worker: add name for worker

theanarkh · richardlau · commit 98cd7e27d4bb · 2025-09-20T03:32:52.000Z
PR-URL: #59213 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -715,6 +715,17 @@ An integer identifier for the current thread. On the corresponding worker object
 (if there is any), it is available as [`worker.threadId`][].
 This value is unique for each [`Worker`][] instance inside a single process.
 
+## `worker.threadName`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string|null}
+
+A string identifier for the current thread or null if the thread is not running.
+On the corresponding worker object (if there is any), it is available as [`worker.threadName`][].
+
 ## `worker.workerData`
 
 <!-- YAML
@@ -1849,6 +1860,17 @@ An integer identifier for the referenced thread. Inside the worker thread,
 it is available as [`require('node:worker_threads').threadId`][].
 This value is unique for each `Worker` instance inside a single process.
 
+### `worker.threadName`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {string|null}
+
+A string identifier for the referenced thread or null if the thread is not running.
+Inside the worker thread, it is available as [`require('node:worker_threads').threadName`][].
+
 ### `worker.unref()`
 
 <!-- YAML
@@ -1969,6 +1991,7 @@ thread spawned will spawn another until the application crashes.
 [`require('node:worker_threads').parentPort.postMessage()`]: #workerpostmessagevalue-transferlist
 [`require('node:worker_threads').parentPort`]: #workerparentport
 [`require('node:worker_threads').threadId`]: #workerthreadid
+[`require('node:worker_threads').threadName`]: #workerthreadname
 [`require('node:worker_threads').workerData`]: #workerworkerdata
 [`trace_events`]: tracing.md
 [`v8.getHeapSnapshot()`]: v8.md#v8getheapsnapshotoptions
@@ -1979,6 +2002,7 @@ thread spawned will spawn another until the application crashes.
 [`worker.postMessage()`]: #workerpostmessagevalue-transferlist
 [`worker.terminate()`]: #workerterminate
 [`worker.threadId`]: #workerthreadid_1
+[`worker.threadName`]: #workerthreadname_1
 [async-resource-worker-pool]: async_context.md#using-asyncresource-for-a-worker-thread-pool
 [browser `MessagePort`]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
 [child processes]: child_process.md
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
@@ -71,6 +71,7 @@ const {
   isInternalThread,
   resourceLimits: resourceLimitsRaw,
   threadId,
+  threadName,
   Worker: WorkerImpl,
   kMaxYoungGenerationSizeMb,
   kMaxOldGenerationSizeMb,
@@ -432,6 +433,12 @@ class Worker extends EventEmitter {
     return this[kHandle].threadId;
   }
 
+  get threadName() {
+    if (this[kHandle] === null) return null;
+
+    return this[kHandle].threadName;
+  }
+
   get stdin() {
     return this[kParentSideStdio].stdin;
   }
@@ -596,6 +603,7 @@ module.exports = {
   getEnvironmentData,
   assignEnvironmentData,
   threadId,
+  threadName,
   InternalWorker,
   Worker,
 };
diff --git a/lib/worker_threads.js b/lib/worker_threads.js
@@ -8,6 +8,7 @@ const {
   setEnvironmentData,
   getEnvironmentData,
   threadId,
+  threadName,
   Worker,
 } = require('internal/worker');
 
@@ -42,6 +43,7 @@ module.exports = {
   resourceLimits,
   postMessageToThread,
   threadId,
+  threadName,
   SHARE_ENV,
   Worker,
   parentPort: null,
diff --git a/src/api/environment.cc b/src/api/environment.cc
@@ -405,6 +405,25 @@ Environment* CreateEnvironment(
     EnvironmentFlags::Flags flags,
     ThreadId thread_id,
     std::unique_ptr<InspectorParentHandle> inspector_parent_handle) {
+  return CreateEnvironment(isolate_data,
+                           context,
+                           args,
+                           exec_args,
+                           flags,
+                           thread_id,
+                           std::move(inspector_parent_handle),
+                           {});
+}
+
+Environment* CreateEnvironment(
+    IsolateData* isolate_data,
+    Local<Context> context,
+    const std::vector<std::string>& args,
+    const std::vector<std::string>& exec_args,
+    EnvironmentFlags::Flags flags,
+    ThreadId thread_id,
+    std::unique_ptr<InspectorParentHandle> inspector_parent_handle,
+    std::string_view thread_name) {
   Isolate* isolate = isolate_data->isolate();
 
   Isolate::Scope isolate_scope(isolate);
@@ -425,7 +444,8 @@ Environment* CreateEnvironment(
                                      exec_args,
                                      env_snapshot_info,
                                      flags,
-                                     thread_id);
+                                     thread_id,
+                                     thread_name);
   CHECK_NOT_NULL(env);
 
   if (use_snapshot) {
diff --git a/src/env-inl.h b/src/env-inl.h
@@ -729,6 +729,10 @@ inline uint64_t Environment::thread_id() const {
   return thread_id_;
 }
 
+inline std::string_view Environment::thread_name() const {
+  return thread_name_;
+}
+
 inline worker::Worker* Environment::worker_context() const {
   return isolate_data()->worker_context();
 }
diff --git a/src/env.cc b/src/env.cc
@@ -803,7 +803,8 @@ Environment::Environment(IsolateData* isolate_data,
                          const std::vector<std::string>& exec_args,
                          const EnvSerializeInfo* env_info,
                          EnvironmentFlags::Flags flags,
-                         ThreadId thread_id)
+                         ThreadId thread_id,
+                         std::string_view thread_name)
     : isolate_(isolate),
       isolate_data_(isolate_data),
       async_hooks_(isolate, MAYBE_FIELD_PTR(env_info, async_hooks)),
@@ -829,7 +830,8 @@ Environment::Environment(IsolateData* isolate_data,
       flags_(flags),
       thread_id_(thread_id.id == static_cast<uint64_t>(-1)
                      ? AllocateEnvironmentThreadId().id
-                     : thread_id.id) {
+                     : thread_id.id),
+      thread_name_(thread_name) {
   constexpr bool is_shared_ro_heap =
 #ifdef NODE_V8_SHARED_RO_HEAP
       true;
diff --git a/src/env.h b/src/env.h
@@ -681,7 +681,8 @@ class Environment final : public MemoryRetainer {
               const std::vector<std::string>& exec_args,
               const EnvSerializeInfo* env_info,
               EnvironmentFlags::Flags flags,
-              ThreadId thread_id);
+              ThreadId thread_id,
+              std::string_view thread_name = "");
   void InitializeMainContext(v8::Local<v8::Context> context,
                              const EnvSerializeInfo* env_info);
   ~Environment() override;
@@ -826,6 +827,7 @@ class Environment final : public MemoryRetainer {
   inline bool should_start_debug_signal_handler() const;
   inline bool no_browser_globals() const;
   inline uint64_t thread_id() const;
+  inline std::string_view thread_name() const;
   inline worker::Worker* worker_context() const;
   Environment* worker_parent_env() const;
   inline void add_sub_worker_context(worker::Worker* context);
@@ -1201,6 +1203,7 @@ class Environment final : public MemoryRetainer {
 
   uint64_t flags_;
   uint64_t thread_id_;
+  std::string thread_name_;
   std::unordered_set<worker::Worker*> sub_worker_contexts_;
 
 #if HAVE_INSPECTOR
diff --git a/src/env_properties.h b/src/env_properties.h
@@ -377,6 +377,7 @@
   V(table_string, "table")                                                     \
   V(target_string, "target")                                                   \
   V(thread_id_string, "threadId")                                              \
+  V(thread_name_string, "threadName")                                          \
   V(ticketkeycallback_string, "onticketkeycallback")                           \
   V(timeout_string, "timeout")                                                 \
   V(time_to_first_byte_string, "timeToFirstByte")                              \
diff --git a/src/node.h b/src/node.h
@@ -716,6 +716,16 @@ NODE_EXTERN Environment* CreateEnvironment(
     ThreadId thread_id = {} /* allocates a thread id automatically */,
     std::unique_ptr<InspectorParentHandle> inspector_parent_handle = {});
 
+NODE_EXTERN Environment* CreateEnvironment(
+    IsolateData* isolate_data,
+    v8::Local<v8::Context> context,
+    const std::vector<std::string>& args,
+    const std::vector<std::string>& exec_args,
+    EnvironmentFlags::Flags flags,
+    ThreadId thread_id,
+    std::unique_ptr<InspectorParentHandle> inspector_parent_handle,
+    std::string_view thread_name);
+
 // Returns a handle that can be passed to `LoadEnvironment()`, making the
 // child Environment accessible to the inspector as if it were a Node.js Worker.
 // `child_thread_id` can be created using `AllocateEnvironmentThreadId()`
diff --git a/src/node_worker.cc b/src/node_worker.cc
@@ -33,6 +33,7 @@ using v8::Local;
 using v8::Locker;
 using v8::Maybe;
 using v8::Name;
+using v8::NewStringType;
 using v8::Null;
 using v8::Number;
 using v8::Object;
@@ -89,6 +90,15 @@ Worker::Worker(Environment* env,
                 Number::New(env->isolate(), static_cast<double>(thread_id_.id)))
       .Check();
 
+  object()
+      ->Set(env->context(),
+            env->thread_name_string(),
+            String::NewFromUtf8(env->isolate(),
+                                name_.data(),
+                                NewStringType::kNormal,
+                                name_.size())
+                .ToLocalChecked())
+      .Check();
   // Without this check, to use the permission model with
   // workers (--allow-worker) one would need to pass --allow-inspector as well
   if (env->permission()->is_granted(
@@ -371,7 +381,8 @@ void Worker::Run() {
             std::move(exec_argv_),
             static_cast<EnvironmentFlags::Flags>(environment_flags_),
             thread_id_,
-            std::move(inspector_parent_handle_)));
+            std::move(inspector_parent_handle_),
+            name_));
         if (is_stopped()) return;
         CHECK_NOT_NULL(env_);
         env_->set_env_vars(std::move(env_vars_));
@@ -1240,6 +1251,16 @@ void CreateWorkerPerContextProperties(Local<Object> target,
             Number::New(isolate, static_cast<double>(env->thread_id())))
       .Check();
 
+  target
+      ->Set(env->context(),
+            env->thread_name_string(),
+            String::NewFromUtf8(isolate,
+                                env->thread_name().data(),
+                                NewStringType::kNormal,
+                                env->thread_name().size())
+                .ToLocalChecked())
+      .Check();
+
   target
       ->Set(env->context(),
             FIXED_ONE_BYTE_STRING(isolate, "isMainThread"),
diff --git a/test/parallel/test-worker-thread-name.js b/test/parallel/test-worker-thread-name.js
@@ -0,0 +1,18 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const { Worker, threadName, workerData } = require('worker_threads');
+
+const name = 'test-worker-thread-name';
+
+if (workerData?.isWorker) {
+  assert.strictEqual(threadName, name);
+  process.exit(0);
+} else {
+  const w = new Worker(__filename, { name, workerData: { isWorker: true } });
+  assert.strictEqual(w.threadName, name);
+  w.on('exit', common.mustCall(() => {
+    assert.strictEqual(w.threadName, null);
+  }));
+}
