diff --git a/doc/api/events.markdown b/doc/api/events.markdown index fed957d34509..b9be5dc5aad3 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -64,6 +64,9 @@ Remove a listener from the listener array for the specified event. Removes all listeners, or those of the specified event. +Note that this will **invalidate** any arrays that have previously been +returned by `emitter.listeners(event)`. + ### emitter.setMaxListeners(n) @@ -75,14 +78,27 @@ that to be increased. Set to zero for unlimited. ### emitter.listeners(event) -Returns an array of listeners for the specified event. This array can be -manipulated, e.g. to remove listeners. +Returns an array of listeners for the specified event. server.on('connection', function (stream) { console.log('someone connected!'); }); console.log(util.inspect(server.listeners('connection'))); // [ [Function] ] +This array **may** be a mutable reference to the same underlying list of +listeners that is used by the event subsystem. However, certain +actions (specifically, removeAllListeners) will invalidate this +reference. + +If you would like to get a copy of the listeners at a specific point in +time that is guaranteed not to change, make a copy, for example by doing +`emitter.listeners(event).slice(0)`. + +In a future release of node, this behavior **may** change to always +return a copy, for consistency. In your programs, please do not rely on +being able to modify the EventEmitter listeners using array methods. +Always use the 'on' method to add new listeners. + ### emitter.emit(event, [arg1], [arg2], [...]) Execute each of the listeners in order with the supplied arguments.