Skip to content

Commit

Permalink
doc:Clarify util.aborted resource parameter usage and memory manageme…
Browse files Browse the repository at this point in the history
…nt in docs
  • Loading branch information
KunalKumar-1 committed Nov 8, 2024
1 parent a094a81 commit f3d9b81
Showing 1 changed file with 18 additions and 9 deletions.
27 changes: 18 additions & 9 deletions doc/api/util.md
Original file line number Diff line number Diff line change
Expand Up @@ -2240,39 +2240,48 @@ 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.

Check failure on line 2258 in doc/api/util.md

View workflow job for this annotation

GitHub Actions / lint-js-and-md

Expected indentation of 2 spaces but found 0
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 f3d9b81

Please sign in to comment.