diff options
author | James M Snell <jasnell@gmail.com> | 2014-12-19 09:53:20 -0800 |
---|---|---|
committer | Timothy J Fontaine <tjfontaine@gmail.com> | 2014-12-22 12:12:48 -0800 |
commit | 48536394c954b2e3e41dcaee3778373ea79e2c25 (patch) | |
tree | 49b815955dae295d687d92c14b6bf1205fc47e31 | |
parent | fd2cb7c611595f1d9095e3087b06939d22238540 (diff) | |
download | node-48536394c954b2e3e41dcaee3778373ea79e2c25.tar.gz |
doc: clarify add/removeListener semantics
Clarify that adding or removing a listener is not idempotent.
RE: #8853
PR: #8911
PR-URL: https://github.com/joyent/node/pull/8911
Signed-off-by: Timothy J Fontaine <tjfontaine@gmail.com>
-rw-r--r-- | doc/api/events.markdown | 18 |
1 files changed, 13 insertions, 5 deletions
diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 07c5b0e2b..2d74b5795 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -33,7 +33,10 @@ added and `'removeListener'` when a listener is removed. ### emitter.addListener(event, listener) ### emitter.on(event, listener) -Adds a listener to the end of the listeners array for the specified event. +Adds a listener to the end of the listeners array for the specified `event`. +No checks are made to see if the `listener` has already been added. Multiple +calls passing the same combination of `event` and `listener` will result in the +`listener` being added multiple times. server.on('connection', function (stream) { console.log('someone connected!'); @@ -65,6 +68,11 @@ Remove a listener from the listener array for the specified event. // ... server.removeListener('connection', callback); +`removeListener` will remove, at most, one instance of a listener from the +listener array. If any single listener has been added multiple times to the +listener array for the specified `event`, then `removeListener` must be called +multiple times to remove each instance. + Returns emitter, so calls can be chained. ### emitter.removeAllListeners([event]) @@ -110,8 +118,8 @@ Return the number of listeners for a given event. * `event` {String} The event name * `listener` {Function} The event handler function -This event is emitted any time someone adds a new listener. It is unspecified -if `listener` is in the list returned by `emitter.listeners(event)`. +This event is emitted any time a listener is added. When this event is triggered, +the listener may not yet have been added to the array of listeners for the `event`. ### Event: 'removeListener' @@ -119,5 +127,5 @@ if `listener` is in the list returned by `emitter.listeners(event)`. * `event` {String} The event name * `listener` {Function} The event handler function -This event is emitted any time someone removes a listener. It is unspecified -if `listener` is in the list returned by `emitter.listeners(event)`. +This event is emitted any time someone removes a listener. When this event is triggered, +the listener may not yet have been removed from the array of listeners for the `event`. |