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 <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>

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));
 
 
 {