From 35742a2d0b3ac1a1eff5ab333b5ae2fef009f00b Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sat, 28 Dec 2024 16:06:52 -0800
Subject: [PATCH] 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: https://github.com/nodejs/node/issues/53266
PR-URL: https://github.com/nodejs/node/pull/56400
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
---
 doc/api/process.md                      | 34 ++++++++++++++
 lib/internal/bootstrap/node.js          |  2 +
 lib/internal/process/per_thread.js      | 14 ++++++
 test/parallel/test-process-ref-unref.js | 60 +++++++++++++++++++++++++
 4 files changed, 110 insertions(+)
 create mode 100644 test/parallel/test-process-ref-unref.js

diff --git a/doc/api/process.md b/doc/api/process.md
index 5eb05bfe48604a..a962ce594f2d36 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -3232,6 +3232,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
@@ -4272,6 +4289,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
index b8c47ee0f54bbd..de2f0e00e14092 100644
--- a/lib/internal/bootstrap/node.js
+++ b/lib/internal/bootstrap/node.js
@@ -178,6 +178,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
index 54fde20e220ce4..0921f583183d71 100644
--- 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;
 
@@ -418,6 +420,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,
   buildAllowedFlags,
@@ -427,4 +439,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
new file mode 100644
index 00000000000000..e9db4d56eefc58
--- /dev/null
+++ 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);
+  });
+});