Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

lib: add aborted() utility function #46494

Merged
merged 26 commits into from Feb 7, 2023
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 32 additions & 0 deletions doc/api/util.md
Expand Up @@ -1989,6 +1989,38 @@ const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]);
```

## `util.aborted(signal, resource)`

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental

* `signal` {AbortSignal}
* `resource` {any} Any non-null entity
jasnell marked this conversation as resolved.
Show resolved Hide resolved
* Returns: {Promise}

Listens to abort event on the provided `signal` and returns a promise which is
resolved if an abort event is triggered. The function is dependent on the `resource`
entity and will be resolved only if the `resource` is not removed
from memory, when `resource` goes out of memory the
jasnell marked this conversation as resolved.
Show resolved Hide resolved
promise shall remain pending and any event listeners attached to the `signal`
will be removed.

```js
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
const { aborted } = require('util');
debadree25 marked this conversation as resolved.
Show resolved Hide resolved

const ac = new AbortController();
const dependent = {};
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

aborted(ac.signal, dependent).then(() => {
// Do something when the abort event is triggered.
});

doSomething(dependent, ac.signal); // Can trigger the abort event
```

## `util.types`

<!-- YAML
Expand Down
21 changes: 21 additions & 0 deletions lib/internal/abort_controller.js
Expand Up @@ -13,6 +13,7 @@ const {
Symbol,
SymbolToStringTag,
WeakRef,
PromiseResolve,
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
} = primordials;

const {
Expand All @@ -22,11 +23,13 @@ const {
kTrustEvent,
kNewListener,
kRemoveListener,
kWeakHandler,
} = require('internal/event_target');
const {
customInspectSymbol,
kEnumerableProperty,
kEmptyObject,
createDeferredPromise,
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
} = require('internal/util');
const { inspect } = require('internal/util/inspect');
const {
Expand All @@ -39,6 +42,8 @@ const {

const {
validateUint32,
validateAbortSignal: abortSignalValidator,
validateObject,
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
} = require('internal/validators');

const {
Expand Down Expand Up @@ -357,6 +362,21 @@ function transferableAbortController() {
return AbortController[kMakeTransferable]();
}

/**
* @param {AbortSignal} signal
* @param {any} resource
* @returns {Promise<void>}
*/
async function aborted(signal, resource) {
abortSignalValidator(signal, 'signal');
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
validateObject(resource, 'resource', { nullable: false, allowFunction: true, allowArray: true });
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
if (signal.aborted)
return PromiseResolve();
const abortPromise = createDeferredPromise();
signal.addEventListener('abort', abortPromise.resolve, { [kWeakHandler]: resource, once: true });
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
aduh95 marked this conversation as resolved.
Show resolved Hide resolved
return abortPromise.promise;
}

ObjectDefineProperties(AbortController.prototype, {
signal: kEnumerableProperty,
abort: kEnumerableProperty,
Expand All @@ -377,4 +397,5 @@ module.exports = {
ClonedAbortSignal,
transferableAbortSignal,
transferableAbortController,
aborted,
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
};
3 changes: 3 additions & 0 deletions lib/util.js
Expand Up @@ -393,6 +393,9 @@ module.exports = {
get transferableAbortController() {
return lazyAbortController().transferableAbortController;
},
get aborted() {
return lazyAbortController().aborted;
},
types
};

Expand Down
44 changes: 44 additions & 0 deletions test/parallel/test-aborted-util.js
@@ -0,0 +1,44 @@
// Flags: --expose-gc
'use strict';

const common = require('../common');
const { aborted } = require('util');
const assert = require('assert');
const { getEventListeners } = require('events');

{
// Test aborted works when provided a resource
const ac = new AbortController();
aborted(ac.signal, {}).then(common.mustCall());
ac.abort();
assert.strictEqual(ac.signal.aborted, true);
assert.strictEqual(getEventListeners(ac.signal, 'abort').length, 0);
}

{
// Test aborted with gc cleanup
const ac = new AbortController();
aborted(ac.signal, {}).then(common.mustNotCall());
setImmediate(() => {
global.gc();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does GC accomplish here? That the aborted() promise is collected before abort() is called?

I don't know if that kind of GC observability is a good thing. Maybe it works now but GC changes can break such patterns. Looks fragile.

Copy link
Member Author

@debadree25 debadree25 Feb 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

basically want to cleanup the empty object to check if the listener is removed when the resource is cleaned by the gc, unsure of any other ways to test this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's just for testing, then it's probably fine. I mean, it could still break in the future but we can revisit if and when that happens.

I'd advise against documenting that behavior though. It's simply not very robust.

ac.abort();
assert.strictEqual(ac.signal.aborted, true);
assert.strictEqual(getEventListeners(ac.signal, 'abort').length, 0);
});
}

{
// Fails with error if not provided abort signal
const sig = new EventTarget();
assert.rejects(aborted(sig, {}), {
name: 'TypeError',
});
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
}

{
// Fails if not provided a resource
const ac = new AbortController();
assert.rejects(aborted(ac.signal, null), {
name: 'TypeError',
});
debadree25 marked this conversation as resolved.
Show resolved Hide resolved
}
debadree25 marked this conversation as resolved.
Show resolved Hide resolved