gh-59705: Implement _thread.set_name() on Windows #128675

vstinner · 2025-01-09T12:35:51Z

Implement set_name() with SetThreadDescription() and _get_name() with GetThreadDescription(). If SetThreadDescription() or GetThreadDescription() is not available in kernelbase.dll, delete the method when the _thread module is imported.

Truncate the thread name to 32766 characters.

~~set_name() raises ValueError if the name contains an embedded null character.~~

Issue: Python should support exporting thread names to the OS #59705

Implement set_name() with SetThreadDescription() and _get_name() with GetThreadDescription(). If SetThreadDescription() or GetThreadDescription() is not available in kernelbase.dll, delete the method when the _thread module is imported. Truncate the thread name to an arbitrary limit of 64 characters. set_name() raises ValueError if the name contains an embedded null character. Co-authored-by: Eryk Sun <[email protected]>

vstinner · 2025-01-09T12:40:35Z

Code based on @eryksun's code: #59705 (comment). Differences with his code:

I only look for functions in kernelbase.dll, not in api-ms-win-core-processthreads-l1-1-3.dll (kernel32).
set_name() doesn't ignore E_NOTIMPL. That's fine since the threading module ignores any OSError. If Python is run on Windows older than 10.0.14393 (1607), set_name() failure would just be ignored silently.
I used the PyUnicode API to convert to/from wchar_t*.

Truncate the thread name to an arbitrary limit of 64 characters.

I copied this limit from @eryksun's code. Maybe it can be extended to 32766 characters?

set_name() raises ValueError if the name contains an embedded null character.

If it's a blocker issue, I can write the code differently to truncate to the first null character instead.

vstinner · 2025-01-09T12:51:09Z

cc @serhiy-storchaka

vstinner · 2025-01-09T13:03:15Z

set_name() raises ValueError if the name contains an embedded null character.

I misunderstood the code, in fact, the name is truncated at the first null character (ValueError is not raised): same behavior than Linux/macOS/FreeBSD/etc.

vstinner · 2025-01-13T15:11:06Z

cc @zooba @encukou

vstinner · 2025-01-13T20:37:49Z

The alternative to SetThreadDescription() (Windows 10 and newer) is to call RaiseException(0x406D1388, ...). Example: msys2-contrib/mingw-w64@0d95c79. From what I understsood, RaiseException(...) is only understood by debuggers.

The Process Explorer tool doesn't show thread names.

encukou · 2025-01-14T10:36:59Z

I'm not familiar with Windows API, but this looks right to me. A review from @python/windows-team would be great though :)

(Specifically: this is a best-effort attempt to add info to aid debugging or understanding what's going on in a system: we want to as much as we reasonably can to the OS, but it's OK drop part of the name or not set it at all, and errors should be discarded since the user didn't really ask for this. And _get_name is private (test-only); this is not a reliable API to get back a Python string.)

vstinner · 2025-01-16T10:34:57Z

I plan to merge this change at the beginning of next week (January 20th).

vstinner · 2025-01-16T10:35:33Z

I fixed the truncation for surrogate pairs and I added tests with non-BMP characters (creating surrogate pairs on Windows).

serhiy-storchaka

I am not a Windows expert, but the code LGTM. Although I am not sure that we should set such small artificial limit.

There are also some issues in tests.

Lib/test/test_threading.py

serhiy-storchaka

LGTM.

vstinner · 2025-01-17T12:19:33Z

Although I am not sure that we should set such small artificial limit.

Ok, I increased the limit from 64 to 32766 characters.

vstinner · 2025-01-17T12:20:34Z

Thanks for the reviews. I enabled auto-merge.

zooba · 2025-01-17T12:19:17Z

Modules/_threadmodule.c

@@ -2594,6 +2648,31 @@ thread_module_exec(PyObject *module)
    }
 #endif

+#ifdef MS_WINDOWS
+    HMODULE kernelbase = GetModuleHandleW(L"kernelbase.dll");
+    if (kernelbase != NULL) {


If this check fails, we likely want to report a system error since everything is broken, but at least we should call DelAttr to remove the functions, since the function pointers will be null.

set_name()/_get_name() is a minor feature of the _thread module, I would prefer to not prevent to import _thread if loading kernelbase.dll fails for whatever reason.

but at least we should call DelAttr to remove the functions, since the function pointers will be null.

Oops, my code was wrong. Fixed.

zooba · 2025-01-17T12:22:32Z

PC/pyconfig.h.in

@@ -753,4 +753,8 @@ Py_NO_ENABLE_SHARED to find out.  Also support MS_NO_COREDLL for b/w compat */
 /* Define if libssl has X509_VERIFY_PARAM_set1_host and related function */
 #define HAVE_X509_VERIFY_PARAM_SET1_HOST 1

+// Truncate the thread name to 64 characters. The OS limit is 32766 wide
+// characters, but long names aren't of practical use.
+#define PYTHREAD_NAME_MAXLEN 64


There's no reason for us to artificially limit this at all, but I'd rather be much closer to the real limit than this. "Aren't of practical use" is a value judgement, not a technical limit.

Also, there's no C API for this, so we probably don't need a public C constant for the limit.

I changed the limit to 32766 characters.

Also, there's no C API for this, so we probably don't need a public C constant for the limit.

I can rename the macro use _Py prefix. But that unrelated to the Windows implementation, so I would prefer to do it in a separated change. Non-Windows platforms use the same macro.

Also, there's no C API for this, so we probably don't need a public C constant for the limit.

I created #128945 to make the macro private.

Remove the module methods if GetModuleHandleW() fails.

vstinner · 2025-01-17T12:40:51Z

@zooba: Please review the updated PR. I fixed thread_module_exec() to remove the module methods if GetModuleHandleW() fails.

zooba · 2025-01-17T13:06:11Z

LGTM

vstinner · 2025-01-17T13:55:58Z

Merged. Thanks for reviews.

vstinner added the skip news label Jan 9, 2025

vstinner requested a review from a team as a code owner January 9, 2025 12:35

bedevere-app bot mentioned this pull request Jan 9, 2025

Python should support exporting thread names to the OS #59705

Open

bedevere-app bot added the awaiting core review label Jan 9, 2025

Embedded null characters are accepted

d588103

Fix trailing surrogate characters

8f2ead7

serhiy-storchaka reviewed Jan 17, 2025

View reviewed changes

Lib/test/test_threading.py Show resolved Hide resolved

Lib/test/test_threading.py Outdated Show resolved Hide resolved

Add more non-BMP tests; fix test on Windows

f1c5232

serhiy-storchaka approved these changes Jan 17, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Jan 17, 2025

vstinner added 2 commits January 17, 2025 13:17

Set limit to 32766

ba09ba1

Fix set_name() error handling

8148a96

vstinner enabled auto-merge (squash) January 17, 2025 12:20

zooba reviewed Jan 17, 2025

View reviewed changes

zooba disabled auto-merge January 17, 2025 12:23

Fix thread_module_exec()

0ff0567

Remove the module methods if GetModuleHandleW() fails.

vstinner merged commit d7f703d into python:main Jan 17, 2025
38 of 39 checks passed

vstinner deleted the win_thread_descr branch January 17, 2025 13:55

bedevere-app bot removed the awaiting merge label Jan 17, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-59705: Implement _thread.set_name() on Windows #128675

gh-59705: Implement _thread.set_name() on Windows #128675

vstinner commented Jan 9, 2025 •

edited

Loading

vstinner commented Jan 9, 2025

vstinner commented Jan 9, 2025

vstinner commented Jan 9, 2025

vstinner commented Jan 13, 2025

vstinner commented Jan 13, 2025

encukou commented Jan 14, 2025

vstinner commented Jan 16, 2025

vstinner commented Jan 16, 2025

serhiy-storchaka left a comment

serhiy-storchaka left a comment

vstinner commented Jan 17, 2025

vstinner commented Jan 17, 2025

zooba Jan 17, 2025

vstinner Jan 17, 2025

zooba Jan 17, 2025

vstinner Jan 17, 2025

vstinner Jan 17, 2025

vstinner Jan 17, 2025

vstinner commented Jan 17, 2025

zooba commented Jan 17, 2025

vstinner commented Jan 17, 2025

gh-59705: Implement _thread.set_name() on Windows #128675

gh-59705: Implement _thread.set_name() on Windows #128675

Conversation

vstinner commented Jan 9, 2025 • edited Loading

vstinner commented Jan 9, 2025

vstinner commented Jan 9, 2025

vstinner commented Jan 9, 2025

vstinner commented Jan 13, 2025

vstinner commented Jan 13, 2025

encukou commented Jan 14, 2025

vstinner commented Jan 16, 2025

vstinner commented Jan 16, 2025

serhiy-storchaka left a comment

Choose a reason for hiding this comment

serhiy-storchaka left a comment

Choose a reason for hiding this comment

vstinner commented Jan 17, 2025

vstinner commented Jan 17, 2025

zooba Jan 17, 2025

Choose a reason for hiding this comment

vstinner Jan 17, 2025

Choose a reason for hiding this comment

zooba Jan 17, 2025

Choose a reason for hiding this comment

vstinner Jan 17, 2025

Choose a reason for hiding this comment

vstinner Jan 17, 2025

Choose a reason for hiding this comment

vstinner Jan 17, 2025

Choose a reason for hiding this comment

vstinner commented Jan 17, 2025

zooba commented Jan 17, 2025

vstinner commented Jan 17, 2025

vstinner commented Jan 9, 2025 •

edited

Loading