diff -r d232cff25bbd Doc/library/threading.rst --- a/Doc/library/threading.rst Sat Apr 27 00:20:04 2013 +0200 +++ b/Doc/library/threading.rst Sat Apr 27 16:00:19 2013 -0700 @@ -350,7 +350,7 @@ 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. +is not defined and may vary across implementations. All methods are executed atomically. @@ -358,7 +358,7 @@ .. class:: Lock() The class implementing primitive lock objects. Once a thread has acquired a - lock, subsequent attempts to acquire it block, until it is released; any + lock, subsequent attempts to acquire it are blocked, until it is released; any thread may release it. .. versionchanged:: 3.3 @@ -367,23 +367,22 @@ .. method:: acquire(blocking=True, timeout=-1) - Acquire a lock, blocking or non-blocking. + Without any optional argument, this method acquires the lock unconditionally, if + necessary waiting until it is released by another thread (only one thread at a + time can acquire a lock --- that's their reason for existence). - When invoked with the *blocking* argument set to ``True`` (the default), - block until the lock is unlocked, then set it to locked and return ``True``. + If the boolean *blocking* argument is present, the action depends on its + value: if it is ``False``, the lock is only acquired if it can be acquired + immediately without waiting, while if it is ``True``, the lock is acquired + unconditionally as above. - When invoked with the *blocking* argument set to ``False``, do not block. - If a call with *blocking* set to ``True`` would block, return ``False`` - immediately; otherwise, set the lock to locked and return ``True``. - - When invoked with the floating-point *timeout* argument set to a positive - value, block for at most the number of seconds specified by *timeout* - and as long as the lock cannot be acquired. A negative *timeout* argument - specifies an unbounded wait. It is forbidden to specify a *timeout* - when *blocking* is false. + If the floating-point *timeout* argument is present and positive, it + specifies the maximum wait time in seconds before returning. A negative + *timeout* argument specifies an unbounded wait. You cannot specify + a *timeout* if *blocking* is ``False``. The return value is ``True`` if the lock is acquired successfully, - ``False`` if not (for example if the *timeout* expired). + ``False`` if not. .. versionchanged:: 3.2 The *timeout* parameter is new.