[Python-checkins] cpython (3.2): Small improvements to the threading docs: better publicize support for the with

[antoine.pitrou]

http://hg.python.org/cpython/rev/2040842626ba
changeset:   76228:2040842626ba
branch:      3.2
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Tue Apr 10 22:47:55 2012 +0200
summary:
  Small improvements to the threading docs: better publicize support for the with statement.

files:
  Doc/library/threading.rst |  54 +++++++++++++++++----------
  1 files changed, 34 insertions(+), 20 deletions(-)


diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -389,6 +389,8 @@
 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
@@ -429,7 +431,8 @@
 
 .. 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
@@ -458,6 +461,8 @@
 :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)
 
@@ -512,10 +517,11 @@
 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 :term:`context manager` protocol: 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.
+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
@@ -686,6 +692,8 @@
 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)
 
@@ -742,11 +750,12 @@
 Once spawned, worker threads call the semaphore's acquire and release methods
 when they need to connect to the server::
 
-   pool_sema.acquire()
-   conn = connectdb()
-   ... use connection ...
-   conn.close()
-   pool_sema.release()
+   with pool_sema:
+       conn = connectdb()
+       try:
+           ... use connection ...
+       finally:
+           conn.close()
 
 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.
@@ -947,19 +956,24 @@
 
 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::
+
+   with some_lock:
+       # do something...
+
+is equivalent to::
+
+   some_lock.acquire()
+   try:
+       # do something...
+   finally:
+       some_lock.release()
 
 Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
 :class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
-:keyword:`with` statement context managers.  For example::
-
-   import threading
-
-   some_rlock = threading.RLock()
-
-   with some_rlock:
-       print("some_rlock is locked while this executes")
+:keyword:`with` statement context managers.
 
 
 .. _threaded-imports:

-- 
Repository URL: http://hg.python.org/cpython