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

doc: sort events alphabetically 

Reorders, with minimal contextual duplication, the events documentation
alphabetically.

PR-URL: https://github.com/nodejs/node/pull/3662
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
process-exit-stdio-flushing
Tristian Flanagan 9 years ago
committed by James M Snell
parent
084e540397
commit
6009c4b159
1 changed files with 89 additions and 91 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 180
      doc/api/events.markdown

180
doc/api/events.markdown
View File

@ -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

Write Preview
Loading…
Cancel
Save