timers: deprecate active() and _unrefActive()

Fishrock123 · Fishrock123 · commit 7c80f18c4136 · 2019-03-22T19:47:32.000-07:00
Another nail in the coffin here, farewell ye ol C-style apis. These apis caused numerous other issues that required far too many safeguards. This gets us one step closer to not having to worry about those issues anymore. Refs: nodejs#18066 Refs: nodejs#20298 PR-URL: nodejs#26760 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -2368,6 +2368,38 @@ Type: Runtime
 
 The `_stream_wrap` module is deprecated.
 
+<a id="DEP0126"></a>
+### DEP0126: timers.active()
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/26760
+    description: Runtime deprecation.
+-->
+
+Type: Runtime
+
+The previously undocumented `timers.active()` is deprecated.
+Please use the publicly documented [`timeout.refresh()`][] instead.
+If re-referencing the timeout is necessary, [`timeout.ref()`][] can be used
+with no performance impact since Node.js 10.
+
+<a id="DEP0127"></a>
+### DEP0127: timers._unrefActive()
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/26760
+    description: Runtime deprecation.
+-->
+
+Type: Runtime
+
+The previously undocumented and "private" `timers._unrefActive()` is deprecated.
+Please use the publicly documented [`timeout.refresh()`][] instead.
+If unreferencing the timeout is necessary, [`timeout.unref()`][] can be used
+with no performance impact since Node.js 10.
+
 [`--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
@@ -2423,6 +2455,9 @@ The `_stream_wrap` module is deprecated.
 [`script.createCachedData()`]: vm.html#vm_script_createcacheddata
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
+[`timeout.ref()`]: timers.html#timers_timeout_ref
+[`timeout.refresh()`]: timers.html#timers_timeout_refresh
+[`timeout.unref()`]: timers.html#timers_timeout_unref
 [`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
@@ -304,14 +304,21 @@ function clearImmediate(immediate) {
 }
 
 module.exports = {
-  _unrefActive: unrefActive,
-  active,
   setTimeout,
   clearTimeout,
   setImmediate,
   clearImmediate,
   setInterval,
   clearInterval,
+  _unrefActive: deprecate(
+    unrefActive,
+    'timers._unrefActive() is deprecated.' +
+    ' Please use timeout.refresh() instead.',
+    'DEP0127'),
+  active: deprecate(
+    active,
+    'timers.active() is deprecated. Please use timeout.refresh() instead.',
+    'DEP0126'),
   unenroll: deprecate(
     unenroll,
     'timers.unenroll() is deprecated. Please use clearTimeout instead.',
diff --git a/test/parallel/test-timers-max-duration-warning.js b/test/parallel/test-timers-max-duration-warning.js
@@ -19,7 +19,7 @@ process.on('warning', common.mustCall((warning) => {
   assert.strictEqual(lines[0], `${OVERFLOW} does not fit into a 32-bit signed` +
                                ' integer.');
   assert.strictEqual(lines.length, 2);
-}, 5));
+}, 6));
 
 
 {

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ process.on('warning', common.mustCall((warning) => {`
`19`	`19`	assert.strictEqual(lines[0], `${OVERFLOW} does not fit into a 32-bit signed` +
`20`	`20`	`' integer.');`
`21`	`21`	`assert.strictEqual(lines.length, 2);`
`22`		`-}, 5));`
	`22`	`+}, 6));`
`23`	`23`
`24`	`24`
`25`	`25`	`{`