worker: add name for worker

theanarkh · theanarkh · commit 8cffc779107d · 2025-07-26T00:43:55.000+08:00
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -721,6 +721,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}
+
+A string identifier for the current thread. On the corresponding worker object
+(if there is any), it is available as [`worker.threadName`][].
+
 ## `worker.workerData`
 
 <!-- YAML
@@ -1855,6 +1866,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}
+
+A string identifier for the referenced thread. Inside the worker thread,
+it is available as [`require('node:worker_threads').threadName`][].
+
 ### `worker.unref()`
 
 <!-- YAML
@@ -1981,6 +2003,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
@@ -1991,6 +2014,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,
@@ -423,6 +424,12 @@ class Worker extends EventEmitter {
     return this[kHandle].threadId;
   }
 
+  get threadName() {
+    if (this[kHandle] === null) return '';
+
+    return this[kHandle].threadName;
+  }
+
   get stdin() {
     return this[kParentSideStdio].stdin;
   }
@@ -556,6 +563,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
@@ -413,7 +413,8 @@ Environment* CreateEnvironment(
     const std::vector<std::string>& exec_args,
     EnvironmentFlags::Flags flags,
     ThreadId thread_id,
-    std::unique_ptr<InspectorParentHandle> inspector_parent_handle) {
+    std::unique_ptr<InspectorParentHandle> inspector_parent_handle,
+    std::string_view thread_name) {
   Isolate* isolate = isolate_data->isolate();
 
   Isolate::Scope isolate_scope(isolate);
@@ -434,7 +435,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
@@ -695,6 +695,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
@@ -784,7 +784,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),
       external_memory_accounter_(new ExternalMemoryAccounter()),
       isolate_data_(isolate_data),
@@ -811,7 +812,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) {
   if (!is_main_thread()) {
     // If this is a Worker thread, we can always safely use the parent's
     // Isolate's code cache because of the shared read-only heap.
diff --git a/src/env.h b/src/env.h
@@ -660,7 +660,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;
@@ -807,6 +808,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);
@@ -1172,6 +1174,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
@@ -386,6 +386,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
@@ -683,7 +683,8 @@ NODE_EXTERN Environment* CreateEnvironment(
     const std::vector<std::string>& exec_args,
     EnvironmentFlags::Flags flags = EnvironmentFlags::kDefaultFlags,
     ThreadId thread_id = {} /* allocates a thread id automatically */,
-    std::unique_ptr<InspectorParentHandle> inspector_parent_handle = {});
+    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.
diff --git a/src/node_worker.cc b/src/node_worker.cc
@@ -32,6 +32,7 @@ using v8::Isolate;
 using v8::Local;
 using v8::Locker;
 using v8::Maybe;
+using v8::NewStringType;
 using v8::Null;
 using v8::Number;
 using v8::Object;
@@ -88,6 +89,14 @@ 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(
@@ -364,7 +373,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_));
@@ -1149,6 +1159,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,20 @@
+'use strict';
+
+const common = require('../common');
+
+const assert = require('assert');
+const { Worker, isMainThread, threadName } = require('worker_threads');
+
+const name = 'test-worker-thread-name';
+
+if (isMainThread) {
+  assert.strictEqual(threadName, '');
+  const w = new Worker(__filename, { name });
+  assert.strictEqual(w.threadName, name);
+  w.on('exit', common.mustCall((code) => {
+    assert.strictEqual(w.threadName, '');
+  }));
+} else {
+  assert.strictEqual(threadName, name);
+  process.exit(0);
+}

Original file line number	Diff line number	Diff line change
`@@ -695,6 +695,10 @@ inline uint64_t Environment::thread_id() const {`
`695`	`695`	`return thread_id_;`
`696`	`696`	`}`
`697`	`697`
	`698`	`+inline std::string_view Environment::thread_name() const {`
	`699`	`+ return thread_name_;`
	`700`	`+}`
	`701`	`+`
`698`	`702`	`inline worker::Worker* Environment::worker_context() const {`
`699`	`703`	`return isolate_data()->worker_context();`
`700`	`704`	`}`