From 68783ae0b823c584f625c045a134bfff63f4d1b3 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Tue, 9 Jan 2018 13:25:20 -0500 Subject: [PATCH] timers: runtime-deprecate {un}enroll() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-By: James M Snell Reviewed-By: Colin Ihrig Reviewed-By: Luigi Pinca Reviewed-By: Сковорода Никита Андреевич Reviewed-By: Matteo Collina Reviewed-By: Ruben Bridgewater --- doc/api/deprecations.md | 18 ++++++++++++++++++ lib/timers.js | 18 ++++++++++++++---- .../test-timers-max-duration-warning.js | 4 +++- 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 84531ea80d128f..ec7a79a2955593 100644 --- a/doc/api/deprecations.md +++ b/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. + +### DEP00XX: timers.enroll() + +Type: Runtime + +`timers.enroll()` is deprecated. Please use the publicly documented [`setTimeout()`][] or [`setInterval()`][] instead. + + +### 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 diff --git a/lib/timers.js b/lib/timers.js index db43a7491de72f..6e5fda0e5eff2d 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'); /* diff --git a/test/parallel/test-timers-max-duration-warning.js b/test/parallel/test-timers-max-duration-warning.js index 712b56b8d2e082..1fc17b97419193 100644 --- a/test/parallel/test-timers-max-duration-warning.js +++ b/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)); {