diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 9dc384a850543f..c14994e5bf4a59 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -36,67 +36,68 @@ a stack trace and exit the program. All EventEmitters emit the event `'newListener'` when new listeners are added and `'removeListener'` when a listener is removed. -### emitter.addListener(event, listener) -### emitter.on(event, listener) +### Inheriting from 'EventEmitter' -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. +Inheriting from `EventEmitter` is no different from inheriting from any other +constructor function. For example: - server.on('connection', function (stream) { - console.log('someone connected!'); - }); + 'use strict'; + const util = require('util'); + const EventEmitter = require('events'); -Returns emitter, so calls can be chained. + function MyEventEmitter() { + // Initialize necessary properties from `EventEmitter` in this instance + EventEmitter.call(this); + } -### emitter.once(event, listener) + // Inherit functions from `EventEmitter`'s prototype + util.inherits(MyEventEmitter, EventEmitter); -Adds a **one time** listener for the event. This listener is -invoked only the next time the event is fired, after which -it is removed. +### Class Method: EventEmitter.listenerCount(emitter, event) - server.once('connection', function (stream) { - console.log('Ah, we have our first user!'); - }); + Stability: 0 - Deprecated: Use [emitter.listenerCount][] instead. -Returns emitter, so calls can be chained. +Returns the number of listeners for a given event. -### emitter.removeListener(event, listener) +### Event: 'newListener' -Removes a listener from the listener array for the specified event. -**Caution**: changes array indices in the listener array behind the listener. +* `event` {String} The event name +* `listener` {Function} The event handler function - var callback = function(stream) { - console.log('someone connected!'); - }; - server.on('connection', callback); - // ... - server.removeListener('connection', callback); +This event is emitted *before* a listener is added. When this event is +triggered, the listener has not been added to the array of listeners for the +`event`. Any listeners added to the event `name` in the newListener event +callback will be added *before* the listener that is in the process of being +added. -`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. +### Event: 'removeListener' -Returns emitter, so calls can be chained. +* `event` {String} The event name +* `listener` {Function} The event handler function -### emitter.removeAllListeners([event]) +This event is emitted *after* a listener is removed. When this event is +triggered, the listener has been removed from the array of listeners for the +`event`. -Removes all listeners, or those of the specified event. It's not a good idea to -remove listeners that were added elsewhere in the code, especially when it's on -an emitter that you didn't create (e.g. sockets or file streams). +### EventEmitter.defaultMaxListeners -Returns emitter, so calls can be chained. +[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) sets the +maximum on a per-instance basis. +This class property lets you set it for *all* `EventEmitter` instances, +current and future, effective immediately. Use with care. -### emitter.setMaxListeners(n) +Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) +still has precedence over `EventEmitter.defaultMaxListeners`. -By default EventEmitters will print a warning if more than 10 listeners are -added for a particular event. This is a useful default which helps finding -memory leaks. Obviously not all Emitters should be limited to 10. This function -allows that to be increased. Set to `Infinity` (or `0`) for unlimited. +### emitter.addListener(event, listener) -Returns emitter, so calls can be chained. +Alias for `emitter.on(event, listener)`. + +### emitter.emit(event[, arg1][, arg2][, ...]) + +Calls each of the listeners in order with the supplied arguments. + +Returns `true` if event had listeners, `false` otherwise. ### emitter.getMaxListeners() @@ -113,16 +114,11 @@ while not being irresponsible and setting a too big number. emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0)); }); -### EventEmitter.defaultMaxListeners - -[`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) sets the -maximum on a per-instance basis. -This class property lets you set it for *all* `EventEmitter` instances, -current and future, effective immediately. Use with care. +### emitter.listenerCount(type) -Note that [`emitter.setMaxListeners(n)`](#events_emitter_setmaxlisteners_n) -still has precedence over `EventEmitter.defaultMaxListeners`. +* `type` {Value} The type of event +Returns the number of listeners listening to the `type` of event. ### emitter.listeners(event) @@ -133,63 +129,65 @@ Returns a copy of the array of listeners for the specified event. }); console.log(util.inspect(server.listeners('connection'))); // [ [Function] ] +### emitter.on(event, listener) -### emitter.emit(event[, arg1][, arg2][, ...]) - -Calls each of the listeners in order with the supplied arguments. - -Returns `true` if event had listeners, `false` otherwise. - - -### emitter.listenerCount(type) - -* `type` {Value} The type of 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. -Returns the number of listeners listening to the `type` of event. + server.on('connection', function (stream) { + console.log('someone connected!'); + }); -### Class Method: EventEmitter.listenerCount(emitter, event) +Returns emitter, so calls can be chained. - Stability: 0 - Deprecated: Use [emitter.listenerCount][] instead. +### emitter.once(event, listener) -Returns the number of listeners for a given event. +Adds a **one time** listener for the event. This listener is +invoked only the next time the event is fired, after which +it is removed. -### Event: 'newListener' + server.once('connection', function (stream) { + console.log('Ah, we have our first user!'); + }); -* `event` {String} The event name -* `listener` {Function} The event handler function +Returns emitter, so calls can be chained. -This event is emitted *before* a listener is added. When this event is -triggered, the listener has not been added to the array of listeners for the -`event`. Any listeners added to the event `name` in the newListener event -callback will be added *before* the listener that is in the process of being -added. +### emitter.removeAllListeners([event]) +Removes all listeners, or those of the specified event. It's not a good idea to +remove listeners that were added elsewhere in the code, especially when it's on +an emitter that you didn't create (e.g. sockets or file streams). -### Event: 'removeListener' +Returns emitter, so calls can be chained. -* `event` {String} The event name -* `listener` {Function} The event handler function +### emitter.removeListener(event, listener) -This event is emitted *after* a listener is removed. When this event is -triggered, the listener has been removed from the array of listeners for the -`event`. +Removes a listener from the listener array for the specified event. +**Caution**: changes array indices in the listener array behind the listener. -### Inheriting from 'EventEmitter' + var callback = function(stream) { + console.log('someone connected!'); + }; + server.on('connection', callback); + // ... + server.removeListener('connection', callback); -Inheriting from `EventEmitter` is no different from inheriting from any other -constructor function. For example: +`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. - 'use strict'; - const util = require('util'); - const EventEmitter = require('events'); +Returns emitter, so calls can be chained. - function MyEventEmitter() { - // Initialize necessary properties from `EventEmitter` in this instance - EventEmitter.call(this); - } +### emitter.setMaxListeners(n) - // Inherit functions from `EventEmitter`'s prototype - util.inherits(MyEventEmitter, EventEmitter); +By default EventEmitters will print a warning if more than 10 listeners are +added for a particular event. This is a useful default which helps finding +memory leaks. Obviously not all Emitters should be limited to 10. This function +allows that to be increased. Set to `Infinity` (or `0`) for unlimited. +Returns emitter, so calls can be chained. [emitter.listenerCount]: #events_emitter_listenercount_type