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: https://github.com/nodejs/node/pull/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>

1 files changed, 14 insertions, 4 deletions

diff --git a/lib/timers.js b/lib/timers.js
index db43a7491d..6e5fda0e5e 100644
--- a/lib/timers.js
+++ b/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,13 +384,18 @@ 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
@@ -398,7 +403,12 @@ exports.enroll = function(item, msecs) {
   if (item._idleNext) unenroll(item);
 
   L.init(item);
-};
+}
+
+exports.enroll = util.deprecate(enroll,
+                                'timers.unenroll() is deprecated. ' +
+                                'Please use clearTimeout instead.',
+                                'DEP00XX');
 
 
 /*