bpo-36084: Add native thread ID (TID) to threading.Thread (GH-13463)

Add native thread ID (TID) to threading.Thread objects
(supported platforms: Windows, FreeBSD, Linux, macOS).

2 files changed, 44 insertions, 0 deletions

diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index acffabf..d7814f2 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -85,6 +85,18 @@ This module defines the following constants and functions:
    may be recycled when a thread exits and another thread is created.
 
 
+.. function:: get_native_id()
+
+   Return the native integral Thread ID of the current thread assigned by the kernel.
+   This is a non-negative integer.
+   Its value may be used to uniquely identify this particular thread system-wide
+   (until the thread terminates, after which the value may be recycled by the OS).
+
+   .. availability:: Windows, FreeBSD, Linux, macOS.
+
+   .. versionadded:: 3.8
+
+
 .. function:: stack_size([size])
 
    Return the thread stack size used when creating new threads.  The optional
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 2234280..1df512f 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -49,6 +49,18 @@ This module defines the following functions:
    .. versionadded:: 3.3
 
 
+.. function:: get_native_id()
+
+   Return the native integral Thread ID of the current thread assigned by the kernel.
+   This is a non-negative integer.
+   Its value may be used to uniquely identify this particular thread system-wide
+   (until the thread terminates, after which the value may be recycled by the OS).
+
+   .. availability:: Windows, FreeBSD, Linux, macOS.
+
+   .. versionadded:: 3.8
+
+
 .. function:: enumerate()
 
    Return a list of all :class:`Thread` objects currently alive.  The list
@@ -297,6 +309,26 @@ since it is impossible to detect the termination of alien threads.
       another thread is created.  The identifier is available even after the
       thread has exited.
 
+   .. attribute:: native_id
+
+      The native integral thread ID of this thread.
+      This is a non-negative integer, or ``None`` if the thread has not
+      been started. See the :func:`get_native_id` function.
+      This represents the Thread ID (``TID``) as assigned to the
+      thread by the OS (kernel).  Its value may be used to uniquely identify
+      this particular thread system-wide (until the thread terminates,
+      after which the value may be recycled by the OS).
+
+      .. note::
+
+         Similar to Process IDs, Thread IDs are only valid (guaranteed unique
+         system-wide) from the time the thread is created until the thread
+         has been terminated.
+
+      .. availability:: Windows, FreeBSD, Linux, macOS.
+
+      .. versionadded:: 3.8
+
    .. method:: is_alive()
 
       Return whether the thread is alive.