nodejs
/
node
mirror of https://github.com/nodejs/node.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: clarify util.aborted resource usage 

PR-URL: https://github.com/nodejs/node/pull/55780
Fixes: https://github.com/nodejs/node/issues/55340
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jason Zhang <xzha4350@gmail.com>
Reviewed-By: Minwoo Jung <nodecorelab@gmail.com>
This commit is contained in:
Kunal Kumar 2024-12-16 03:26:47 +05:30 committed by GitHub
parent bc64114ebf
commit c39875a32d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 25 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/api/util.md
View File

@ -2248,39 +2248,55 @@ added:
> Stability: 1 - Experimental > Stability: 1 - Experimental
* `signal` {AbortSignal} * `signal` {AbortSignal}
* `resource` {Object} Any non-null entity, reference to which is held weakly. * `resource` {Object} Any non-null object tied to the abortable operation and held weakly.
If `resource` is garbage collected before the `signal` aborts, the promise remains pending,
allowing Node.js to stop tracking it.
This helps prevent memory leaks in long-running or non-cancelable operations.
* Returns: {Promise} * Returns: {Promise}
Listens to abort event on the provided `signal` and Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted.
returns a promise that is fulfilled when the `signal` is If `resource` is provided, it weakly references the operation's associated object,
aborted. If the passed `resource` is garbage collected before the `signal` is so if `resource` is garbage collected before the `signal` aborts,
aborted, the returned promise shall remain pending indefinitely. then returned promise shall remain pending.
This prevents memory leaks in long-running or non-cancelable operations.
```cjs ```cjs
const { aborted } = require('node:util'); const { aborted } = require('node:util');
// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable(); const dependent = obtainSomethingAbortable();
// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => { aborted(dependent.signal, dependent).then(() => {
// Do something when dependent is aborted.
// This code runs when `dependent` is aborted.
console.log('Dependent resource was aborted.');
}); });
// Simulate an event that triggers the abort.
dependent.on('event', () => { dependent.on('event', () => {
dependent.abort(); dependent.abort(); // This will cause the `aborted` promise to resolve.
}); });
``` ```
```mjs ```mjs
import { aborted } from 'node:util'; import { aborted } from 'node:util';
// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable(); const dependent = obtainSomethingAbortable();
// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => { aborted(dependent.signal, dependent).then(() => {
// Do something when dependent is aborted.
// This code runs when `dependent` is aborted.
console.log('Dependent resource was aborted.');
}); });
// Simulate an event that triggers the abort.
dependent.on('event', () => { dependent.on('event', () => {
dependent.abort(); dependent.abort(); // This will cause the `aborted` promise to resolve.
}); });
``` ```