Merge

Doc/library/threading.rst

@@ -218,30 +218,32 @@ Thread Objects
 
 This class represents an activity that is run in a separate thread of control.
 There are two ways to specify the activity: by passing a callable object to the
-constructor, or by overriding the :meth:`run` method in a subclass.  No other
-methods (except for the constructor) should be overridden in a subclass.  In
-other words,  *only*  override the :meth:`__init__` and :meth:`run` methods of
-this class.
+constructor, or by overriding the :meth:`~Thread.run` method in a subclass.
+No other methods (except for the constructor) should be overridden in a
+subclass.  In other words,  *only*  override the :meth:`~Thread.__init__`
+and :meth:`~Thread.run` methods of this class.
 
 Once a thread object is created, its activity must be started by calling the
-thread's :meth:`start` method.  This invokes the :meth:`run` method in a
-separate thread of control.
+thread's :meth:`~Thread.start` method.  This invokes the :meth:`~Thread.run`
+method in a separate thread of control.
 
 Once the thread's activity is started, the thread is considered 'alive'. It
-stops being alive when its :meth:`run` method terminates -- either normally, or
-by raising an unhandled exception.  The :meth:`is_alive` method tests whether the
-thread is alive.
+stops being alive when its :meth:`~Thread.run` method terminates -- either
+normally, or by raising an unhandled exception.  The :meth:`~Thread.is_alive`
+method tests whether the thread is alive.
 
-Other threads can call a thread's :meth:`join` method.  This blocks the calling
-thread until the thread whose :meth:`join` method is called is terminated.
+Other threads can call a thread's :meth:`~Thread.join` method.  This blocks
+the calling thread until the thread whose :meth:`~Thread.join` method is
+called is terminated.
 
 A thread has a name.  The name can be passed to the constructor, and read or
-changed through the :attr:`name` attribute.
+changed through the :attr:`~Thread.name` attribute.
 
 A thread can be flagged as a "daemon thread".  The significance of this flag is
 that the entire Python program exits when only daemon threads are left.  The
 initial value is inherited from the creating thread.  The flag can be set
-through the :attr:`daemon` property or the *daemon* constructor argument.
+through the :attr:`~Thread.daemon` property or the *daemon* constructor
+argument.
 
 There is a "main thread" object; this corresponds to the initial thread of
 control in the Python program.  It is not a daemon thread.
@@ -250,8 +252,8 @@ There is the possibility that "dummy thread objects" are created. These are
 thread objects corresponding to "alien threads", which are threads of control
 started outside the threading module, such as directly from C code.  Dummy
 thread objects have limited functionality; they are always considered alive and
-daemonic, and cannot be :meth:`join`\ ed.  They are never deleted, since it is
-impossible to detect the termination of alien threads.
+daemonic, and cannot be :meth:`~Thread.join`\ ed.  They are never deleted,
+since it is impossible to detect the termination of alien threads.
 
 
 .. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
@@ -292,7 +294,8 @@ impossible to detect the termination of alien threads.
       Start the thread's activity.
 
       It must be called at most once per thread object.  It arranges for the
-      object's :meth:`run` method to be invoked in a separate thread of control.
+      object's :meth:`~Thread.run` method to be invoked in a separate thread
+      of control.
 
       This method will raise a :exc:`RuntimeError` if called more than once
       on the same thread object.
@@ -308,25 +311,27 @@ impossible to detect the termination of alien threads.
 
    .. method:: join(timeout=None)
 
-      Wait until the thread terminates. This blocks the calling thread until the
-      thread whose :meth:`join` method is called terminates -- either normally
-      or through an unhandled exception -- or until the optional timeout occurs.
+      Wait until the thread terminates. This blocks the calling thread until
+      the thread whose :meth:`~Thread.join` method is called terminates -- either
+      normally or through an unhandled exception --, or until the optional
+      timeout occurs.
 
       When the *timeout* argument is present and not ``None``, it should be a
       floating point number specifying a timeout for the operation in seconds
-      (or fractions thereof). As :meth:`join` always returns ``None``, you must
-      call :meth:`is_alive` after :meth:`join` to decide whether a timeout
-      happened -- if the thread is still alive, the :meth:`join` call timed out.
+      (or fractions thereof). As :meth:`~Thread.join` always returns ``None``,
+      you must call :meth:`~Thread.is_alive` after :meth:`~Thread.join` to
+      decide whether a timeout happened -- if the thread is still alive, the
+      :meth:`~Thread.join` call timed out.
 
       When the *timeout* argument is not present or ``None``, the operation will
       block until the thread terminates.
 
-      A thread can be :meth:`join`\ ed many times.
+      A thread can be :meth:`~Thread.join`\ ed many times.
 
-      :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
-      the current thread as that would cause a deadlock. It is also an error to
-      :meth:`join` a thread before it has been started and attempts to do so
-      raises the same exception.
+      :meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made
+      to join the current thread as that would cause a deadlock. It is also
+      an error to :meth:`~Thread.join` a thread before it has been started
+      and attempts to do so raise the same exception.
 
    .. attribute:: name
 
@@ -343,27 +348,27 @@ 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 :func:`get_ident()`
-      function.  Thread identifiers may be recycled when a thread exits and
-      another thread is created.  The identifier is available even after the
-      thread has exited.
+      been started.  This is a nonzero integer.  See the
+      :func:`_thread.get_ident()` function.  Thread identifiers may be recycled
+      when a thread exits and another thread is created.  The identifier is
+      available even after the thread has exited.
 
    .. method:: is_alive()
 
       Return whether the thread is alive.
 
-      This method returns ``True`` just before the :meth:`run` method starts
-      until just after the :meth:`run` method terminates.  The module function
-      :func:`.enumerate` returns a list of all alive threads.
+      This method returns ``True`` just before the :meth:`~Thread.run` method
+      starts until just after the :meth:`~Thread.run` method terminates.  The
+      module function :func:`.enumerate` returns a list of all alive threads.
 
    .. attribute:: daemon
 
       A boolean value indicating whether this thread is a daemon thread (True)
-      or not (False).  This must be set before :meth:`start` is called,
+      or not (False).  This must be set before :meth:`~Thread.start` is called,
       otherwise :exc:`RuntimeError` is raised.  Its initial value is inherited
       from the creating thread; the main thread is not a daemon thread and
-      therefore all threads created in the main thread default to :attr:`daemon`
-      = ``False``.
+      therefore all threads created in the main thread default to
+      :attr:`~Thread.daemon` = ``False``.
 
       The entire Python program exits when no alive non-daemon threads are left.
 
@@ -397,19 +402,22 @@ synchronization primitive available, implemented directly by the :mod:`_thread`
 extension module.
 
 A primitive lock is in one of two states, "locked" or "unlocked". It is created
-in the unlocked state.  It has two basic methods, :meth:`acquire` and
-:meth:`release`.  When the state is unlocked, :meth:`acquire` changes the state
-to locked and returns immediately.  When the state is locked, :meth:`acquire`
-blocks until a call to :meth:`release` in another thread changes it to unlocked,
-then the :meth:`acquire` call resets it to locked and returns.  The
-:meth:`release` method should only be called in the locked state; it changes the
-state to unlocked and returns immediately. If an attempt is made to release an
-unlocked lock, a :exc:`RuntimeError` will be raised.
-
-When more than one thread is blocked in :meth:`acquire` waiting for the state to
-turn to unlocked, only one thread proceeds when a :meth:`release` call resets
-the state to unlocked; which one of the waiting threads proceeds is not defined,
-and may vary across implementations.
+in the unlocked state.  It has two basic methods, :meth:`~Lock.acquire` and
+:meth:`~Lock.release`.  When the state is unlocked, :meth:`~Lock.acquire`
+changes the state to locked and returns immediately.  When the state is locked,
+:meth:`~Lock.acquire` blocks until a call to :meth:`~Lock.release` in another
+thread changes it to unlocked, then the :meth:`~Lock.acquire` call resets it
+to locked and returns.  The :meth:`~Lock.release` method should only be
+called in the locked state; it changes the state to unlocked and returns
+immediately. If an attempt is made to release an unlocked lock, a
+:exc:`RuntimeError` will be raised.
+
+Locks also support the :ref:`context manager protocol <with-locks>`.
+
+When more than one thread is blocked in :meth:`~Lock.acquire` waiting for the
+state to turn to unlocked, only one thread proceeds when a :meth:`~Lock.release`
+call resets the state to unlocked; which one of the waiting threads proceeds
+is not defined, and may vary across implementations.
 
 All methods are executed atomically.
 
@@ -446,7 +454,8 @@ All methods are executed atomically.
 
 .. method:: Lock.release()
 
-   Release a lock.
+   Release a lock.  This can be called from any thread, not only the thread
+   which has acquired the lock.
 
    When the lock is locked, reset it to unlocked, and return.  If any other threads
    are blocked waiting for the lock to become unlocked, allow exactly one of them
@@ -468,12 +477,14 @@ and "recursion level" in addition to the locked/unlocked state used by primitive
 locks.  In the locked state, some thread owns the lock; in the unlocked state,
 no thread owns it.
 
-To lock the lock, a thread calls its :meth:`acquire` method; this returns once
-the thread owns the lock.  To unlock the lock, a thread calls its
-:meth:`release` method. :meth:`acquire`/:meth:`release` call pairs may be
-nested; only the final :meth:`release` (the :meth:`release` of the outermost
-pair) resets the lock to unlocked and allows another thread blocked in
-:meth:`acquire` to proceed.
+To lock the lock, a thread calls its :meth:`~RLock.acquire` method; this
+returns once the thread owns the lock.  To unlock the lock, a thread calls
+its :meth:`~Lock.release` method. :meth:`~Lock.acquire`/:meth:`~Lock.release`
+call pairs may be nested; only the final :meth:`~Lock.release` (the
+:meth:`~Lock.release` of the outermost pair) resets the lock to unlocked and
+allows another thread blocked in :meth:`~Lock.acquire` to proceed.
+
+Reentrant locks also support the :ref:`context manager protocol <with-locks>`.
 
 
 .. method:: RLock.acquire(blocking=True, timeout=-1)
@@ -525,62 +536,74 @@ Condition Objects
 -----------------
 
 A condition variable is always associated with some kind of lock; this can be
-passed in or one will be created by default.  (Passing one in is useful when
-several condition variables must share the same lock.)
-
-A condition variable has :meth:`acquire` and :meth:`release` methods that call
-the corresponding methods of the associated lock. It also has a :meth:`wait`
-method, and :meth:`notify` and :meth:`notify_all` methods.  These three must only
-be called when the calling thread has acquired the lock, otherwise a
-:exc:`RuntimeError` is raised.
-
-The :meth:`wait` method releases the lock, and then blocks until it is awakened
-by a :meth:`notify` or :meth:`notify_all` call for the same condition variable in
-another thread.  Once awakened, it re-acquires the lock and returns.  It is also
-possible to specify a timeout.
-
-The :meth:`notify` method wakes up one of the threads waiting for the condition
-variable, if any are waiting.  The :meth:`notify_all` method wakes up all threads
-waiting for the condition variable.
-
-Note: the :meth:`notify` and :meth:`notify_all` methods don't release the lock;
-this means that the thread or threads awakened will not return from their
-:meth:`wait` call immediately, but only when the thread that called
-:meth:`notify` or :meth:`notify_all` finally relinquishes ownership of the lock.
-
-Tip: the typical programming style using condition variables uses the lock to
+passed in or one will be created by default.  Passing one in is useful when
+several condition variables must share the same lock.  The lock is part of
+the condition object: you don't have to track it separately.
+
+A condition variable obeys the :ref:`context manager protocol <with-locks>`:
+using the ``with`` statement acquires the associated lock for the duration of
+the enclosed block.  The :meth:`~Condition.acquire` and
+:meth:`~Condition.release` methods also call the corresponding methods of
+the associated lock.
+
+Other methods must be called with the associated lock held.  The
+:meth:`~Condition.wait` method releases the lock, and then blocks until
+another thread awakens it by calling :meth:`~Condition.notify` or
+:meth:`~Condition.notify_all`.  Once awakened, :meth:`~Condition.wait`
+re-acquires the lock and returns.  It is also possible to specify a timeout.
+
+The :meth:`~Condition.notify` method wakes up one of the threads waiting for
+the condition variable, if any are waiting.  The :meth:`~Condition.notify_all`
+method wakes up all threads waiting for the condition variable.
+
+Note: the :meth:`~Condition.notify` and :meth:`~Condition.notify_all` methods
+don't release the lock; this means that the thread or threads awakened will
+not return from their :meth:`~Condition.wait` call immediately, but only when
+the thread that called :meth:`~Condition.notify` or :meth:`~Condition.notify_all`
+finally relinquishes ownership of the lock.
+
+
+Usage
+^^^^^
+
+The typical programming style using condition variables uses the lock to
 synchronize access to some shared state; threads that are interested in a
-particular change of state call :meth:`wait` repeatedly until they see the
-desired state, while threads that modify the state call :meth:`notify` or
-:meth:`notify_all` when they change the state in such a way that it could
-possibly be a desired state for one of the waiters.  For example, the following
-code is a generic producer-consumer situation with unlimited buffer capacity::
+particular change of state call :meth:`~Condition.wait` repeatedly until they
+see the desired state, while threads that modify the state call
+:meth:`~Condition.notify` or :meth:`~Condition.notify_all` when they change
+the state in such a way that it could possibly be a desired state for one
+of the waiters.  For example, the following code is a generic
+producer-consumer situation with unlimited buffer capacity::
 
    # Consume one item
-   cv.acquire()
+   with cv:
        while not an_item_is_available():
            cv.wait()
        get_an_available_item()
-   cv.release()
 
    # Produce one item
-   cv.acquire()
+   with cv:
        make_an_item_available()
-   cv.notify()
-   cv.release()
 
-To choose between :meth:`notify` and :meth:`notify_all`, consider whether one
-state change can be interesting for only one or several waiting threads.  E.g.
-in a typical producer-consumer situation, adding one item to the buffer only
-needs to wake up one consumer thread.
+The ``while`` loop checking for the application's condition is necessary
+because :meth:`~Condition.wait` can return after an arbitrary long time,
+and other threads may have exhausted the available items in between.  This
+is inherent to multi-threaded programming.  The :meth:`~Condition.wait_for`
+method can be used to automate the condition checking::
 
-Note:  Condition variables can be, depending on the implementation, subject
-to both spurious wakeups (when :meth:`wait` returns without a :meth:`notify`
-call) and stolen wakeups (when another thread acquires the lock before the
-awoken thread.)  For this reason, it is always necessary to verify the state
-the thread is waiting for when :meth:`wait` returns and optionally repeat
-the call as often as necessary.
+   # Consume an item
+   with cv:
+       cv.wait_for(an_item_is_available)
+       get_an_available_item()
 
+To choose between :meth:`~Condition.notify` and :meth:`~Condition.notify_all`,
+consider whether one state change can be interesting for only one or several
+waiting threads.  E.g. in a typical producer-consumer situation, adding one
+item to the buffer only needs to wake up one consumer thread.
+
+
+Interface
+^^^^^^^^^
 
 .. class:: Condition(lock=None)
 
@@ -648,12 +671,6 @@ the call as often as necessary.
       held when called and is re-aquired on return.  The predicate is evaluated
       with the lock held.
 
-      Using this method, the consumer example above can be written thus::
-
-         with cv:
-             cv.wait_for(an_item_is_available)
-             get_an_available_item()
-
       .. versionadded:: 3.2
 
    .. method:: notify(n=1)
@@ -689,12 +706,16 @@ Semaphore Objects
 
 This is one of the oldest synchronization primitives in the history of computer
 science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
-used :meth:`P` and :meth:`V` instead of :meth:`acquire` and :meth:`release`).
+used the names ``P()`` and ``V()`` instead of :meth:`~Semaphore.acquire` and
+:meth:`~Semaphore.release`).
 
 A semaphore manages an internal counter which is decremented by each
-:meth:`acquire` call and incremented by each :meth:`release` call.  The counter
-can never go below zero; when :meth:`acquire` finds that it is zero, it blocks,
-waiting until some other thread calls :meth:`release`.
+:meth:`~Semaphore.acquire` call and incremented by each :meth:`~Semaphore.release`
+call.  The counter can never go below zero; when :meth:`~Semaphore.acquire`
+finds that it is zero, it blocks, waiting until some other thread calls
+:meth:`~Semaphore.release`.
+
+Semaphores also support the :ref:`context manager protocol <with-locks>`.
 
 
 .. class:: Semaphore(value=1)
@@ -710,11 +731,12 @@ waiting until some other thread calls :meth:`release`.
       When invoked without arguments: if the internal counter is larger than
       zero on entry, decrement it by one and return immediately.  If it is zero
       on entry, block, waiting until some other thread has called
-      :meth:`release` to make it larger than zero.  This is done with proper
-      interlocking so that if multiple :meth:`acquire` calls are blocked,
-      :meth:`release` will wake exactly one of them up.  The implementation may
-      pick one at random, so the order in which blocked threads are awakened
-      should not be relied on.  Returns true (or blocks indefinitely).
+      :meth:`~Semaphore.release` to make it larger than zero.  This is done
+      with proper interlocking so that if multiple :meth:`acquire` calls are
+      blocked, :meth:`~Semaphore.release` will wake exactly one of them up.
+      The implementation may pick one at random, so the order in which
+      blocked threads are awakened should not be relied on.  Returns
+      true (or blocks indefinitely).
 
       When invoked with *blocking* set to false, do not block.  If a call
       without an argument would block, return false immediately; otherwise,
@@ -751,11 +773,12 @@ main thread would initialize the semaphore::
 Once spawned, worker threads call the semaphore's acquire and release methods
 when they need to connect to the server::
 
-   pool_sema.acquire()
+   with pool_sema:
        conn = connectdb()
+       try:
            ... use connection ...
+       finally:
            conn.close()
-   pool_sema.release()
 
 The use of a bounded semaphore reduces the chance that a programming error which
 causes the semaphore to be released more than it's acquired will go undetected.
@@ -770,8 +793,8 @@ This is one of the simplest mechanisms for communication between threads: one
 thread signals an event and other threads wait for it.
 
 An event object manages an internal flag that can be set to true with the
-:meth:`~Event.set` method and reset to false with the :meth:`clear` method.  The
-:meth:`wait` method blocks until the flag is true.
+:meth:`~Event.set` method and reset to false with the :meth:`~Event.clear`
+method.  The :meth:`~Event.wait` method blocks until the flag is true.
 
 
 .. class:: Event()
@@ -798,7 +821,7 @@ An event object manages an internal flag that can be set to true with the
 
       Block until the internal flag is true.  If the internal flag is true on
       entry, return immediately.  Otherwise, block until another thread calls
-      :meth:`set` to set the flag to true, or until the optional timeout occurs.
+      :meth:`.set` to set the flag to true, or until the optional timeout occurs.
 
       When the timeout argument is present and not ``None``, it should be a
       floating point number specifying a timeout for the operation in seconds
@@ -854,8 +877,8 @@ Barrier Objects
 
 This class provides a simple synchronization primitive for use by a fixed number
 of threads that need to wait for each other.  Each of the threads tries to pass
-the barrier by calling the :meth:`wait` method and will block until all of the
-threads have made the call.  At this points, the threads are released
+the barrier by calling the :meth:`~Barrier.wait` method and will block until
+all of the threads have made the call.  At this points, the threads are released
 simultanously.
 
 The barrier can be reused any number of times for the same number of threads.
@@ -956,19 +979,24 @@ Using locks, conditions, and semaphores in the :keyword:`with` statement
 
 All of the objects provided by this module that have :meth:`acquire` and
 :meth:`release` methods can be used as context managers for a :keyword:`with`
-statement.  The :meth:`acquire` method will be called when the block is entered,
-and :meth:`release` will be called when the block is exited.
+statement.  The :meth:`acquire` method will be called when the block is
+entered, and :meth:`release` will be called when the block is exited.  Hence,
+the following snippet::
 
-Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
-:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
-:keyword:`with` statement context managers.  For example::
+   with some_lock:
+       # do something...
 
-   import threading
+is equivalent to::
 
-   some_rlock = threading.RLock()
+   some_lock.acquire()
+   try:
+       # do something...
+   finally:
+       some_lock.release()
 
-   with some_rlock:
-       print("some_rlock is locked while this executes")
+Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
+:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
+:keyword:`with` statement context managers.
 
 
 .. _threaded-imports: