From 68a266571831d4cf3e13f40762d7bdd0389de634 Mon Sep 17 00:00:00 2001
From: ishabi <ilyasshabi94@gmail.com>
Date: Thu, 30 Oct 2025 23:49:22 +0100
Subject: [PATCH] src: add locksCounters() to monitor Web Locks usage

---
 doc/api/globals.md                           |   4 +
 doc/api/process.md                           |  55 +++++
 doc/api/worker_threads.md                    |   6 +-
 lib/internal/bootstrap/node.js               |   1 +
 lib/internal/process/per_thread.js           |  19 ++
 src/node_locks.cc                            |  51 ++++-
 src/node_locks.h                             |  18 ++
 src/node_process_methods.cc                  |  23 ++
 test/parallel/test-process-locks-counters.js | 226 +++++++++++++++++++
 9 files changed, 401 insertions(+), 2 deletions(-)
 create mode 100644 test/parallel/test-process-locks-counters.js

diff --git a/doc/api/globals.md b/doc/api/globals.md
index 5521f1446cb13c..c99f9b891c9b8f 100644
--- a/doc/api/globals.md
+++ b/doc/api/globals.md
@@ -839,6 +839,9 @@ navigator.locks.request('shared_resource', { mode: 'shared' }, async (lock) => {
 
 See [`worker_threads.locks`][] for detailed API documentation.
 
+Use [`process.locksCounters()`][] to monitor lock acquisitions, contention, and
+queue sizes across the process.
+
 ## Class: `PerformanceEntry`
 
 <!-- YAML
@@ -1376,6 +1379,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [`localStorage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
 [`module`]: modules.md#module
 [`perf_hooks.performance`]: perf_hooks.md#perf_hooksperformance
+[`process.locksCounters()`]: process.md#processlockscounters
 [`process.nextTick()`]: process.md#processnexttickcallback-args
 [`process` object]: process.md#process
 [`require()`]: modules.md#requireid
diff --git a/doc/api/process.md b/doc/api/process.md
index 3eaa17be6144dd..edd6a2c91262be 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -3735,6 +3735,60 @@ console.log(resourceUsage());
 */
 ```
 
+## `process.locksCounters()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object} Web Locks usage statistics for the current process.
+  * `totalAborts` {bigint} Lock requests aborted (either `ifAvailable` could not
+    be granted, or the callback rejected/threw).
+  * `totalSteals` {bigint} Lock requests granted with `{ steal: true }`.
+  * `totalExclusiveAcquired` {bigint} Total exclusive locks acquired.
+  * `totalSharedAcquired` {bigint} Total shared locks acquired.
+  * `holdersExclusive` {number} Exclusive locks currently held.
+  * `holdersShared` {number} Shared locks currently held.
+  * `pendingExclusive` {number} Exclusive lock requests currently queued.
+  * `pendingShared` {number} Shared lock requests currently queued.
+
+Returns an object containing lock usage metrics for the current process to provide visibility into
+[`navigator.locks`][] (Web Locks API).
+
+```mjs
+import process from 'node:process';
+import { locks } from 'node:worker_threads';
+
+const before = process.locksCounters();
+
+await locks.request('my_resource', async () => {
+  const current = process.locksCounters();
+  console.log(current.holdersExclusive); // 1
+  console.log(current.totalExclusiveAcquired - before.totalExclusiveAcquired); // 1n
+});
+
+const after = process.locksCounters();
+console.log(after.holdersExclusive); // 0 (released)
+console.log(after.totalExclusiveAcquired - before.totalExclusiveAcquired); // 1n (cumulative)
+```
+
+```cjs
+const process = require('node:process');
+const { locks } = require('node:worker_threads');
+
+const before = process.locksCounters();
+
+locks.request('my_resource', async () => {
+  const current = process.locksCounters();
+  console.log(current.holdersExclusive); // 1
+  console.log(current.totalExclusiveAcquired - before.totalExclusiveAcquired); // 1n
+}).then(() => {
+  const after = process.locksCounters();
+  console.log(after.holdersExclusive); // 0 (released)
+  console.log(after.totalExclusiveAcquired - before.totalExclusiveAcquired); // 1n (cumulative)
+});
+```
+
 ## `process.send(message[, sendHandle[, options]][, callback])`
 
 <!-- YAML
@@ -4535,6 +4589,7 @@ cases:
 [`module.getSourceMapsSupport()`]: module.md#modulegetsourcemapssupport
 [`module.isBuiltin(id)`]: module.md#moduleisbuiltinmodulename
 [`module.setSourceMapsSupport()`]: module.md#modulesetsourcemapssupportenabled-options
+[`navigator.locks`]: globals.md#navigatorlocks
 [`net.Server`]: net.md#class-netserver
 [`net.Socket`]: net.md#class-netsocket
 [`os.constants.dlopen`]: os.md#dlopen-constants
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
index b44df3da70a95f..37c7af991e176c 100644
--- a/doc/api/worker_threads.md
+++ b/doc/api/worker_threads.md
@@ -781,7 +781,10 @@ added: v24.5.0
 An instance of a [`LockManager`][LockManager] that can be used to coordinate
 access to resources that may be shared across multiple threads within the same
 process. The API mirrors the semantics of the
-[browser `LockManager`][]
+[browser `LockManager`][].
+
+Use [`process.locksCounters()`][] to monitor lock acquisitions, contention, and
+queue sizes across the process.
 
 ### Class: `Lock`
 
@@ -2249,6 +2252,7 @@ thread spawned will spawn another until the application crashes.
 [`process.env`]: process.md#processenv
 [`process.execArgv`]: process.md#processexecargv
 [`process.exit()`]: process.md#processexitcode
+[`process.locksCounters()`]: process.md#processlockscounters
 [`process.stderr`]: process.md#processstderr
 [`process.stdin`]: process.md#processstdin
 [`process.stdout`]: process.md#processstdout
diff --git a/lib/internal/bootstrap/node.js b/lib/internal/bootstrap/node.js
index 09ec85a25c1e73..a11eb28609ccbc 100644
--- a/lib/internal/bootstrap/node.js
+++ b/lib/internal/bootstrap/node.js
@@ -172,6 +172,7 @@ const rawMethods = internalBinding('process_methods');
   process.cpuUsage = wrapped.cpuUsage;
   process.threadCpuUsage = wrapped.threadCpuUsage;
   process.resourceUsage = wrapped.resourceUsage;
+  process.locksCounters = wrapped.locksCounters;
   process.memoryUsage = wrapped.memoryUsage;
   process.constrainedMemory = rawMethods.constrainedMemory;
   process.availableMemory = rawMethods.availableMemory;
diff --git a/lib/internal/process/per_thread.js b/lib/internal/process/per_thread.js
index da2ba93e7e93ae..2596a495941736 100644
--- a/lib/internal/process/per_thread.js
+++ b/lib/internal/process/per_thread.js
@@ -110,6 +110,7 @@ function wrapProcessMethods(binding) {
     threadCpuUsage: _threadCpuUsage,
     memoryUsage: _memoryUsage,
     rss,
+    locksCounters: _locksCounters,
     resourceUsage: _resourceUsage,
     loadEnvFile: _loadEnvFile,
     execve: _execve,
@@ -349,6 +350,23 @@ function wrapProcessMethods(binding) {
     };
   }
 
+  const locksCountersBuffer = new Float64Array(8);
+  const locksCountersBigIntView = new BigUint64Array(locksCountersBuffer.buffer, 0, 4);
+
+  function locksCounters() {
+    _locksCounters(locksCountersBuffer);
+    return {
+      totalAborts: locksCountersBigIntView[0],
+      totalSteals: locksCountersBigIntView[1],
+      totalExclusiveAcquired: locksCountersBigIntView[2],
+      totalSharedAcquired: locksCountersBigIntView[3],
+      holdersExclusive: locksCountersBuffer[4],
+      holdersShared: locksCountersBuffer[5],
+      pendingExclusive: locksCountersBuffer[6],
+      pendingShared: locksCountersBuffer[7],
+    };
+  }
+
   /**
    * Loads the `.env` file to process.env.
    * @param {string | URL | Buffer | undefined} path
@@ -372,6 +390,7 @@ function wrapProcessMethods(binding) {
     kill,
     exit,
     execve,
+    locksCounters,
     loadEnvFile,
   };
 }
diff --git a/src/node_locks.cc b/src/node_locks.cc
index 9c871569c4d46b..92100d76bf9a1a 100644
--- a/src/node_locks.cc
+++ b/src/node_locks.cc
@@ -319,6 +319,10 @@ void LockManager::ProcessQueue(Environment* env) {
      *    remove later
      */
     if (if_available_request) {
+      {
+        Mutex::ScopedLock scoped_lock(mutex_);
+        counters.total_aborts++;
+      }
       Local<Value> null_arg = Null(isolate);
       Local<Value> callback_result;
       {
@@ -456,7 +460,17 @@ void LockManager::ProcessQueue(Environment* env) {
                                grantable_request->released_promise());
     {
       Mutex::ScopedLock scoped_lock(mutex_);
-      held_locks_[grantable_request->name()].push_back(granted_lock);
+      auto& resource_locks = held_locks_[grantable_request->name()];
+      resource_locks.push_back(granted_lock);
+      if (grantable_request->steal()) {
+        counters.total_steals++;
+      }
+
+      if (grantable_request->mode() == Lock::Mode::Exclusive) {
+        counters.total_exclusive_acquired++;
+      } else {
+        counters.total_shared_acquired++;
+      }
     }
 
     // Create and store the new granted lock
@@ -715,6 +729,10 @@ void LockManager::ReleaseLockAndProcessQueue(Environment* env,
   // stolen.
   if (!lock->is_stolen()) {
     if (was_rejected) {
+      {
+        Mutex::ScopedLock scoped_lock(mutex_);
+        counters.total_aborts++;
+      }
       // Propagate rejection from the user callback
       if (lock->released_promise()
               ->Reject(context, callback_result)
@@ -800,6 +818,37 @@ void LockManager::CleanupEnvironment(Environment* env_to_cleanup) {
   registered_envs_.erase(env_to_cleanup);
 }
 
+LockManager::LocksCountersSnapshot LockManager::GetCountersSnapshot() const {
+  LocksCountersSnapshot snapshot;
+  Mutex::ScopedLock scoped_lock(mutex_);
+
+  snapshot.total_steals = counters.total_steals;
+  snapshot.total_aborts = counters.total_aborts;
+  snapshot.total_exclusive_acquired = counters.total_exclusive_acquired;
+  snapshot.total_shared_acquired = counters.total_shared_acquired;
+
+  for (const auto& pending_request : pending_queue_) {
+    if (pending_request->mode() == Lock::Mode::Exclusive) {
+      snapshot.pending_exclusive++;
+    } else {
+      snapshot.pending_shared++;
+    }
+  }
+
+  for (const auto& resource : held_locks_) {
+    const auto& locks = resource.second;
+    for (const auto& lock : locks) {
+      if (lock->mode() == Lock::Mode::Exclusive) {
+        snapshot.holders_exclusive++;
+      } else {
+        snapshot.holders_shared++;
+      }
+    }
+  }
+
+  return snapshot;
+}
+
 // Cleanup hook wrapper
 void LockManager::OnEnvironmentCleanup(void* arg) {
   Environment* env = static_cast<Environment*>(arg);
diff --git a/src/node_locks.h b/src/node_locks.h
index cee1d26a42ff94..62fa5637571015 100644
--- a/src/node_locks.h
+++ b/src/node_locks.h
@@ -155,6 +155,17 @@ class LockManager final {
                                   std::shared_ptr<Lock> lock,
                                   v8::Local<v8::Value> result,
                                   bool was_rejected = false);
+  struct LocksCountersSnapshot {
+    uint64_t total_steals = 0;
+    uint64_t total_aborts = 0;
+    uint64_t total_exclusive_acquired = 0;
+    uint64_t total_shared_acquired = 0;
+    size_t holders_exclusive = 0;
+    size_t holders_shared = 0;
+    size_t pending_exclusive = 0;
+    size_t pending_shared = 0;
+  };
+  LocksCountersSnapshot GetCountersSnapshot() const;
 
  private:
   LockManager() = default;
@@ -171,6 +182,13 @@ class LockManager final {
   static LockManager current_;
 
   mutable Mutex mutex_;
+  struct Counters {
+    uint64_t total_steals = 0;
+    uint64_t total_aborts = 0;
+    uint64_t total_exclusive_acquired = 0;
+    uint64_t total_shared_acquired = 0;
+  };
+  Counters counters;
   // All entries for a given Environment* are purged in CleanupEnvironment().
   std::unordered_map<std::u16string, std::deque<std::shared_ptr<Lock>>>
       held_locks_;
diff --git a/src/node_process_methods.cc b/src/node_process_methods.cc
index fe4aad63bc877b..4559f3a6a21fbf 100644
--- a/src/node_process_methods.cc
+++ b/src/node_process_methods.cc
@@ -8,6 +8,7 @@
 #include "node_errors.h"
 #include "node_external_reference.h"
 #include "node_internals.h"
+#include "node_locks.h"
 #include "node_process-inl.h"
 #include "path.h"
 #include "util-inl.h"
@@ -39,6 +40,7 @@ typedef int mode_t;
 
 namespace node {
 
+using node::worker::locks::LockManager;
 using v8::Array;
 using v8::ArrayBuffer;
 using v8::CFunction;
@@ -156,6 +158,25 @@ static void ThreadCPUUsage(const FunctionCallbackInfo<Value>& args) {
   fields[1] = MICROS_PER_SEC * rusage.ru_stime.tv_sec + rusage.ru_stime.tv_usec;
 }
 
+static void LocksCounters(const FunctionCallbackInfo<Value>& args) {
+  LockManager::LocksCountersSnapshot snapshot =
+      LockManager::GetCurrent()->GetCountersSnapshot();
+
+  Local<ArrayBuffer> ab = get_fields_array_buffer(args, 0, 8);
+
+  uint64_t* bigint_fields = static_cast<uint64_t*>(ab->Data());
+  bigint_fields[0] = snapshot.total_aborts;
+  bigint_fields[1] = snapshot.total_steals;
+  bigint_fields[2] = snapshot.total_exclusive_acquired;
+  bigint_fields[3] = snapshot.total_shared_acquired;
+
+  double* fields = static_cast<double*>(ab->Data());
+  fields[4] = static_cast<double>(snapshot.holders_exclusive);
+  fields[5] = static_cast<double>(snapshot.holders_shared);
+  fields[6] = static_cast<double>(snapshot.pending_exclusive);
+  fields[7] = static_cast<double>(snapshot.pending_shared);
+}
+
 static void Cwd(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   CHECK(env->has_run_bootstrapping_code());
@@ -770,6 +791,7 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
   SetMethod(isolate, target, "rss", Rss);
   SetMethod(isolate, target, "cpuUsage", CPUUsage);
   SetMethod(isolate, target, "threadCpuUsage", ThreadCPUUsage);
+  SetMethodNoSideEffect(isolate, target, "locksCounters", LocksCounters);
   SetMethod(isolate, target, "resourceUsage", ResourceUsage);
 
   SetMethod(isolate, target, "_debugEnd", DebugEnd);
@@ -819,6 +841,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(Rss);
   registry->Register(CPUUsage);
   registry->Register(ThreadCPUUsage);
+  registry->Register(LocksCounters);
   registry->Register(ResourceUsage);
 
   registry->Register(GetActiveRequests);
diff --git a/test/parallel/test-process-locks-counters.js b/test/parallel/test-process-locks-counters.js
new file mode 100644
index 00000000000000..acf4c82f69dcda
--- /dev/null
+++ b/test/parallel/test-process-locks-counters.js
@@ -0,0 +1,226 @@
+'use strict';
+
+require('../common');
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const { Worker, locks } = require('node:worker_threads');
+
+function totalAcquired(snapshot) {
+  return snapshot.totalExclusiveAcquired + snapshot.totalSharedAcquired;
+}
+
+function holdersTotal(snapshot) {
+  return snapshot.holdersExclusive + snapshot.holdersShared;
+}
+
+function pendingTotal(snapshot) {
+  return snapshot.pendingExclusive + snapshot.pendingShared;
+}
+
+describe('process.locksCounters()', () => {
+  it('should return valid counters structure with correct types', async () => {
+    assert.strictEqual(typeof process.locksCounters, 'function');
+
+    const snapshot = process.locksCounters();
+
+    // BigInt counters
+    assert.strictEqual(typeof snapshot.totalAborts, 'bigint');
+    assert(snapshot.totalAborts >= 0n);
+    assert.strictEqual(typeof snapshot.totalSteals, 'bigint');
+    assert(snapshot.totalSteals >= 0n);
+    assert.strictEqual(typeof snapshot.totalExclusiveAcquired, 'bigint');
+    assert(snapshot.totalExclusiveAcquired >= 0n);
+    assert.strictEqual(typeof snapshot.totalSharedAcquired, 'bigint');
+    assert(snapshot.totalSharedAcquired >= 0n);
+
+    // Number counters
+    assert.strictEqual(typeof snapshot.holdersExclusive, 'number');
+    assert(snapshot.holdersExclusive >= 0);
+    assert.strictEqual(typeof snapshot.holdersShared, 'number');
+    assert(snapshot.holdersShared >= 0);
+    assert.strictEqual(typeof snapshot.pendingExclusive, 'number');
+    assert(snapshot.pendingExclusive >= 0);
+    assert.strictEqual(typeof snapshot.pendingShared, 'number');
+    assert(snapshot.pendingShared >= 0);
+
+    const totalAcq = totalAcquired(snapshot);
+    assert.strictEqual(typeof totalAcq, 'bigint');
+    assert.strictEqual(totalAcq, snapshot.totalExclusiveAcquired + snapshot.totalSharedAcquired);
+  });
+
+  it('should increment totalExclusiveAcquired and track holders', async () => {
+    const resource = 'test-exclusive-acquire';
+    const before = process.locksCounters();
+
+    await locks.request(resource, async (lock) => {
+      assert.strictEqual(lock.mode, 'exclusive');
+      const current = process.locksCounters();
+
+      assert.strictEqual(totalAcquired(current), totalAcquired(before) + 1n);
+      assert.strictEqual(current.totalExclusiveAcquired, before.totalExclusiveAcquired + 1n);
+
+      assert.strictEqual(current.holdersExclusive, before.holdersExclusive + 1);
+      assert.strictEqual(holdersTotal(current), holdersTotal(before) + 1);
+    });
+
+    const after = process.locksCounters();
+    assert.strictEqual(after.totalExclusiveAcquired, before.totalExclusiveAcquired + 1n);
+    assert.strictEqual(after.holdersExclusive, before.holdersExclusive);
+  });
+
+  it('should track multiple shared locks held simultaneously', async () => {
+    const resource = 'test-multiple-shared';
+    const before = process.locksCounters();
+
+    await locks.request(resource, { mode: 'shared' }, async () => {
+      const afterFirst = process.locksCounters();
+      assert.strictEqual(afterFirst.holdersShared, before.holdersShared + 1);
+
+      await locks.request(resource, { mode: 'shared' }, async () => {
+        const afterSecond = process.locksCounters();
+
+        assert.strictEqual(afterSecond.holdersShared, before.holdersShared + 2);
+        assert.strictEqual(afterSecond.totalSharedAcquired, before.totalSharedAcquired + 2n);
+      });
+    });
+
+    const after = process.locksCounters();
+    assert.strictEqual(after.totalSharedAcquired, before.totalSharedAcquired + 2n);
+    assert.strictEqual(after.holdersShared, before.holdersShared);
+  });
+
+  it('should track pending lock requests', async () => {
+    const resource = 'test-pending-lock';
+    const before = process.locksCounters();
+
+    const firstLock = locks.request(resource, async () => {
+      return 'first-lock';
+    });
+
+    const secondLock = locks.request(resource, async () => {
+      return 'second-lock';
+    });
+
+    const current = process.locksCounters();
+
+    // Should have one holder and one pending
+    assert(current.holdersExclusive >= before.holdersExclusive + 1);
+    assert(current.pendingExclusive >= before.pendingExclusive + 1);
+    assert(pendingTotal(current) >= pendingTotal(before) + 1);
+
+    // Release the locks
+    await firstLock;
+    await secondLock;
+
+    const after = process.locksCounters();
+    assert.strictEqual(after.totalExclusiveAcquired, before.totalExclusiveAcquired + 2n);
+  });
+
+  it('should increment totalAborts when ifAvailable fails', async () => {
+    const resource = 'test-ifavailable-abort';
+    const before = process.locksCounters();
+
+    await locks.request(resource, async () => {
+      // Try to acquire with ifAvailable while lock is held
+      const result = await locks.request(resource, { ifAvailable: true }, (lock) => {
+        return lock;
+      });
+
+      assert.strictEqual(result, null);
+
+      const after = process.locksCounters();
+      assert.strictEqual(after.totalAborts, before.totalAborts + 1n);
+    });
+  });
+
+  it('should increment totalAborts when callback rejects', async () => {
+    const resource = 'test-callback-reject-abort';
+    const before = process.locksCounters();
+
+    await locks.request(resource, async () => {
+      throw new Error('Callback rejection');
+    }).catch(() => {
+      // Expected rejection
+    });
+
+    const after = process.locksCounters();
+    assert.strictEqual(after.totalExclusiveAcquired, before.totalExclusiveAcquired + 1n);
+    assert.strictEqual(after.totalAborts, before.totalAborts + 1n);
+  });
+
+  it('should increment totalSteals when stealing a lock', async () => {
+    const resource = 'test-steal-counter';
+    const before = process.locksCounters();
+
+    const originalPromise = locks.request(resource, async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      return 'original';
+    }).catch((err) => {
+      assert.strictEqual(err.name, 'AbortError');
+      return 'stolen';
+    });
+
+    const stealResult = await locks.request(resource, { steal: true }, async (lock) => {
+      assert.strictEqual(lock.mode, 'exclusive');
+      return 'completed';
+    });
+
+    assert.strictEqual(stealResult, 'completed');
+    assert.strictEqual(await originalPromise, 'stolen');
+
+    const after = process.locksCounters();
+    assert.strictEqual(after.totalSteals, before.totalSteals + 1n);
+    assert.strictEqual(after.totalExclusiveAcquired, before.totalExclusiveAcquired + 2n);
+  });
+
+  it('should handle counters correctly across worker threads', async () => {
+    const resource = 'test-cross-thread';
+    const before = process.locksCounters();
+
+    const worker = new Worker(`
+      const { parentPort, locks } = require('worker_threads');
+
+      locks.request('test-cross-thread', async () => {
+        // Lock acquired and released
+      }).then(() => {
+        parentPort.postMessage('done');
+      });
+    `, { eval: true });
+
+    await new Promise((resolve) => {
+      worker.once('message', resolve);
+    });
+
+    await worker.terminate();
+
+    await locks.request(resource, async (lock) => {
+      assert.strictEqual(lock.mode, 'exclusive');
+    });
+
+    const after = process.locksCounters();
+    assert.strictEqual(totalAcquired(after), totalAcquired(before) + 2n);
+    assert.strictEqual(after.totalExclusiveAcquired, before.totalExclusiveAcquired + 2n);
+  });
+
+  it('should accumulate counters correctly over many acquisitions', async () => {
+    const resource = 'test-accumulation';
+    const before = process.locksCounters();
+    const iterations = 1_000;
+
+    for (let i = 0; i < iterations; i++) {
+      await locks.request(resource, { mode: i % 2 === 0 ? 'exclusive' : 'shared' }, async () => {
+        // Do nothing, just acquire the lock
+      });
+    }
+
+    const after = process.locksCounters();
+
+    const totalAcquired = after.totalExclusiveAcquired + after.totalSharedAcquired;
+    const beforeTotal = before.totalExclusiveAcquired + before.totalSharedAcquired;
+
+    assert.strictEqual(totalAcquired, beforeTotal + BigInt(iterations));
+
+    assert(after.totalExclusiveAcquired > before.totalExclusiveAcquired);
+    assert(after.totalSharedAcquired > before.totalSharedAcquired);
+  });
+});