Skip to content

Commit f3d9b81

Browse files
committed
doc:Clarify util.aborted resource parameter usage and memory management in docs
1 parent a094a81 commit f3d9b81

File tree

1 file changed

+18
-9
lines changed

1 file changed

+18
-9
lines changed

doc/api/util.md

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2240,39 +2240,48 @@ 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. 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.
22442244
* Returns: {Promise}
22452245
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.
2246+
Listens to abort event on the provided `signal` and returns a promise that resolves when the `signal` is aborted. If `resource` is provided, it weakly references the operation's associated object, so if `resource` is garbage collected before the `signal` aborts, then returned promise shall remain pending. This prevents memory leaks in long-running or non-cancelable operations.
22502247
22512248
```cjs
22522249
const { aborted } = require('node:util');
22532250

2251+
// Obtain an object with an abortable signal, like a custom resource or operation.
22542252
const dependent = obtainSomethingAbortable();
22552253

2254+
// Pass `dependent` as the resource, indicating the promise should only resolve
2255+
// if `dependent` is still in memory when the signal is aborted.
22562256
aborted(dependent.signal, dependent).then(() => {
2257-
// Do something when dependent is aborted.
2257+
2258+
// This code runs when `dependent` is aborted.
2259+
console.log('Dependent resource was aborted.');
22582260
});
22592261

2262+
// Simulate an event that triggers the abort.
22602263
dependent.on('event', () => {
2261-
dependent.abort();
2264+
dependent.abort(); // This will cause the `aborted` promise to resolve.
22622265
});
22632266
```
22642267
22652268
```mjs
22662269
import { aborted } from 'node:util';
22672270

2271+
// Obtain an object with an abortable signal, like a custom resource or operation.
22682272
const dependent = obtainSomethingAbortable();
22692273

2274+
// Pass `dependent` as the resource, indicating the promise should only resolve
2275+
// if `dependent` is still in memory when the signal is aborted.
22702276
aborted(dependent.signal, dependent).then(() => {
2271-
// Do something when dependent is aborted.
2277+
2278+
// This code runs when `dependent` is aborted.
2279+
console.log('Dependent resource was aborted.');
22722280
});
22732281

2282+
// Simulate an event that triggers the abort.
22742283
dependent.on('event', () => {
2275-
dependent.abort();
2284+
dependent.abort(); // This will cause the `aborted` promise to resolve.
22762285
});
22772286
```
22782287

0 commit comments

Comments
 (0)