lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: general improvments to events documentation 

PR-URL: https://github.com/nodejs/node/pull/7480
Reviewed-By: James M Snell <jasnell@gmail.com>
v7.x
Sakthipriyan Vairamani 9 years ago
parent
fd02c93d29
commit
af4915894b
1 changed files with 28 additions and 28 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 56
      doc/api/events.md

56
doc/api/events.md
View File

@ -15,11 +15,11 @@ a [stream][] emits an event whenever data is available to be read.
All objects that emit events are instances of the `EventEmitter` class. These All objects that emit events are instances of the `EventEmitter` class. These
objects expose an `eventEmitter.on()` function that allows one or more objects expose an `eventEmitter.on()` function that allows one or more
Functions to be attached to named events emitted by the object. Typically, functions to be attached to named events emitted by the object. Typically,
event names are camel-cased strings but any valid JavaScript property key event names are camel-cased strings but any valid JavaScript property key
can be used. can be used.
When the `EventEmitter` object emits an event, all of the Functions attached When the `EventEmitter` object emits an event, all of the functions attached
to that specific event are called _synchronously_. Any values returned by the to that specific event are called _synchronously_. Any values returned by the
called listeners are _ignored_ and will be discarded. called listeners are _ignored_ and will be discarded.
@ -109,7 +109,8 @@ myEmitter.emit('event');
``` ```
Using the `eventEmitter.once()` method, it is possible to register a listener Using the `eventEmitter.once()` method, it is possible to register a listener
that is unregistered before it is called. that is called at most once for a particular event. Once the event is emitted,
the listener is unregistered and *then* called.
```js ```js
const myEmitter = new MyEmitter(); const myEmitter = new MyEmitter();
@ -126,7 +127,7 @@ myEmitter.emit('event');
## Error events ## Error events
When an error occurs within an `EventEmitter` instance, the typical action is When an error occurs within an `EventEmitter` instance, the typical action is
for an `'error'` event to be emitted. These are treated as a special case for an `'error'` event to be emitted. These are treated as special cases
within Node.js. within Node.js.
If an `EventEmitter` does _not_ have at least one listener registered for the If an `EventEmitter` does _not_ have at least one listener registered for the
@ -139,10 +140,9 @@ myEmitter.emit('error', new Error('whoops!'));
// Throws and crashes Node.js // Throws and crashes Node.js
``` ```
To guard against crashing the Node.js process, developers can either register To guard against crashing the Node.js process, a listener can be registered
a listener for the `process.on('uncaughtException')` event or use the on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
[`domain`][] module (_Note, however, that the `domain` module has been can be used. (_Note, however, that the `domain` module has been deprecated_)
deprecated_).
```js ```js
const myEmitter = new MyEmitter(); const myEmitter = new MyEmitter();
@ -155,8 +155,7 @@ myEmitter.emit('error', new Error('whoops!'));
// Prints: whoops! there was an error // Prints: whoops! there was an error
``` ```
As a best practice, developers should always register listeners for the As a best practice, listeners should always be added for the `'error'` events.
`'error'` event:
```js ```js
const myEmitter = new MyEmitter(); const myEmitter = new MyEmitter();
@ -176,15 +175,15 @@ const EventEmitter = require('events');
``` ```
All EventEmitters emit the event `'newListener'` when new listeners are All EventEmitters emit the event `'newListener'` when new listeners are
added and `'removeListener'` when a listener is removed. added and `'removeListener'` when existing listeners are removed.
### Event: 'newListener' ### Event: 'newListener'
* `eventName` {String|Symbol} The name of the event being listened for * `eventName` {String|Symbol} The name of the event being listened for
* `listener` {Function} The event handler function * `listener` {Function} The event handler function
The `EventEmitter` instance will emit it's own `'newListener'` event *before* The `EventEmitter` instance will emit its own `'newListener'` event *before*
a listener is added to it's internal array of listeners. a listener is added to its internal array of listeners.
Listeners registered for the `'newListener'` event will be passed the event Listeners registered for the `'newListener'` event will be passed the event
name and a reference to the listener being added. name and a reference to the listener being added.
@ -219,7 +218,7 @@ myEmitter.emit('event');
* `eventName` {String|Symbol} The event name * `eventName` {String|Symbol} The event name
* `listener` {Function} The event handler function * `listener` {Function} The event handler function
The `'removeListener'` event is emitted *after* a listener is removed. The `'removeListener'` event is emitted *after* the `listener` is removed.
### EventEmitter.listenerCount(emitter, eventName) ### EventEmitter.listenerCount(emitter, eventName)
@ -251,7 +250,7 @@ precedence over `EventEmitter.defaultMaxListeners`.
Note that this is not a hard limit. The `EventEmitter` instance will allow Note that this is not a hard limit. The `EventEmitter` instance will allow
more listeners to be added but will output a trace warning to stderr indicating more listeners to be added but will output a trace warning to stderr indicating
that a `possible EventEmitter memory leak` has been detected. For any single that a "possible EventEmitter memory leak" has been detected. For any single
`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()` `EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
methods can be used to temporarily avoid this warning: methods can be used to temporarily avoid this warning:
@ -301,7 +300,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to
### emitter.listenerCount(eventName) ### emitter.listenerCount(eventName)
* `eventName` {Value} The name of the event being listened for * `eventName` {String|Symbol} The name of the event being listened for
Returns the number of listeners listening to the event named `eventName`. Returns the number of listeners listening to the event named `eventName`.
@ -319,7 +318,7 @@ console.log(util.inspect(server.listeners('connection')));
### emitter.on(eventName, listener) ### emitter.on(eventName, listener)
* `eventName` {string|Symbol} The name of the event. * `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function * `listener` {Function} The callback function
Adds the `listener` function to the end of the listeners array for the Adds the `listener` function to the end of the listeners array for the
@ -334,7 +333,7 @@ server.on('connection', (stream) => {
}); });
``` ```
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The By default, event listeners are invoked in the order they are added. The
`emitter.prependListener()` method can be used as an alternative to add the `emitter.prependListener()` method can be used as an alternative to add the
@ -352,7 +351,7 @@ myEE.emit('foo');
### emitter.once(eventName, listener) ### emitter.once(eventName, listener)
* `eventName` {string|Symbol} The name of the event. * `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function * `listener` {Function} The callback function
Adds a **one time** `listener` function for the event named `eventName`. The Adds a **one time** `listener` function for the event named `eventName`. The
@ -364,7 +363,7 @@ server.once('connection', (stream) => {
}); });
``` ```
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The By default, event listeners are invoked in the order they are added. The
`emitter.prependOnceListener()` method can be used as an alternative to add the `emitter.prependOnceListener()` method can be used as an alternative to add the
@ -382,7 +381,7 @@ myEE.emit('foo');
### emitter.prependListener(eventName, listener) ### emitter.prependListener(eventName, listener)
* `eventName` {string|Symbol} The name of the event. * `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function * `listener` {Function} The callback function
Adds the `listener` function to the *beginning* of the listeners array for the Adds the `listener` function to the *beginning* of the listeners array for the
@ -397,11 +396,11 @@ server.prependListener('connection', (stream) => {
}); });
``` ```
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
### emitter.prependOnceListener(eventName, listener) ### emitter.prependOnceListener(eventName, listener)
* `eventName` {string|Symbol} The name of the event. * `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function * `listener` {Function} The callback function
Adds a **one time** `listener` function for the event named `eventName` to the Adds a **one time** `listener` function for the event named `eventName` to the
@ -414,7 +413,7 @@ server.prependOnceListener('connection', (stream) => {
}); });
``` ```
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
### emitter.removeAllListeners([eventName]) ### emitter.removeAllListeners([eventName])
@ -424,7 +423,7 @@ Note that it is bad practice to remove listeners added elsewhere in the code,
particularly when the `EventEmitter` instance was created by some other particularly when the `EventEmitter` instance was created by some other
component or module (e.g. sockets or file streams). component or module (e.g. sockets or file streams).
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
### emitter.removeListener(eventName, listener) ### emitter.removeListener(eventName, listener)
@ -485,10 +484,10 @@ myEmitter.emit('event');
Because listeners are managed using an internal array, calling this will Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called, being removed. This will not impact the order in which listeners are called,
but it will means that any copies of the listener array as returned by but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated. the `emitter.listeners()` method will need to be recreated.
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
### emitter.setMaxListeners(n) ### emitter.setMaxListeners(n)
@ -499,7 +498,7 @@ The `emitter.setMaxListeners()` method allows the limit to be modified for this
specific `EventEmitter` instance. The value can be set to `Infinity` (or `0`) specific `EventEmitter` instance. The value can be set to `Infinity` (or `0`)
to indicate an unlimited number of listeners. to indicate an unlimited number of listeners.
Returns a reference to the `EventEmitter` so calls can be chained. Returns a reference to the `EventEmitter`, so that calls can be chained.
[`net.Server`]: net.html#net_class_net_server [`net.Server`]: net.html#net_class_net_server
[`fs.ReadStream`]: fs.html#fs_class_fs_readstream [`fs.ReadStream`]: fs.html#fs_class_fs_readstream
@ -507,4 +506,5 @@ Returns a reference to the `EventEmitter` so calls can be chained.
[`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
[`emitter.listenerCount()`]: #events_emitter_listenercount_eventname [`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
[`domain`]: domain.html [`domain`]: domain.html
[`process` object's `uncaughtException` event]: process.html#process_event_uncaughtexception
[stream]: stream.html [stream]: stream.html

Write Preview
Loading…
Cancel
Save