diff options
author | James M Snell <jasnell@gmail.com> | 2020-05-23 04:11:14 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-06-05 22:21:47 +0300 |
commit | 74ca960aac4600953caacd5f250b11a90bd70ee7 (patch) | |
tree | 241afade93b93c034e23339896e7386f32c3b3e9 /doc/api/globals.md | |
parent | 3e2a3007107b7a100794f4e4adbde19263fc7464 (diff) |
lib: initial experimental AbortController implementation
AbortController impl based very closely on:
https://github.com/mysticatea/abort-controller
Marked experimental.
Not currently used by any of the existing promise apis.
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/33527
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Diffstat (limited to 'doc/api/globals.md')
-rw-r--r-- | doc/api/globals.md | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/doc/api/globals.md b/doc/api/globals.md index 7e6129e9038..78550035cbc 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -17,6 +17,101 @@ The objects listed here are specific to Node.js. There are [built-in objects][] that are part of the JavaScript language itself, which are also globally accessible. +## Class: `AbortController` +<!--YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +<!-- type=global --> + +A utility class used to signal cancelation in selected `Promise`-based APIs. +The API is based on the Web API [`AbortController`][]. + +To use, launch Node.js using the `--experimental-abortcontroller` flag. + +```js +const ac = new AbortController(); + +ac.signal.addEventListener('abort', () => console.log('Aborted!'), + { once: true }); + +ac.abort(); + +console.log(ac.signal.aborted); // Prints True +``` + +### `abortController.abort()` +<!-- YAML +added: REPLACEME +--> + +Triggers the abort signal, causing the `abortController.signal` to emit +the `'abort'` event. + +### `abortController.signal` +<!-- YAML +added: REPLACEME +--> + +* Type: {AbortSignal} + +### Class: `AbortSignal extends EventTarget` +<!-- YAML +added: REPLACEME +--> + +The `AbortSignal` is used to notify observers when the +`abortController.abort()` method is called. + +#### Event: `'abort'` +<!-- YAML +added: REPLACEME +--> + +The `'abort'` event is emitted when the `abortController.abort()` method +is called. The callback is invoked with a single object argument with a +single `type` propety set to `'abort'`: + +```js +const ac = new AbortController(); + +// Use either the onabort property... +ac.signal.onabort = () => console.log('aborted!'); + +// Or the EventTarget API... +ac.signal.addEventListener('abort', (event) => { + console.log(event.type); // Prints 'abort' +}, { once: true }); + +ac.abort(); +``` + +The `AbortController` with which the `AbortSignal` is associated will only +ever trigger the `'abort'` event once. Any event listeners attached to the +`AbortSignal` *should* use the `{ once: true }` option (or, if using the +`EventEmitter` APIs to attach a listener, use the `once()` method) to ensure +that the event listener is removed as soon as the `'abort'` event is handled. +Failure to do so may result in memory leaks. + +#### `abortSignal.aborted` +<!-- YAML +added: REPLACEME +--> + +* Type: {boolean} True after the `AbortController` has been aborted. + +#### `abortSignal.onabort` +<!-- YAML +added: REPLACEME +--> + +* Type: {Function} + +An optional callback function that may be set by user code to be notified +when the `abortController.abort()` function has been called. + ## Class: `Buffer` <!-- YAML added: v0.1.103 @@ -226,6 +321,7 @@ The object that acts as the namespace for all W3C [WebAssembly][webassembly-org] related functionality. See the [Mozilla Developer Network][webassembly-mdn] for usage and compatibility. +[`AbortController`]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController [`TextDecoder`]: util.html#util_class_util_textdecoder [`TextEncoder`]: util.html#util_class_util_textencoder [`URLSearchParams`]: url.html#url_class_urlsearchparams |