timers: allow Immediates to be unrefed

Refactor Immediates handling to allow for them to be unrefed, similar
to setTimeout, but without extra handles.

Document the new `immediate.ref()` and `immediate.unref()` methods.

Add SetImmediateUnref on the C++ side.

PR-URL: https://github.com/nodejs/node/pull/18139
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

3 files changed, 53 insertions, 0 deletions

diff --git a/test/addons-napi/test_uv_loop/test_uv_loop.cc b/test/addons-napi/test_uv_loop/test_uv_loop.cc
index 44819f72bb..048e25af9d 100644
--- a/test/addons-napi/test_uv_loop/test_uv_loop.cc
+++ b/test/addons-napi/test_uv_loop/test_uv_loop.cc
@@ -24,6 +24,15 @@ void* SetImmediate(napi_env env, T&& cb) {
 
     assert(cb() != nullptr);
   });
+  // Idle handle is needed only to stop the event loop from blocking in poll.
+  uv_idle_t* idle = new uv_idle_t;
+  uv_idle_init(loop, idle);
+  uv_idle_start(idle, [](uv_idle_t* idle) {
+    uv_close(reinterpret_cast<uv_handle_t*>(idle), [](uv_handle_t* handle) {
+      delete reinterpret_cast<uv_check_t*>(handle);
+    });
+  });
+
   return nullptr;
 }
 
diff --git a/test/parallel/test-timers-immediate-unref-simple.js b/test/parallel/test-timers-immediate-unref-simple.js
new file mode 100644
index 0000000000..6849746032
--- /dev/null
+++ b/test/parallel/test-timers-immediate-unref-simple.js
@@ -0,0 +1,7 @@
+'use strict';
+
+const common = require('../common');
+
+// This immediate should not execute as it was unrefed
+// and nothing else is keeping the event loop alive
+setImmediate(common.mustNotCall()).unref();
diff --git a/test/parallel/test-timers-immediate-unref.js b/test/parallel/test-timers-immediate-unref.js
new file mode 100644
index 0000000000..5b56eb7e1d
--- /dev/null
+++ b/test/parallel/test-timers-immediate-unref.js
@@ -0,0 +1,37 @@
+'use strict';
+
+const common = require('../common');
+const Countdown = require('../common/countdown');
+
+// This immediate should execute as it was unrefed and refed again.
+// It also confirms that unref/ref are chainable.
+setImmediate(common.mustCall(firstStep)).ref().unref().unref().ref();
+
+function firstStep() {
+  const countdown =
+    new Countdown(2, common.mustCall(() => setImmediate(secondStep)));
+  // Unrefed setImmediate executes if it was unrefed but something else keeps
+  // the loop open
+  setImmediate(() => countdown.dec()).unref();
+  setTimeout(() => countdown.dec(), 50);
+}
+
+function secondStep() {
+  // clearImmediate works just fine with unref'd immediates
+  const immA = setImmediate(() => {
+    clearImmediate(immA);
+    clearImmediate(immB);
+    // this should not keep the event loop open indefinitely
+    // or do anything else weird
+    immA.ref();
+    immB.ref();
+  }).unref();
+  const immB = setImmediate(common.mustNotCall()).unref();
+  setImmediate(common.mustCall(finalStep));
+}
+
+function finalStep() {
+  // This immediate should not execute as it was unrefed
+  // and nothing else is keeping the event loop alive
+  setImmediate(common.mustNotCall()).unref();
+}