Close #12028: Make threading._get_ident() public, rename it to

threading.get_ident() and document it. This function was used by
_thread.get_ident().

Doc/library/signal.rst

@@ -187,10 +187,9 @@ The :mod:`signal` module defines the following functions:
    Send the signal *signum* to the thread *thread_id*, another thread in the same
    process as the caller.  The signal is asynchronously directed to thread.
 
-   *thread_id* can be read from the :attr:`~threading.Thread.ident` attribute
+   Use :func:`threading.get_ident()` or the :attr:`~threading.Thread.ident`
-   of :attr:`threading.Thread`.  For example,
+   attribute of :attr:`threading.Thread` to get a 'thread identifier' for
-   ``threading.current_thread().ident`` gives the identifier of the current
+   *thread_id*.
-   thread.
 
    If *signum* is 0, then no signal is sent, but error checking is still
    performed; this can be used to check if a thread is still running.

Doc/library/threading.rst

@@ -48,6 +48,17 @@ This module defines the following functions and objects:
    returned.
 
 
+.. function:: get_ident()
+
+   Return the 'thread identifier' of the current thread.  This is a nonzero
+   integer.  Its value has no direct meaning; it is intended as a magic cookie
+   to be used e.g. to index a dictionary of thread-specific data.  Thread
+   identifiers may be recycled when a thread exits and another thread is
+   created.
+
+   .. versionadded:: 3.3
+
+
 .. function:: enumerate()
 
    Return a list of all :class:`Thread` objects currently alive.  The list
@@ -332,10 +343,10 @@ impossible to detect the termination of alien threads.
    .. attribute:: ident
 
       The 'thread identifier' of this thread or ``None`` if the thread has not
-      been started.  This is a nonzero integer.  See the
+      been started.  This is a nonzero integer.  See the :func:`get_ident()`
-      :func:`thread.get_ident()` function.  Thread identifiers may be recycled
+      function.  Thread identifiers may be recycled when a thread exits and
-      when a thread exits and another thread is created.  The identifier is
+      another thread is created.  The identifier is available even after the
-      available even after the thread has exited.
+      thread has exited.
 
    .. method:: is_alive()
 

Lib/logging/__init__.py

@@ -41,10 +41,9 @@
     codecs = None
 
 try:
-    import _thread as thread
     import threading
 except ImportError: #pragma: no cover
-    thread = None
+    threading = None
 
 __author__  = "Vinay Sajip <vinay_sajip@red-dove.com>"
 __status__  = "production"
@@ -199,7 +198,7 @@ def _checkLevel(level):
 #the lock would already have been acquired - so we need an RLock.
 #The same argument applies to Loggers and Manager.loggerDict.
 #
-if thread:
+if threading:
     _lock = threading.RLock()
 else: #pragma: no cover
     _lock = None
@@ -278,8 +277,8 @@ def __init__(self, name, level, pathname, lineno,
         self.created = ct
         self.msecs = (ct - int(ct)) * 1000
         self.relativeCreated = (self.created - _startTime) * 1000
-        if logThreads and thread:
+        if logThreads and threading:
-            self.thread = thread.get_ident()
+            self.thread = threading.get_ident()
             self.threadName = threading.current_thread().name
         else: # pragma: no cover
             self.thread = None
@@ -773,7 +772,7 @@ def createLock(self):
         """
         Acquire a thread lock for serializing access to the underlying I/O.
         """
-        if thread:
+        if threading:
             self.lock = threading.RLock()
         else: #pragma: no cover
             self.lock = None

Lib/reprlib.py

@@ -5,7 +5,7 @@
 import builtins
 from itertools import islice
 try:
-    from _thread import get_ident
+    from threading import get_ident
 except ImportError:
     from _dummy_thread import get_ident
 

Lib/test/lock_tests.py

@@ -4,7 +4,7 @@
 
 import sys
 import time
-from _thread import start_new_thread, get_ident, TIMEOUT_MAX
+from _thread import start_new_thread, TIMEOUT_MAX
 import threading
 import unittest
 
@@ -31,7 +31,7 @@ def __init__(self, f, n, wait_before_exit=False):
         self.finished = []
         self._can_exit = not wait_before_exit
         def task():
-            tid = get_ident()
+            tid = threading.get_ident()
             self.started.append(tid)
             try:
                 f()

Lib/test/test_capi.py

@@ -190,18 +190,17 @@ def TestThreadState():
         idents = []
 
         def callback():
-            idents.append(_thread.get_ident())
+            idents.append(threading.get_ident())
 
         _testcapi._test_thread_state(callback)
         a = b = callback
         time.sleep(1)
         # Check our main thread is in the list exactly 3 times.
-        if idents.count(_thread.get_ident()) != 3:
+        if idents.count(threading.get_ident()) != 3:
             raise support.TestFailed(
                         "Couldn't find main thread correctly in the list")
 
     if threading:
-        import _thread
         import time
         TestThreadState()
         t = threading.Thread(target=TestThreadState)

Lib/test/test_signal.py

@@ -557,7 +557,7 @@ def can_test_blocked_signals(self, skip):
 
     def kill(self, signum):
         if self.has_pthread_kill:
-            tid = threading.current_thread().ident
+            tid = threading.get_ident()
             signal.pthread_kill(tid, signum)
         else:
             pid = os.getpid()
@@ -589,7 +589,7 @@ def test_sigpending(self):
                          'need signal.pthread_kill()')
     def test_pthread_kill(self):
         signum = signal.SIGUSR1
-        current = threading.current_thread().ident
+        current = threading.get_ident()
 
         old_handler = signal.signal(signum, self.handler)
         self.addCleanup(signal.signal, signum, old_handler)

Lib/test/test_sys.py

@@ -343,7 +343,7 @@ def test_current_frames(self):
     # Test sys._current_frames() in a WITH_THREADS build.
     @test.support.reap_threads
     def current_frames_with_threads(self):
-        import threading, _thread
+        import threading
         import traceback
 
         # Spawn a thread that blocks at a known place.  Then the main
@@ -357,7 +357,7 @@ def f123():
             g456()
 
         def g456():
-            thread_info.append(_thread.get_ident())
+            thread_info.append(threading.get_ident())
             entered_g.set()
             leave_g.wait()
 
@@ -373,7 +373,7 @@ def g456():
 
         d = sys._current_frames()
 
-        main_id = _thread.get_ident()
+        main_id = threading.get_ident()
         self.assertIn(main_id, d)
         self.assertIn(thread_id, d)
 

Lib/test/test_threaded_import.py

@@ -30,7 +30,7 @@ def task(N, done, done_tasks, errors):
     except Exception as e:
         errors.append(e.with_traceback(None))
     finally:
-        done_tasks.append(thread.get_ident())
+        done_tasks.append(threading.get_ident())
         finished = len(done_tasks) == N
         if finished:
             done.set()

Lib/test/test_threading.py

@@ -173,7 +173,7 @@ class AsyncExc(Exception):
         exception = ctypes.py_object(AsyncExc)
 
         # First check it works when setting the exception from the same thread.
-        tid = _thread.get_ident()
+        tid = threading.get_ident()
 
         try:
             result = set_async_exc(ctypes.c_long(tid), exception)
@@ -202,7 +202,7 @@ class AsyncExc(Exception):
 
         class Worker(threading.Thread):
             def run(self):
-                self.id = _thread.get_ident()
+                self.id = threading.get_ident()
                 self.finished = False
 
                 try:

Lib/threading.py

@@ -24,7 +24,7 @@
 # Rename some stuff so "from threading import *" is safe
 _start_new_thread = _thread.start_new_thread
 _allocate_lock = _thread.allocate_lock
-_get_ident = _thread.get_ident
+get_ident = _thread.get_ident
 ThreadError = _thread.error
 try:
     _CRLock = _thread.RLock
@@ -52,7 +52,7 @@ def _note(self, format, *args):
                 format = format % args
                 # Issue #4188: calling current_thread() can incur an infinite
                 # recursion if it has to create a DummyThread on the fly.
-                ident = _get_ident()
+                ident = get_ident()
                 try:
                     name = _active[ident].name
                 except KeyError:
@@ -110,7 +110,7 @@ def __repr__(self):
                 self.__class__.__name__, owner, self._count)
 
     def acquire(self, blocking=True, timeout=-1):
-        me = _get_ident()
+        me = get_ident()
         if self._owner == me:
             self._count = self._count + 1
             if __debug__:
@@ -130,7 +130,7 @@ def acquire(self, blocking=True, timeout=-1):
     __enter__ = acquire
 
     def release(self):
-        if self._owner != _get_ident():
+        if self._owner != get_ident():
             raise RuntimeError("cannot release un-acquired lock")
         self._count = count = self._count - 1
         if not count:
@@ -166,7 +166,7 @@ def _release_save(self):
         return (count, owner)
 
     def _is_owned(self):
-        return self._owner == _get_ident()
+        return self._owner == get_ident()
 
 _PyRLock = _RLock
 
@@ -714,7 +714,7 @@ def _bootstrap(self):
             raise
 
     def _set_ident(self):
-        self._ident = _get_ident()
+        self._ident = get_ident()
 
     def _bootstrap_inner(self):
         try:
@@ -787,7 +787,7 @@ def _bootstrap_inner(self):
                 try:
                     # We don't call self._delete() because it also
                     # grabs _active_limbo_lock.
-                    del _active[_get_ident()]
+                    del _active[get_ident()]
                 except:
                     pass
 
@@ -823,7 +823,7 @@ def _delete(self):
 
         try:
             with _active_limbo_lock:
-                del _active[_get_ident()]
+                del _active[get_ident()]
                 # There must not be any python code between the previous line
                 # and after the lock is released.  Otherwise a tracing function
                 # could try to acquire the lock again in the same thread, (in
@@ -1006,9 +1006,8 @@ def join(self, timeout=None):
 
 def current_thread():
     try:
-        return _active[_get_ident()]
+        return _active[get_ident()]
     except KeyError:
-        ##print "current_thread(): no current thread for", _get_ident()
         return _DummyThread()
 
 currentThread = current_thread
@@ -1062,7 +1061,7 @@ def _after_fork():
             if thread is current:
                 # There is only one active thread. We reset the ident to
                 # its new value since it can have changed.
-                ident = _get_ident()
+                ident = get_ident()
                 thread._ident = ident
                 # Any condition variables hanging off of the active thread may
                 # be in an invalid state, so we reinitialize them.

Misc/NEWS

@@ -177,6 +177,10 @@ Core and Builtins
 Library
 -------
 
+- Issue #12028: Make threading._get_ident() public, rename it to
+  threading.get_ident() and document it. This function was used by
+  _thread.get_ident().
+
 - Issue #12171: IncrementalEncoder.reset() of CJK codecs (multibytecodec) calls
   encreset() instead of decreset().