From 83f8c4c57dcd63a524312403b5bd87e09d1851c6 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 12 Nov 2020 10:02:12 -0800 Subject: [PATCH] doc: cleanup events.md structure Signed-off-by: James M Snell PR-URL: https://github.com/nodejs/node/pull/36100 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Rich Trott --- doc/api/deprecations.md | 4 +- doc/api/events.md | 221 ++++++++++++++++++++-------------------- 2 files changed, 115 insertions(+), 110 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 7e1cd082602fbc..c37f6748deb9ab 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -710,7 +710,7 @@ changes: Type: Documentation-only -The [`EventEmitter.listenerCount(emitter, eventName)`][] API is +The [`events.listenerCount(emitter, eventName)`][] API is deprecated. Please use [`emitter.listenerCount(eventName)`][] instead. ### DEP0034: `fs.exists(path, callback)` @@ -2665,7 +2665,6 @@ Use `fs.rm(path, { recursive: true, force: true })` instead. [`Buffer.isBuffer()`]: buffer.md#buffer_static_method_buffer_isbuffer_obj [`Cipher`]: crypto.md#crypto_class_cipher [`Decipher`]: crypto.md#crypto_class_decipher -[`EventEmitter.listenerCount(emitter, eventName)`]: events.md#events_eventemitter_listenercount_emitter_eventname [`REPLServer.clearBufferedCommand()`]: repl.md#repl_replserver_clearbufferedcommand [`ReadStream.open()`]: fs.md#fs_class_fs_readstream [`Server.connections`]: net.md#net_server_connections @@ -2695,6 +2694,7 @@ Use `fs.rm(path, { recursive: true, force: true })` instead. [`domain`]: domain.md [`ecdh.setPublicKey()`]: crypto.md#crypto_ecdh_setpublickey_publickey_encoding [`emitter.listenerCount(eventName)`]: events.md#events_emitter_listenercount_eventname +[`events.listenerCount(emitter, eventName)`]: events.md#events_events_listenercount_emitter_eventname [`fs.FileHandle`]: fs.md#fs_class_filehandle [`fs.access()`]: fs.md#fs_fs_access_path_mode_callback [`fs.createReadStream()`]: fs.md#fs_fs_createreadstream_path_options diff --git a/doc/api/events.md b/doc/api/events.md index 39fcf8cf0f7dc3..8d01f4851d7050 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -158,11 +158,13 @@ myEmitter.emit('error', new Error('whoops!')); ``` It is possible to monitor `'error'` events without consuming the emitted error -by installing a listener using the symbol `errorMonitor`. +by installing a listener using the symbol `events.errorMonitor`. ```js -const myEmitter = new MyEmitter(); -myEmitter.on(EventEmitter.errorMonitor, (err) => { +const { EventEmitter, errorMonitor } = require('events'); + +const myEmitter = new EventEmitter(); +myEmitter.on(errorMonitor, (err) => { MyMonitoringTool.log(err); }); myEmitter.emit('error', new Error('whoops!')); @@ -205,12 +207,13 @@ ee2.on('something', async (value) => { ee2[Symbol.for('nodejs.rejection')] = console.log; ``` -Setting `EventEmitter.captureRejections = true` will change the default for all +Setting `events.captureRejections = true` will change the default for all new instances of `EventEmitter`. ```js -EventEmitter.captureRejections = true; -const ee1 = new EventEmitter(); +const events = require('events'); +events.captureRejections = true; +const ee1 = new events.EventEmitter(); ee1.on('something', async (value) => { throw new Error('kaboom'); }); @@ -306,106 +309,6 @@ changes: The `'removeListener'` event is emitted *after* the `listener` is removed. -### `EventEmitter.listenerCount(emitter, eventName)` - - -> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. - -* `emitter` {EventEmitter} The emitter to query -* `eventName` {string|symbol} The event name - -A class method that returns the number of listeners for the given `eventName` -registered on the given `emitter`. - -```js -const myEmitter = new EventEmitter(); -myEmitter.on('event', () => {}); -myEmitter.on('event', () => {}); -console.log(EventEmitter.listenerCount(myEmitter, 'event')); -// Prints: 2 -``` - -### `EventEmitter.defaultMaxListeners` - - -By default, a maximum of `10` listeners can be registered for any single -event. This limit can be changed for individual `EventEmitter` instances -using the [`emitter.setMaxListeners(n)`][] method. To change the default -for *all* `EventEmitter` instances, the `EventEmitter.defaultMaxListeners` -property can be used. If this value is not a positive number, a `RangeError` -is thrown. - -Take caution when setting the `EventEmitter.defaultMaxListeners` because the -change affects *all* `EventEmitter` instances, including those created before -the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has -precedence over `EventEmitter.defaultMaxListeners`. - -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 -`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()` -methods can be used to temporarily avoid this warning: - -```js -emitter.setMaxListeners(emitter.getMaxListeners() + 1); -emitter.once('event', () => { - // do stuff - emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0)); -}); -``` - -The [`--trace-warnings`][] command-line flag can be used to display the -stack trace for such warnings. - -The emitted warning can be inspected with [`process.on('warning')`][] and will -have the additional `emitter`, `type` and `count` properties, referring to -the event emitter instance, the event’s name and the number of attached -listeners, respectively. -Its `name` property is set to `'MaxListenersExceededWarning'`. - -### `EventEmitter.errorMonitor` - - -This symbol shall be used to install a listener for only monitoring `'error'` -events. Listeners installed using this symbol are called before the regular -`'error'` listeners are called. - -Installing a listener using this symbol does not change the behavior once an -`'error'` event is emitted, therefore the process will still crash if no -regular `'error'` listener is installed. - -### `EventEmitter.setMaxListeners(n[, ...eventTargets])` - - -* `n` {number} A non-negative number. The maximum number of listeners per - `EventTarget` event. -* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget} - or {EventEmitter} instances. If none are specified, `n` is set as the default - max for all newly created {EventTarget} and {EventEmitter} objects. - -```js -const { - setMaxListeners, - EventEmitter -} = require('events'); - -const target = new EventTarget(); -const emitter = new EventEmitter(); - -setMaxListeners(5, target, emitter); -``` - ### `emitter.addListener(eventName, listener)` + +By default, a maximum of `10` listeners can be registered for any single +event. This limit can be changed for individual `EventEmitter` instances +using the [`emitter.setMaxListeners(n)`][] method. To change the default +for *all* `EventEmitter` instances, the `events.defaultMaxListeners` +property can be used. If this value is not a positive number, a `RangeError` +is thrown. + +Take caution when setting the `events.defaultMaxListeners` because the +change affects *all* `EventEmitter` instances, including those created before +the change is made. However, calling [`emitter.setMaxListeners(n)`][] still has +precedence over `events.defaultMaxListeners`. + +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 +`EventEmitter`, the `emitter.getMaxListeners()` and `emitter.setMaxListeners()` +methods can be used to temporarily avoid this warning: + +```js +emitter.setMaxListeners(emitter.getMaxListeners() + 1); +emitter.once('event', () => { + // do stuff + emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0)); +}); +``` + +The [`--trace-warnings`][] command-line flag can be used to display the +stack trace for such warnings. + +The emitted warning can be inspected with [`process.on('warning')`][] and will +have the additional `emitter`, `type` and `count` properties, referring to +the event emitter instance, the event’s name and the number of attached +listeners, respectively. +Its `name` property is set to `'MaxListenersExceededWarning'`. + +## `events.errorMonitor` + + +This symbol shall be used to install a listener for only monitoring `'error'` +events. Listeners installed using this symbol are called before the regular +`'error'` listeners are called. + +Installing a listener using this symbol does not change the behavior once an +`'error'` event is emitted, therefore the process will still crash if no +regular `'error'` listener is installed. + ## `events.getEventListeners(emitterOrTarget, eventName)` + +> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. + +* `emitter` {EventEmitter} The emitter to query +* `eventName` {string|symbol} The event name + +A class method that returns the number of listeners for the given `eventName` +registered on the given `emitter`. + +```js +const { EventEmitter, listenerCount } = require('events'); +const myEmitter = new EventEmitter(); +myEmitter.on('event', () => {}); +myEmitter.on('event', () => {}); +console.log(listenerCount(myEmitter, 'event')); +// Prints: 2 +``` + ## `events.on(emitter, eventName[, options])` + +* `n` {number} A non-negative number. The maximum number of listeners per + `EventTarget` event. +* `...eventsTargets` {EventTarget[]|EventEmitter[]} Zero or more {EventTarget} + or {EventEmitter} instances. If none are specified, `n` is set as the default + max for all newly created {EventTarget} and {EventEmitter} objects. + +```js +const { + setMaxListeners, + EventEmitter +} = require('events'); + +const target = new EventTarget(); +const emitter = new EventEmitter(); + +setMaxListeners(5, target, emitter); +``` + + ## `EventTarget` and `Event` API