1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: general improvments to events documentation

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/7480
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Sakthipriyan Vairamani 2016-06-29 23:20:23 +05:30
parent fd02c93d29
commit af4915894b
1 changed files with 28 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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
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
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
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
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
const myEmitter = new MyEmitter();
@ -126,7 +127,7 @@ myEmitter.emit('event');
## Error events
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.
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
```
To guard against crashing the Node.js process, developers can either register
a listener for the `process.on('uncaughtException')` event or use the
[`domain`][] module (_Note, however, that the `domain` module has been
deprecated_).
To guard against crashing the Node.js process, a listener can be registered
on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
can be used. (_Note, however, that the `domain` module has been deprecated_)
```js
const myEmitter = new MyEmitter();
@ -155,8 +155,7 @@ myEmitter.emit('error', new Error('whoops!'));
// Prints: whoops! there was an error
```
As a best practice, developers should always register listeners for the
`'error'` event:
As a best practice, listeners should always be added for the `'error'` events.
```js
const myEmitter = new MyEmitter();
@ -176,15 +175,15 @@ const EventEmitter = require('events');
```
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'
* `eventName` {String|Symbol} The name of the event being listened for
* `listener` {Function} The event handler function
The `EventEmitter` instance will emit it's own `'newListener'` event *before*
a listener is added to it's internal array of listeners.
The `EventEmitter` instance will emit its own `'newListener'` event *before*
a listener is added to its internal array of listeners.
Listeners registered for the `'newListener'` event will be passed the event
name and a reference to the listener being added.
@ -219,7 +218,7 @@ myEmitter.emit('event');
* `eventName` {String|Symbol} The event name
* `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)
@ -251,7 +250,7 @@ precedence over `EventEmitter.defaultMaxListeners`.
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
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()`
methods can be used to temporarily avoid this warning:
@ -301,7 +300,7 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to
### 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`.
@ -319,7 +318,7 @@ console.log(util.inspect(server.listeners('connection')));
### 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
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
`emitter.prependListener()` method can be used as an alternative to add the
@ -352,7 +351,7 @@ myEE.emit('foo');
### 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
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
`emitter.prependOnceListener()` method can be used as an alternative to add the
@ -382,7 +381,7 @@ myEE.emit('foo');
### 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
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)
* `eventName` {string|Symbol} The name of the event.
* `eventName` {String|Symbol} The name of the event.
* `listener` {Function} The callback function
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])
@ -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
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)
@ -485,10 +484,10 @@ myEmitter.emit('event');
Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
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.
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)
@ -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`)
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
[`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
[`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
[`domain`]: domain.html
[`process` object's `uncaughtException` event]: process.html#process_event_uncaughtexception
[stream]: stream.html