Skip to content

Commit

Permalink
doc:clarify util.aborted resource parameter usage
Browse files Browse the repository at this point in the history
  • Loading branch information
KunalKumar-1 committed Nov 8, 2024
1 parent a094a81 commit af461d0
Showing 1 changed file with 25 additions and 9 deletions.
34 changes: 25 additions & 9 deletions doc/api/util.md
Original file line number Diff line number Diff line change
Expand Up @@ -2240,39 +2240,55 @@ added:
> Stability: 1 - Experimental
* `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}
Listens to abort event on the provided `signal` and
returns a promise that is fulfilled when the `signal` is
aborted. If the passed `resource` is garbage collected before the `signal` is
aborted, the returned promise shall remain pending indefinitely.
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.
```cjs
const { aborted } = require('node:util');

// Obtain an object with an abortable signal, like a custom resource or operation.
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(() => {
// 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.abort();
dependent.abort(); // This will cause the `aborted` promise to resolve.
});
```
```mjs
import { aborted } from 'node:util';

// Obtain an object with an abortable signal, like a custom resource or operation.
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(() => {
// 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.abort();
dependent.abort(); // This will cause the `aborted` promise to resolve.
});
```
Expand Down

0 comments on commit af461d0

Please sign in to comment.