@@ -594,14 +594,25 @@ and "recursion level" in addition to the locked/unlocked state used by primitive
594594locks. In the locked state, some thread owns the lock; in the unlocked state,
595595no thread owns it.
596596
597- To lock the lock, a thread calls its:meth: `~RLock.acquire ` method; this
598- returns once the thread owns the lock. To unlock the lock, a thread calls
599- its:meth: `~Lock.release ` method.:meth: `~Lock.acquire `/:meth: `~Lock.release `
600- call pairs may be nested; only the final:meth: `~Lock.release ` (the
601- :meth: `~Lock.release ` of the outermost pair) resets the lock to unlocked and
602- allows another thread blocked in:meth: `~Lock.acquire ` to proceed.
597+ Threads call a lock's:meth: `~RLock.acquire ` method to lock it,
598+ and its:meth: `~Lock.release ` method to unlock it.
603599
604- Reentrant locks also support the:ref: `context management protocol <with-locks >`.
600+ ..note ::
601+
602+ Reentrant locks support the:ref: `context management protocol <with-locks >`,
603+ so it is recommended to use:keyword: `with ` instead of manually calling
604+ :meth: `~RLock.acquire ` and:meth: `~RLock.release `
605+ to handle acquiring and releasing the lock for a block of code.
606+
607+ RLock's:meth: `~RLock.acquire `/:meth: `~RLock.release ` call pairs may be nested,
608+ unlike Lock's:meth: `~Lock.acquire `/:meth: `~Lock.release `. Only the final
609+ :meth: `~RLock.release ` (the:meth: `~Lock.release ` of the outermost pair) resets
610+ the lock to an unlocked state and allows another thread blocked in
611+ :meth: `~RLock.acquire ` to proceed.
612+
613+ :meth: `~RLock.acquire `/:meth: `~RLock.release ` must be used in pairs: each acquire
614+ must have a release in the thread that has acquired the lock. Failing to
615+ call release as many times the lock has been acquired can lead to deadlock.
605616
606617
607618..class ::RLock()
@@ -620,25 +631,41 @@ Reentrant locks also support the :ref:`context management protocol <with-locks>`
620631
621632 Acquire a lock, blocking or non-blocking.
622633
623- When invoked without arguments: if this thread already owns the lock, increment
624- the recursion level by one, and return immediately. Otherwise, if another
625- thread owns the lock, block until the lock is unlocked. Once the lock is
626- unlocked (not owned by any thread), then grab ownership, set the recursion level
627- to one, and return. If more than one thread is blocked waiting until the lock
628- is unlocked, only one at a time will be able to grab ownership of the lock.
629- There is no return value in this case.
634+ ..seealso ::
630635
631- When invoked with the *blocking * argument set to ``True ``, do the same thing as when
632- called without arguments, and return ``True ``.
636+ :ref: `Using RLock as a context manager <with-locks >`
637+ Recommended over manual:meth: `!acquire ` and:meth: `release ` calls
638+ whenever practical.
633639
634- When invoked with the *blocking * argument set to ``False ``, do not block. If a call
635- without an argument would block, return ``False `` immediately; otherwise, do the
636- same thing as when called without arguments, and return ``True ``.
637640
638- When invoked with the floating-point *timeout * argument set to a positive
639- value, block for at most the number of seconds specified by *timeout *
640- and as long as the lock cannot be acquired. Return ``True `` if the lock has
641- been acquired, ``False `` if the timeout has elapsed.
641+ When invoked with the *blocking * argument set to ``True `` (the default):
642+
643+ * If no thread owns the lock, acquire the lock and return immediately.
644+
645+ * If another thread owns the lock, block until we are able to acquire
646+ lock, or *timeout *, if set to a positive float value.
647+
648+ * If the same thread owns the lock, acquire the lock again, and
649+ return immediately. This is the difference between:class: `Lock ` and
650+ :class: `!RLock `;:class: `Lock ` handles this case the same as the previous,
651+ blocking until the lock can be acquired.
652+
653+ When invoked with the *blocking * argument set to ``False ``:
654+
655+ * If no thread owns the lock, acquire the lock and return immediately.
656+
657+ * If another thread owns the lock, return immediately.
658+
659+ * If the same thread owns the lock, acquire the lock again and return
660+ immediately.
661+
662+ In all cases, if the thread was able to acquire the lock, return ``True ``.
663+ If the thread was unable to acquire the lock (i.e. if not blocking or
664+ the timeout was reached) return ``False ``.
665+
666+ If called multiple times, failing to call:meth: `~RLock.release ` as many times
667+ may lead to deadlock. Consider using:class: `!RLock ` as a context manager rather than
668+ calling acquire/release directly.
642669
643670 ..versionchanged ::3.2
644671 The *timeout * parameter is new.
@@ -654,7 +681,7 @@ Reentrant locks also support the :ref:`context management protocol <with-locks>`
654681
655682 Only call this method when the calling thread owns the lock. A
656683:exc: `RuntimeError ` is raised if this method is called when the lock is
657- unlocked .
684+ not acquired .
658685
659686 There is no return value.
660687