Skip to content

Commit c83d690

Browse files
committed
doc: clarify util.aborted resource usage
1 parent a094a81 commit c83d690

File tree

1 file changed

+25
-9
lines changed

1 file changed

+25
-9
lines changed

doc/api/util.md

+25-9
Original file line numberDiff line numberDiff line change
@@ -2240,39 +2240,55 @@ added:
22402240
> Stability: 1 - Experimental
22412241
22422242
* `signal` {AbortSignal}
2243-
* `resource` {Object} Any non-null entity, reference to which is held weakly.
2243+
* `resource` {Object} Any non-null object tied to the abortable operation and held weakly.
2244+
If `resource` is garbage collected before the `signal` aborts, the promise remains pending,
2245+
allowing Node.js to stop tracking it.
2246+
This helps prevent memory leaks in long-running or non-cancelable operations.
22442247
* Returns: {Promise}
22452248
2246-
Listens to abort event on the provided `signal` and
2247-
returns a promise that is fulfilled when the `signal` is
2248-
aborted. If the passed `resource` is garbage collected before the `signal` is
2249-
aborted, the returned promise shall remain pending indefinitely.
2249+
Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted.
2250+
If `resource` is provided, it weakly references the operation's associated object,
2251+
so if `resource` is garbage collected before the `signal` aborts,
2252+
then returned promise shall remain pending.
2253+
This prevents memory leaks in long-running or non-cancelable operations.
22502254
22512255
```cjs
22522256
const { aborted } = require('node:util');
22532257

2258+
// Obtain an object with an abortable signal, like a custom resource or operation.
22542259
const dependent = obtainSomethingAbortable();
22552260

2261+
// Pass `dependent` as the resource, indicating the promise should only resolve
2262+
// if `dependent` is still in memory when the signal is aborted.
22562263
aborted(dependent.signal, dependent).then(() => {
2257-
// Do something when dependent is aborted.
2264+
2265+
// This code runs when `dependent` is aborted.
2266+
console.log('Dependent resource was aborted.');
22582267
});
22592268

2269+
// Simulate an event that triggers the abort.
22602270
dependent.on('event', () => {
2261-
dependent.abort();
2271+
dependent.abort(); // This will cause the `aborted` promise to resolve.
22622272
});
22632273
```
22642274
22652275
```mjs
22662276
import { aborted } from 'node:util';
22672277

2278+
// Obtain an object with an abortable signal, like a custom resource or operation.
22682279
const dependent = obtainSomethingAbortable();
22692280

2281+
// Pass `dependent` as the resource, indicating the promise should only resolve
2282+
// if `dependent` is still in memory when the signal is aborted.
22702283
aborted(dependent.signal, dependent).then(() => {
2271-
// Do something when dependent is aborted.
2284+
2285+
// This code runs when `dependent` is aborted.
2286+
console.log('Dependent resource was aborted.');
22722287
});
22732288

2289+
// Simulate an event that triggers the abort.
22742290
dependent.on('event', () => {
2275-
dependent.abort();
2291+
dependent.abort(); // This will cause the `aborted` promise to resolve.
22762292
});
22772293
```
22782294

0 commit comments

Comments
 (0)