Skip to content
Browse files

event: Document the mutability of listeners()

  • Loading branch information...
1 parent 032fc42 commit e72addcf8e72e6a32a7561588aa3d73b30defc7b @isaacs committed Jun 14, 2012
Showing with 18 additions and 2 deletions.
  1. +18 −2 doc/api/events.markdown
View
20 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.

0 comments on commit e72addc

Please sign in to comment.
Something went wrong with that request. Please try again.