8000 doc: cleanup events.md structure · nodejs/node@186ad24 · GitHub
[go: up one dir, main page]
Skip to content

Commit 186ad24

Browse files
jasnelldanielleadams
jasnell
authored and
danielleadams
committed
doc: cleanup events.md structure
Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #36100 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
1 parent 47397ff commit 186ad24

File tree

2 files changed

+114
-110
lines changed

2 files changed

+114
-110
lines changed

‎doc/api/deprecations.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -717,7 +717,7 @@ changes:
717717

718718
Type: Documentation-only
719719

720-
The [`EventEmitter.listenerCount(emitter, eventName)`][] API is
720+
The [`events.listenerCount(emitter, eventName)`][] API is
721721
deprecated. Please use [`emitter.listenerCount(eventName)`][] instead.
722722

723723
### DEP0034: `fs.exists(path, callback)`
@@ -2712,7 +2712,6 @@ runtime warning results no matter where the `"exports"` usage occurs.
27122712
[`Buffer.isBuffer()`]: buffer.md#buffer_static_method_buffer_isbuffer_obj
27132713
[`Cipher`]: crypto.md#crypto_class_cipher
27142714
[`Decipher`]: crypto.md#crypto_class_decipher
2715-
[`EventEmitter.listenerCount(emitter, eventName)`]: events.md#events_eventemitter_listenercount_emitter_eventname
27162715
[`REPLServer.clearBufferedCommand()`]: repl.md#repl_replserver_clearbufferedcommand
27172716
[`ReadStream.open()`]: fs.md#fs_class_fs_readstream
27182717
[`Server.getConnections()`]: net.md#net_server_getconnections_callback
@@ -2741,6 +2740,7 @@ runtime warning results no matter where the `"exports"` usage occurs.
27412740
[`domain`]: domain.md
27422741
[`ecdh.setPublicKey()`]: crypto.md#crypto_ecdh_setpublickey_publickey_encoding
27432742
[`emitter.listenerCount(eventName)`]: events.md#events_emitter_listenercount_eventname
2743+
[`events.listenerCount(emitter, eventName)`]: events.md#events_events_listenercount_emitter_eventname
27442744
[`fs.FileHandle`]: fs.md#fs_class_filehandle
27452745
[`fs.access()`]: fs.md#fs_fs_access_path_mode_callback
27462746
[`fs.createReadStream()`]: fs.md#fs_fs_createreadstream_path_options

‎doc/api/events.md‎

Lines changed: 112 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -158,11 +158,13 @@ myEmitter.emit('error', new Error('whoops!'));
158158
```
159159

160160
It is possible to monitor `'error'` events without consuming the emitted error
161-
by installing a listener using the symbol `errorMonitor`.
161+
by installing a listener using the symbol `events.errorMonitor`.
162162

163163
```js
164-
const myEmitter = new MyEmitter();
165-
myEmitter.on(EventEmitter.errorMonitor, (err) => {
164+
const { EventEmitter, errorMonitor } = require('events');
165+
166+
const myEmitter = new EventEmitter();
167+
myEmitter.on(errorMonitor, (err) => {
166168
MyMonitoringTool.log(err);
167169
});
168170
myEmitter.emit('error', new Error('whoops!'));
@@ -205,12 +207,13 @@ ee2.on('something', async (value) => {
205207
ee2[Symbol.for('nodejs.rejection')] = console.log;
206208
```
207209

208-
Setting `EventEmitter.captureRejections = true` will change the default for all
210+
Setting `events.captureRejections = true` will change the default for all
209211
new instances of `EventEmitter`.
210212

211213
```js
212-
EventEmitter.captureRejections = true;
213-
const ee1 = new EventEmitter();
214+
const events = require('events');
215+
events.captureRejections = true;
216+
const ee1 = new events.EventEmitter();
214217
ee1.on('something', async (value) => {
215218
throw new Error('kaboom');
216219
});
@@ -306,106 +309,6 @@ changes:
306309

307310
The `'removeListener'` event is emitted *after* the `listener` is removed.
308311

309-
### `EventEmitter.listenerCount(emitter, eventName)`
310-
<!-- YAML
311-
added: v0.9.12
312-
deprecated: v3.2.0
313-
-->
314-
315-
> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
316-
317-
* `emitter` {EventEmitter} The emitter to query
318-
* `eventName` {string|symbol} The event name
319-
320-
A class method that returns the number of listeners for the given `eventName`
321-
registered on the given `emitter`.
322-
3262 323-
```js
324-
const myEmitter = new EventEmitter();
325-
myEmitter.on('event', () => {});
326-
myEmitter.on('event', () => {});
327-
console.log(EventEmitter.listenerCount(myEmitter, 'event'));
328-
// Prints: 2
329-
```
330-
331-
### `EventEmitter.defaultMaxListeners`
332-
<!-- YAML
333-
added: v0.11.2
334-
-->
335-
336-
By default, a maximum of `10` listeners can be registered for any single
337-
event. This limit can be changed for individual `EventEmitter` instances
338-
using the [`emitter.setMaxListeners(n)`][] method. To change the default
339-
for *all* `EventEmitter` instances, the `EventEmitter.defaultMaxListeners`
340-
property can be used. If this value is not a positive number, a `RangeError`
341-
is thrown.
342-
343-
Take caution when setting the `EventEmitter.defaultMaxListeners` because the
344-
change affects *all* `EventEmitter` instances, including those created before
345-
the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has
346-
precedence over `EventEmitter.defaultMaxListeners`.
347-
348-
This is not a hard limit. The `EventEmitter` instance will allow
349-
more listeners to be added but will output a trace warning to stderr indicating
350-
that a "possible EventEmitter memory leak" has been detected. For any single
351-
`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
352-
methods can be used to temporarily avoid this warning:
353-
354-
```js
355-
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
356-
emitter.once('event', () => {
357-
// do stuff
358-
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
359-
});
360-
```
361-
362-
The [`--trace-warnings`][] command-line flag can be used to display the
363-
stack trace for such warnings.
364-
365-
The emitted warning can be inspected with [`process.on('warning')`][] and will
366-
have the additional `emitter`, `type` and `count` properties, referring to
367-
the event emitter instance, the event’s name and the number of attached
368-
listeners, respectively.
369-
Its `name` property is set to `'MaxListenersExceededWarning'`.
370-
371-
### `EventEmitter.errorMonitor`
372-
<!-- YAML
373-
added:
374-
- v13.6.0
375-
- v12.17.0
376-
--> D966 ;
377-
378-
This symbol shall be used to install a listener for only monitoring `'error'`
379-
events. Listeners installed using this symbol are called before the regular
380-
`'error'` listeners are called.
381-
382-
Installing a listener using this symbol does not change the behavior once an
383-
`'error'` event is emitted, therefore the process will still crash if no
384-
regular `'error'` listener is installed.
385-
386-
### `EventEmitter.setMaxListeners(n[, ...eventTargets])`
387-
<!-- YAML
388-
added: v15.3.0
389-
-->
390-
391-
* `n` {number} A non-negative number. The maximum number of listeners per
392-
`EventTarget` event.
393-
* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget}
394-
or {EventEmitter} instances. If none are specified, `n` is set as the default
395-
max for all newly created {EventTarget} and {EventEmitter} objects.
396-
397-
```js
398-
const {
399-
setMaxListeners,
400-
EventEmitter
401-
} = require('events');
402-
403-
const target = new EventTarget();
404-
const emitter = new EventEmitter();
405-
406-
setMaxListeners(5, target, emitter);
407-
```
408-
409312
### `emitter.addListener(eventName, listener)`
410313
<!-- YAML
411314
added: v0.1.26
@@ -496,7 +399,7 @@ added: v1.0.0
496399

497400
Returns the current max listener value for the `EventEmitter` which is either
498401
set by [`emitter.setMaxListeners(n)`][] or defaults to
499-
[`EventEmitter.defaultMaxListeners`][].
402+
[`events.defaultMaxListeners`][].
500403

501404
### `emitter.listenerCount(eventName)`
502405
<!-- YAML
@@ -852,6 +755,61 @@ class MyClass extends EventEmitter {
852755
}
853756
```
854757

758+
## `events.defaultMaxListeners`
759+
<!-- YAML
760+
added: v0.11.2
761+
-->
762+
763+
By default, a maximum of `10` listeners can be registered for any single
764+
event. This limit can be changed for individual `EventEmitter` instances
765+
using the [`emitter.setMaxListeners(n)`][] method. To change the default
766+
for *all* `EventEmitter` instances, the `events.defaultMaxListeners`
767+
property can be used. If this value is not a positive number, a `RangeError`
768+
is thrown.
769+
770+
Take caution when setting the `events.defaultMaxListeners` because the
771+
change affects *all* `EventEmitter` instances, including those created before
772+
the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has
773+
precedence over `events.defaultMaxListeners`.
774+
775+
This is not a hard limit. The `EventEmitter` instance will allow
776+
more listeners to be added but will output a trace warning to stderr indicating
777+
that a "possible EventEmitter memory leak" has been detected. For any single
778+
`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()`
779+
methods can be used to temporarily avoid this warning:
780+
781+
```js
782+
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
783+
emitter.once('event', () => {
784+
// do stuff
785+
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
786+
});
787+
```
788+
789+
The [`--trace-warnings`][] command-line flag can be used to display the
790+
stack trace for such warnings.
791+
792+
The emitted warning can be inspected with [`process.on('warning')`][] and will
793+
have the additional `emitter`, `type` and `count` properties, referring to
794+
the event emitter instance, the event’s name and the number of attached
795+
listeners, respectively.
796+
Its `name` property is set to `'MaxListenersExceededWarning'`.
797+
798+
## `events.errorMonitor`
799+
<!-- YAML
800+
added:
801+
- v13.6.0
802+
- v12.17.0
803+
-->
804+
805+
This symbol shall be used to install a listener for only monitoring `'error'`
806+
events. Listeners installed using this symbol are called before the regular
807+
`'error'` listeners are called.
808+
809+
Installing a listener using this symbol does not change the behavior once an
810+
`'error'` event is emitted, therefore the process will still crash if no
811+
regular `'error'` listener is installed.
812+
855813
## `events.getEventListeners(emitterOrTarget, eventName)`
856814
<!-- YAML
857815
added:
@@ -1061,6 +1019,29 @@ Value: `Symbol.for('nodejs.rejection')`
10611019

10621020
See how to write a custom [rejection handler][rejection].
10631021

1022+
## `events.listenerCount(emitter, eventName)`
1023+
<!-- YAML
1024+
added: v0.9.12
1025+
deprecated: v3.2.0
1026+
-->
1027+
1028+
> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead.
1029+
1030+
* `emitter` {EventEmitter} The emitter to query
1031+
* `eventName` {string|symbol} The event name
1032+
1033+
A class method that returns the number of listeners for the given `eventName`
1034+
registered on the given `emitter`.
1035+
1036+
```js
1037+
const { EventEmitter, listenerCount } = require('events');
1038+
const myEmitter = new EventEmitter();
1039+
myEmitter.on('event', () => {});
1040+
myEmitter.on('event', () => {});
1041+
console.log(listenerCount(myEmitter, 'event'));
1042+
// Prints: 2
1043+
```
1044+
10641045
## `events.on(emitter, eventName[, options])`
10651046
<!-- YAML
10661047
added:
@@ -1128,6 +1109,29 @@ const ac = new AbortController();
11281109
process.nextTick(() => ac.abort());
11291110
```
11301111

1112+
## `events.setMaxListeners(n[, ...eventTargets])`
1113+
<!-- YAML
1114+
added: REPLACEME
1115+
-->
1116+
1117+
* `n` {number} A non-negative number. The maximum number of listeners per
1118+
`EventTarget` event.
1119+
* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget}
1120+
or {EventEmitter} instances. If none are specified, `n` is set as the default
1121+
max for all newly created {EventTarget} and {EventEmitter} objects.
1122+
1123+
```js
1124+
const {
1125+
setMaxListeners,
1126+
EventEmitter
1127+
} = require('events');
1128+
1129+
const target = new EventTarget();
1130+
const emitter = new EventEmitter();
1131+
1132+
setMaxListeners(5, target, emitter);
1133+
```
1134+
11311135
<a id="event-target-and-event-api"></a>
11321136
## `EventTarget` and `Event` API
11331137
<!-- YAML
@@ -1606,14 +1610,14 @@ to the `EventTarget`.
16061610

16071611
[WHATWG-EventTarget]: https://dom.spec.whatwg.org/#interface-eventtarget
16081612
[`--trace-warnings`]: cli.md#cli_trace_warnings
1609-
[`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
16101613
[`EventTarget` Web API]: https://dom.spec.whatwg.org/#eventtarget
16111614
[`EventTarget` error handling]: #events_eventtarget_error_handling
16121615
[`Event` Web API]: https://dom.spec.whatwg.org/#event
16131616
[`domain`]: domain.md
16141617
[`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
16151618
[`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener
16161619
[`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
1620+
[`events.defaultMaxListeners`]: #events_events_defaultmaxlisteners
16171621
[`fs.ReadStream`]: fs.md#fs_class_fs_readstream
16181622
[`net.Server`]: net.md#net_class_net_server
16191623
[`process.on('warning')`]: process.md#process_event_warning

0 commit comments

Comments
 (0)
0