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

timers: allow timers to be used as primitives #34017

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions doc/api/timers.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,21 @@ Calling `timeout.unref()` creates an internal timer that will wake the Node.js
event loop. Creating too many of these can adversely impact performance
of the Node.js application.

### `timeout[Symbol.toPrimitive]()`
<!-- YAML
added: REPLACEME
-->

* Returns: {integer} number that can be used to reference this `timeout`

Coerce a `Timeout` to a primitive, a primitive will be generated that
can be used to clear the `Timeout`.
The generated number can only be used in the same thread where timeout
was created. Therefore to use it cross [`worker_threads`][] it has
to first be passed to a correct thread.
This allows enhanced compatibility with browser's `setTimeout()`, and
`setInterval()` implementations.

## Scheduling timers

A timer in Node.js is an internal construct that calls a given function after
Expand Down Expand Up @@ -346,3 +361,4 @@ const timersPromises = require('timers/promises');
[`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
[`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
[`util.promisify()`]: util.html#util_util_promisify_original
[`worker_threads`]: worker_threads.html
4 changes: 4 additions & 0 deletions lib/internal/timers.js
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ const {
const async_id_symbol = Symbol('asyncId');
const trigger_async_id_symbol = Symbol('triggerId');

const kHasPrimitive = Symbol('kHasPrimitive');

const {
ERR_INVALID_CALLBACK,
ERR_OUT_OF_RANGE
Expand Down Expand Up @@ -185,6 +187,7 @@ function Timeout(callback, after, args, isRepeat, isRefed) {
if (isRefed)
incRefCount();
this[kRefed] = isRefed;
this[kHasPrimitive] = false;

initAsyncResource(this, 'Timeout');
}
Expand Down Expand Up @@ -639,6 +642,7 @@ module.exports = {
Timeout,
Immediate,
kRefed,
kHasPrimitive,
initAsyncResource,
setUnrefTimeout,
getTimerDuration,
Expand Down
28 changes: 28 additions & 0 deletions lib/timers.js
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,10 @@
'use strict';

const {
ObjectCreate,
MathTrunc,
Object,
SymbolToPrimitive
} = primordials;

const {
Expand All @@ -41,6 +43,7 @@ const {
kRefCount
},
kRefed,
kHasPrimitive,
getTimerDuration,
timerListMap,
timerListQueue,
Expand All @@ -66,13 +69,21 @@ const {
emitDestroy
} = require('internal/async_hooks');

// This stores all the known timer async ids to allow users to clearTimeout and
// clearInterval using those ids, to match the spec and the rest of the web
// platform.
const knownTimersById = ObjectCreate(null);

// Remove a timer. Cancels the timeout and resets the relevant timer properties.
function unenroll(item) {
if (item._destroyed)
return;

item._destroyed = true;

if (item[kHasPrimitive])
delete knownTimersById[item[async_id_symbol]];

// Fewer checks may be possible, but these cover everything.
if (destroyHooksExist() && item[async_id_symbol] !== undefined)
emitDestroy(item[async_id_symbol]);
Expand Down Expand Up @@ -163,6 +174,14 @@ function clearTimeout(timer) {
if (timer && timer._onTimeout) {
timer._onTimeout = null;
unenroll(timer);
return;
}
if (typeof timer === 'number' || typeof timer === 'string') {
lundibundi marked this conversation as resolved.
Show resolved Hide resolved
const timerInstance = knownTimersById[timer];
if (timerInstance !== undefined) {
timerInstance._onTimeout = null;
unenroll(timerInstance);
}
}
}

Expand Down Expand Up @@ -208,6 +227,15 @@ Timeout.prototype.close = function() {
return this;
};

Timeout.prototype[SymbolToPrimitive] = function() {
const id = this[async_id_symbol];
if (!this[kHasPrimitive]) {
this[kHasPrimitive] = true;
knownTimersById[id] = this;
}
return id;
};

function setImmediate(callback, arg1, arg2, arg3) {
validateCallback(callback);

Expand Down
29 changes: 29 additions & 0 deletions test/parallel/test-timers-to-primitive.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
'use strict';

const common = require('../common');
const assert = require('assert');

[
setTimeout(common.mustNotCall(), 1),
setInterval(common.mustNotCall(), 1),
].forEach((timeout) => {
assert.strictEqual(Number.isNaN(+timeout), false);
assert.strictEqual(+timeout, timeout[Symbol.toPrimitive]());
assert.strictEqual(`${timeout}`, timeout[Symbol.toPrimitive]().toString());
assert.deepStrictEqual(Object.keys({ [timeout]: timeout }), [`${timeout}`]);
clearTimeout(+timeout);
});

{
// Check that clearTimeout works with number id.
const timeout = setTimeout(common.mustNotCall(), 1);
const id = +timeout;
clearTimeout(id);
}

{
// Check that clearTimeout works with string id.
const timeout = setTimeout(common.mustNotCall(), 1);
const id = `${timeout}`;
clearTimeout(id);
}