process: add process.ref() and process.unref() methods

The `process.ref(...)` and `process.unref(...)` methods are intended to replace the use of `ref()` and `unref()` methods defined directly on individual API objects. The existing `ref()` and `unref()` methods will be marked as legacy and won't be removed but new APIs should use `process.ref()` and `process.unref()` instead. Refs: #53266 PR-URL: #56400 Backport-PR-URL: #56571 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
aduh95 · Feb 4, 2025 · Dec 29, 2024 · Jan 10, 2025 · Jan 12, 2025 · Feb 4, 2025
commit 396a830df7f95e47d65ef9817121b555dc198009
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -3221,6 +3221,23 @@ const { ppid } = require('node:process');
 console.log(`The parent process is pid ${ppid}`);
 ```
 
+## `process.ref(maybeRefable)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `maybeRefable` {any} An object that may be "refable".
+
+An object is "refable" if it implements the Node.js "Refable protocol".
+Specifically, this means that the object implements the `Symbol.for('node:ref')`
+and `Symbol.for('node:unref')` methods. "Ref'd" objects will keep the Node.js
+event loop alive, while "unref'd" objects will not. Historically, this was
+implemented by using `ref()` and `unref()` methods directly on the objects.
+This pattern, however, is being deprecated in favor of the "Refable protocol"
+in order to better support Web Platform API types whose APIs cannot be modified
+to add `ref()` and `unref()` methods but still need to support that behavior.
+
 ## `process.release`
 
 <!-- YAML
@@ -4261,6 +4278,23 @@ console.log(
 
 In [`Worker`][] threads, `process.umask(mask)` will throw an exception.
 
+## `process.unref(maybeRefable)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `maybeUnfefable` {any} An object that may be "unref'd".
+
+An object is "unrefable" if it implements the Node.js "Refable protocol".
+Specifically, this means that the object implements the `Symbol.for('node:ref')`
+and `Symbol.for('node:unref')` methods. "Ref'd" objects will keep the Node.js
+event loop alive, while "unref'd" objects will not. Historically, this was
+implemented by using `ref()` and `unref()` methods directly on the objects.
+This pattern, however, is being deprecated in favor of the "Refable protocol"
+in order to better support Web Platform API types whose APIs cannot be modified
+to add `ref()` and `unref()` methods but still need to support that behavior.
+
 ## `process.uptime()`
 
 <!-- YAML

diff --git a/lib/internal/bootstrap/node.js b/lib/internal/bootstrap/node.js
@@ -181,6 +181,8 @@ const rawMethods = internalBinding('process_methods');
   process.availableMemory = rawMethods.availableMemory;
   process.kill = wrapped.kill;
   process.exit = wrapped.exit;
+  process.ref = perThreadSetup.ref;
+  process.unref = perThreadSetup.unref;
 
   let finalizationMod;
   ObjectDefineProperty(process, 'finalization', {

diff --git a/lib/internal/process/per_thread.js b/lib/internal/process/per_thread.js
@@ -13,6 +13,7 @@ const {
   ArrayPrototypeSplice,
   BigUint64Array,
   Float64Array,
+  FunctionPrototypeCall,
   NumberMAX_SAFE_INTEGER,
   ObjectDefineProperty,
   ObjectFreeze,
@@ -26,6 +27,7 @@ const {
   StringPrototypeReplace,
   StringPrototypeSlice,
   Symbol,
+  SymbolFor,
   SymbolIterator,
 } = primordials;
 
@@ -422,6 +424,16 @@ function toggleTraceCategoryState(asyncHooksEnabled) {
 
 const { arch, platform, version } = process;
 
+function ref(maybeRefable) {
+  const fn = maybeRefable?.[SymbolFor('node:ref')] || maybeRefable?.ref;
+  if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);
+}
+
+function unref(maybeRefable) {
+  const fn = maybeRefable?.[SymbolFor('node:unref')] || maybeRefable?.unref;
+  if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);
+}
+
 module.exports = {
   toggleTraceCategoryState,
   assert,
@@ -432,4 +444,6 @@ module.exports = {
   arch,
   platform,
   version,
+  ref,
+  unref,
 };
diff --git a/test/parallel/test-process-ref-unref.js b/test/parallel/test-process-ref-unref.js
@@ -0,0 +1,60 @@
+'use strict';
+
+require('../common');
+
+const {
+  describe,
+  it,
+} = require('node:test');
+
+const {
+  strictEqual,
+} = require('node:assert');
+
+class Foo {
+  refCalled = 0;
+  unrefCalled = 0;
+  ref() {
+    this.refCalled++;
+  }
+  unref() {
+    this.unrefCalled++;
+  }
+}
+
+class Foo2 {
+  refCalled = 0;
+  unrefCalled = 0;
+  [Symbol.for('node:ref')]() {
+    this.refCalled++;
+  }
+  [Symbol.for('node:unref')]() {
+    this.unrefCalled++;
+  }
+}
+
+describe('process.ref/unref work as expected', () => {
+  it('refs...', () => {
+    // Objects that implement the new Symbol-based API
+    // just work.
+    const foo1 = new Foo();
+    const foo2 = new Foo2();
+    process.ref(foo1);
+    process.unref(foo1);
+    process.ref(foo2);
+    process.unref(foo2);
+    strictEqual(foo1.refCalled, 1);
+    strictEqual(foo1.unrefCalled, 1);
+    strictEqual(foo2.refCalled, 1);
+    strictEqual(foo2.unrefCalled, 1);
+
+    // Objects that implement the legacy API also just work.
+    const i = setInterval(() => {}, 1000);
+    strictEqual(i.hasRef(), true);
+    process.unref(i);
+    strictEqual(i.hasRef(), false);
+    process.ref(i);
+    strictEqual(i.hasRef(), true);
+    clearInterval(i);
+  });
+});