bpo-36084: Add native thread ID to threading.Thread objects (GH-11993)

1 files changed, 31 insertions, 0 deletions

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index c58a6ad..99dd7ff 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,25 @@ 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 or ``0`` if the thread has not
+      been started.  This is a non-negative integer.  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.
+
+      .. 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.