event: Document the mutability of listeners()

nodejs · Jun 15, 2012 · e72addc · e72addc
1 parent 032fc42
commit e72addc
Showing 1 changed file with 18 additions and 2 deletions.
diff --git 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.