timers: runtime-deprecate {un}enroll()

This was never a Very Good API, and generally just left so many open
ends for inconsistent behavior. The "optimization" benefit of this API
is little to none. Makes a starting step towards removing it so that in
the future timers, especially in their async_hooks interactions, can be
simplified.

PR-URL: #18066
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

doc/api/deprecations.md

@@ -856,11 +856,27 @@ Using `assert.fail()` with more than one argument has no benefit over writing an
individual error message. Either use `assert.fail()` with one argument or switch
to one of the other assert methods.

<a id="DEP00XX"></a>
### DEP00XX: timers.enroll()

Type: Runtime

`timers.enroll()` is deprecated. Please use the publicly documented [`setTimeout()`][] or [`setInterval()`][] instead.

<a id="DEP00XX"></a>
### DEP00XX: timers.unenroll()

Type: Runtime

`timers.unenroll()` is deprecated. Please use the publicly documented [`clearTimeout()`][] or [`clearInterval()`][] instead.

[`--pending-deprecation`]: cli.html#cli_pending_deprecation
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
[`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer
[`Buffer.isBuffer()`]: buffer.html#buffer_class_method_buffer_isbuffer_obj
[`clearInterval()`]: timers.html#timers_clearinterval_timeout
[`clearTimeout()`]: timers.html#timers_cleartimeout_timeout
[`EventEmitter.listenerCount(emitter, eventName)`]: events.html#events_eventemitter_listenercount_emitter_eventname
[`Server.connections`]: net.html#net_server_connections
[`Server.getConnections()`]: net.html#net_server_getconnections_callback
@@ -890,6 +906,8 @@ to one of the other assert methods.
[`os.tmpdir()`]: os.html#os_os_tmpdir
[`punycode`]: punycode.html
[`require.extensions`]: modules.html#modules_require_extensions
[`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
[`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
[`tls.CryptoStream`]: tls.html#tls_class_cryptostream
[`tls.SecureContext`]: tls.html#tls_tls_createsecurecontext_options
[`tls.SecurePair`]: tls.html#tls_class_securepair

lib/timers.js

@@ -367,7 +367,7 @@ function reuse(item) {


// Remove a timer. Cancels the timeout and resets the relevant timer properties.
const unenroll = exports.unenroll = function(item) {
function unenroll(item) {
  // Fewer checks may be possible, but these cover everything.
  if (async_hook_fields[kDestroy] > 0 &&
      item &&
@@ -384,21 +384,31 @@ const unenroll = exports.unenroll = function(item) {
  }
  // if active is called later, then we want to make sure not to insert again
  item._idleTimeout = -1;
};
}

exports.unenroll = util.deprecate(unenroll,
                                  'timers.unenroll() is deprecated. ' +
                                  'Please use clearTimeout instead.',
                                  'DEP00XX');


// Make a regular object able to act as a timer by setting some properties.
// This function does not start the timer, see `active()`.
// Using existing objects as timers slightly reduces object overhead.
exports.enroll = function(item, msecs) {
function enroll(item, msecs) {
  item._idleTimeout = timerInternals.validateTimerDuration(msecs);

  // if this item was already in a list somewhere
  // then we should unenroll it from that
  if (item._idleNext) unenroll(item);

  L.init(item);
};
}

exports.enroll = util.deprecate(enroll,
                                'timers.unenroll() is deprecated. ' +
                                'Please use clearTimeout instead.',
                                'DEP00XX');


/*

test/parallel/test-timers-max-duration-warning.js

@@ -11,13 +11,15 @@ function timerNotCanceled() {
}

process.on('warning', common.mustCall((warning) => {
  if (warning.name === 'DeprecationWarning') return;

  const lines = warning.message.split('\n');

  assert.strictEqual(warning.name, 'TimeoutOverflowWarning');
  assert.strictEqual(lines[0], `${OVERFLOW} does not fit into a 32-bit signed` +
                               ' integer.');
  assert.strictEqual(lines.length, 2);
}, 3));
}, 4));


{