fix(engine): keep a Python thread's own name in the engine and in Python

packages/server/engine-core/apLib/async/ThreadApi.hpp

@@ -77,8 +77,12 @@ class ThreadApi {
 #endif
     }
 
+    // Name of a context implicitly made for a thread the engine did not start,
+    // until something better is known (engine::python::syncThreadName)
+    static constexpr TextView ExternalName = "External";
+
     // This function returns a pointer to the this thread context
-    static auto thisCtx(TextView name = "External",
+    static auto thisCtx(TextView name = ExternalName,
                         bool markReady = false) noexcept {
         return _visit(
             overloaded{// Caller of the thread supplied a context ptr on start

packages/server/engine-lib/engLib/python/init.cpp

@@ -350,32 +350,61 @@ void setupDebug() noexcept {
         }
     }
 
-    // If we have not named the thread for python yet, we will do so now.
-    if (!tls_thread_named) {
-        try {
-            // Get the name of this thread
-            std::string name = std::string(ap::async::getCurrentThreadName());
-
-            // Output a message
-            LOG(Python, "Updating thread name to", name);
-
-            // Get the threading module
-            py::module threading = py::module::import("threading");
-
-            // Get the callers thread in python
-            py::object currentThread = threading.attr("current_thread")();
-
-            // Set the name
-            currentThread.attr("name") = name;
-        } catch (const py::error_already_set &e) {
-            LOG(Python, "Python error during debug set thread name {}",
-                e.what());
-        } catch (...) {
-            LOG(Python, "Error setting up thread name");
+    // Give the thread one name on both sides, if not done yet
+    syncThreadName();
+}
+
+//---------------------------------------------------------------------
+/// @details
+///		Gives the calling thread one name in the engine and in Python,
+///		once per thread.  Whoever started the thread named it: the
+///		engine its own threads, Python its own (asyncio_0 and the like).
+///		Each side knows a thread it did not start only by a placeholder,
+///		the engine by ThreadApi::ExternalName and Python by a
+///		_DummyThread's "Dummy-N", and takes the other side's name.
+///
+///		Called when the engine calls into Python (setupDebug) and when
+///		Python calls into the engine (UnlockPython), so the name is
+///		settled before either side logs or profiles the thread.  This
+///		MUST be called while the GIL is locked
+///--------------------------------------------------------------------
+void syncThreadName() noexcept {
+    // Only attempt this once per thread
+    if (tls_thread_named)
+        return;
+    tls_thread_named = true;
+
+    try {
+        // Get the callers thread in python
+        py::module threading = py::module::import("threading");
+        py::object currentThread = threading.attr("current_thread")();
+
+        // Python started this thread and named it: the engine takes that
+        // name, unless it has a real one of its own (the main thread)
+        if (!py::isinstance(currentThread, threading.attr("_DummyThread"))) {
+            std::string name =
+                py::cast<std::string>(currentThread.attr("name"));
+
+            // A context made now is born with the name; one made earlier
+            // holds only the placeholder
+            auto ctx = ap::async::ThreadApi::thisCtx(name);
+            if (ctx->name() == ap::async::ThreadApi::ExternalName)
+                ctx->setName(ap::TextView{name});
+
+            if (ctx->name() == ap::TextView{name}) {
+                LOG(Python, "Engine thread name taken from Python:", name);
+                return;
+            }
         }
 
-        // Only attempt this once
-        tls_thread_named = true;
+        // Python knows this thread only as Dummy-N: it takes the engine's
+        std::string name = std::string(ap::async::getCurrentThreadName());
+        LOG(Python, "Updating thread name to", name);
+        currentThread.attr("name") = name;
+    } catch (const py::error_already_set &e) {
+        LOG(Python, "Python error during set thread name {}", e.what());
+    } catch (...) {
+        LOG(Python, "Error setting up thread name");
     }
 }
 

packages/server/engine-lib/engLib/python/lock.hpp

@@ -72,16 +72,26 @@ class LockPython : public py::gil_scoped_acquire {
     }
 };
 
+//-------------------------------------------------------------------------
+/// @details
+///		Gives the calling thread one name in the engine and in Python,
+///		once per thread.  Defined in init.cpp.  MUST be called with the
+///		GIL held.
+//-------------------------------------------------------------------------
+void syncThreadName() noexcept;
+
 //-------------------------------------------------------------------------
 /// @details
 ///		This class manages the GIL state and ensures that
 ///		1.	We release python to other threads when we are busy
 ///		2.	No matter what happens (exception, error, etc) the GIL is
 ///			relocked when we leave
+///		3.	A thread Python started, entering the engine here, is named
+///			in the engine before the engine works on it
 //-------------------------------------------------------------------------
-class UnlockPython : public py::gil_scoped_release {
+class UnlockPython {
 public:
-    UnlockPython() : py::gil_scoped_release() {
+    UnlockPython() {
         if (ap::log::isLevelEnabled(Lvl::GIL)) {
             // Get the current thread ID
             std::thread::id threadId = std::this_thread::get_id();
@@ -100,5 +110,14 @@ class UnlockPython : public py::gil_scoped_release {
             LOG(GIL, "UnlockPython: Re-acquiring GIL on thread ", threadId);
         }
     }
+
+private:
+    // Members, not a base: they initialize in declaration order, so the name
+    // is synced while the GIL is still held, before m_release lets it go
+    struct SyncName {
+        SyncName() noexcept { syncThreadName(); }
+    } m_syncName;
+
+    py::gil_scoped_release m_release;
 };
 }  // namespace engine::python

packages/server/engine-lib/test/python/thread_names.cpp

@@ -0,0 +1,243 @@
+// =============================================================================
+// MIT License
+// Copyright (c) 2026 Aparavi Software AG
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+// =============================================================================
+//
+// One name per thread on both sides of the language boundary.
+//
+// The engine keeps a thread's name in its thread context, Python in its
+// threading.Thread.  Whoever started the thread named it: the engine its own
+// threads, Python its own (asyncio_0, ThreadPoolExecutor-0_1).  Each side
+// knows a thread it did not start only by a placeholder, "External" in the
+// engine and "Dummy-N" in Python, and has to take the other side's name.  The
+// profiler and the logs then agree on which thread did what.
+//
+// NOTE: as in profiler.cpp, assertions never run on a worker thread: Catch2's
+// macros are not thread safe.  Workers record what they saw, the Catch2
+// thread asserts.
+// =============================================================================
+
+#include <pybind11/embed.h>
+
+#include <chrono>
+#include <condition_variable>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+
+#include "test.h"
+
+namespace py = pybind11;
+
+// Named rather than anonymous: a unity build puts this file in one unit with
+// profiler.cpp, whose anonymous namespace would then be this one too
+namespace thread_names {
+
+// Every wait is bounded: a deadlock in a GIL path must fail the run, not hang
+constexpr auto kTimeout = std::chrono::seconds(60);
+
+/// A thread's name as each side sees it
+struct Names {
+    std::string engine;
+    std::string python;
+};
+
+/// The calling thread's name in the engine
+std::string engineName() {
+    return std::string{ap::async::getCurrentThreadName()};
+}
+
+/// The calling thread's name in Python; GIL must be held
+std::string pythonName() {
+    return py::cast<std::string>(
+        py::module_::import("threading").attr("current_thread")().attr("name"));
+}
+
+//---------------------------------------------------------------------
+/// @details
+///     Both names on a thread outside Python, reading Python's through
+///     the engine's real seam into Python, as a pipeline filter does
+//---------------------------------------------------------------------
+Names bothNames() {
+    Names names;
+    if (callPython(localfcn()->Error {
+            names.python = pythonName();
+            return {};
+        }))
+        names.python = "<callPython failed>";
+    names.engine = engineName();
+    return names;
+}
+
+//---------------------------------------------------------------------
+/// @details
+///     Signals the Catch2 thread that a worker is done, so it can wait
+///     with a timeout.  Not std::latch, which has no timed wait
+//---------------------------------------------------------------------
+class Done {
+public:
+    void signal() noexcept {
+        {
+            std::lock_guard<std::mutex> guard(m_mutex);
+            m_done = true;
+        }
+        m_cv.notify_all();
+    }
+
+    bool wait() noexcept {
+        std::unique_lock<std::mutex> guard(m_mutex);
+        return m_cv.wait_for(guard, kTimeout, [&] { return m_done; });
+    }
+
+private:
+    std::mutex m_mutex;
+    std::condition_variable m_cv;
+    bool m_done = false;
+};
+
+//---------------------------------------------------------------------
+/// @details
+///     Starts a Python thread named @p name that calls into the engine,
+///     the way the data path hands a document to the engine from an
+///     asyncio worker, and returns what that thread saw.  With
+///     @p engineFirst the engine creates its thread context before the
+///     call reaches UnlockPython, as a cancellation check or a log line
+///     would.  Runs on the Catch2 thread.
+//---------------------------------------------------------------------
+Names fromPythonThread(const char *name, bool engineFirst) {
+    Names names;
+    if (callPython(localfcn()->Error {
+            py::exec(R"PY(
+import threading as _rr_threading
+import engtest_thread_names as _rr_thread_names
+
+
+def rr_thread_names_run(name, engine_first):
+    seen = []
+    thread = _rr_threading.Thread(
+        name=name,
+        target=lambda: seen.append(_rr_thread_names.enter_engine(engine_first)))
+    thread.start()
+    thread.join(60)
+    return seen[0] if seen else ('<no result>', '<no result>')
+)PY");
+            auto seen = py::module_::import("__main__")
+                            .attr("rr_thread_names_run")(name, engineFirst)
+                            .cast<py::tuple>();
+            names.engine = seen[0].cast<std::string>();
+            names.python = seen[1].cast<std::string>();
+            return {};
+        }))
+        names.engine = names.python = "<callPython failed>";
+    return names;
+}
+
+}  // namespace thread_names
+
+// Called from a thread Python started: the engine side of that thread
+PYBIND11_EMBEDDED_MODULE(engtest_thread_names, m) {
+    m.def("enter_engine", [](bool engineFirst) {
+        if (engineFirst)
+            (void)thread_names::engineName();
+
+        thread_names::Names names;
+        {
+            // The engine's entry from Python, as a pipe write takes it
+            engine::python::UnlockPython unlock;
+            names.engine = thread_names::engineName();
+
+            // On to a Python node, as the engine does, through the real seam
+            if (callPython(localfcn()->Error {
+                    names.python = thread_names::pythonName();
+                    return {};
+                }))
+                names.python = "<callPython failed>";
+        }
+        return py::make_tuple(names.engine, names.python);
+    });
+}
+
+//-----------------------------------------------------------------------------
+// A thread Python started keeps Python's name, and the engine takes it too.
+//-----------------------------------------------------------------------------
+TEST_CASE("python::thread_names::python_thread") {
+    auto names = thread_names::fromPythonThread("rr-py-thread", false);
+
+    CHECK(names.engine == "rr-py-thread");
+    CHECK(names.python == "rr-py-thread");
+}
+
+//-----------------------------------------------------------------------------
+// Same, when the engine made its thread context before the thread reached
+// UnlockPython: the placeholder it started with gives way to Python's name.
+//-----------------------------------------------------------------------------
+TEST_CASE("python::thread_names::python_thread_engine_first") {
+    auto names = thread_names::fromPythonThread("rr-py-engine-first", true);
+
+    CHECK(names.engine == "rr-py-engine-first");
+    CHECK(names.python == "rr-py-engine-first");
+}
+
+//-----------------------------------------------------------------------------
+// A thread the engine started gives its name to Python.
+//-----------------------------------------------------------------------------
+TEST_CASE("python::thread_names::engine_thread") {
+    thread_names::Names names;
+    thread_names::Done done;
+    auto thread =
+        std::make_unique<ap::async::Thread>(_location, "rr-engine", [&] {
+            names = thread_names::bothNames();
+            done.signal();
+        });
+    REQUIRE_NO_ERROR(thread->start());
+
+    if (!done.wait()) {
+        // Joining a hung thread would hang the run; leak it instead
+        (void)thread.release();
+        FAIL("engine thread did not finish within the timeout");
+    }
+    thread.reset();
+
+    CHECK(names.engine == "rr-engine");
+    CHECK(names.python == "rr-engine");
+}
+
+//-----------------------------------------------------------------------------
+// A thread neither side started keeps the engine's placeholder on both sides.
+//-----------------------------------------------------------------------------
+TEST_CASE("python::thread_names::foreign_thread") {
+    thread_names::Names names;
+    thread_names::Done done;
+    std::thread thread([&] {
+        names = thread_names::bothNames();
+        done.signal();
+    });
+
+    if (!done.wait()) {
+        thread.detach();
+        FAIL("foreign thread did not finish within the timeout");
+    }
+    thread.join();
+
+    CHECK(names.engine == "External");
+    CHECK(names.python == "External");
+}