gh-59705: Implement _thread.set_name() on Windows by vstinner · Pull Request #128675 · python/cpython · GitHub

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 <eryksun@gmail.com>

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.

cc @serhiy-storchaka

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.

cc @zooba @encukou

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.

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.)

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

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

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.

LGTM.

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

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

Thanks for the reviews. I enabled auto-merge.

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.

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.

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

LGTM

Merged. Thanks for reviews.

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. Co-authored-by: Eryk Sun <eryksun@gmail.com>

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

Closed

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

Comment thread Lib/test/test_threading.py

Comment thread Lib/test/test_threading.py Outdated

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

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

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

python deleted a comment Aug 17, 2026

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

+              // 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

gh-59705: Implement _thread.set_name() on Windows by vstinner · Pull Request #128675 · python/cpython · GitHub

Uh oh!

Uh oh!

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

gh-59705: Implement _thread.set_name() on Windows#128675vstinner merged 7 commits intopython:mainpython/cpython:mainfrom vstinner:win_thread_descrvstinner/cpython:win_thread_descrCopy head branch name to clipboard

Conversation

vstinner commented Jan 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Jan 9, 2025

Uh oh!

vstinner commented Jan 9, 2025

Uh oh!

vstinner commented Jan 9, 2025

Uh oh!

vstinner commented Jan 13, 2025

Uh oh!

vstinner commented Jan 13, 2025

Uh oh!

encukou commented Jan 14, 2025

Uh oh!

vstinner commented Jan 16, 2025

Uh oh!

vstinner commented Jan 16, 2025

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Jan 17, 2025

Uh oh!

vstinner commented Jan 17, 2025

Uh oh!

zooba Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

vstinner Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

zooba Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

vstinner Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

vstinner Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

vstinner Jan 17, 2025

Choose a reason for hiding this comment

Uh oh!

vstinner commented Jan 17, 2025

Uh oh!

zooba commented Jan 17, 2025

Uh oh!

vstinner commented Jan 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gh-59705: Implement _thread.set_name() on Windows#128675
vstinner merged 7 commits into
python:mainfrom
vstinner:win_thread_descr

vstinner commented Jan 9, 2025 •
edited
Loading