[Python-checkins] cpython: asyncio: document locks
victor.stinner
python-checkins at python.org
Mon Dec 2 14:31:25 CET 2013
http://hg.python.org/cpython/rev/7303cc4fd837
changeset: 87700:7303cc4fd837
user: Victor Stinner <victor.stinner at gmail.com>
date: Mon Dec 02 14:31:16 2013 +0100
summary:
asyncio: document locks
files:
Doc/library/asyncio.rst | 216 ++++++++++++++++++++++++++++
Lib/asyncio/locks.py | 6 +-
2 files changed, 219 insertions(+), 3 deletions(-)
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -901,6 +901,222 @@
Synchronization primitives
--------------------------
+.. class:: Lock(\*, loop=None)
+
+ Primitive lock objects.
+
+ A primitive lock is a synchronization primitive that is not owned by a
+ particular coroutine when locked. 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, acquire() changes the state to
+ locked and returns immediately. When the state is locked, acquire() blocks
+ until a call to release() in another coroutine changes it to unlocked, then
+ the acquire() call resets it to locked and returns. The 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 coroutine is blocked in acquire() waiting for the state
+ to turn to unlocked, only one coroutine proceeds when a release() call
+ resets the state to unlocked; first coroutine which is blocked in acquire()
+ is being processed.
+
+ :meth:`acquire` is a coroutine and should be called with ``yield from``.
+
+ Locks also support the context manager protocol. ``(yield from lock)``
+ should be used as context manager expression.
+
+ Usage::
+
+ lock = Lock()
+ ...
+ yield from lock
+ try:
+ ...
+ finally:
+ lock.release()
+
+ Context manager usage::
+
+ lock = Lock()
+ ...
+ with (yield from lock):
+ ...
+
+ Lock objects can be tested for locking state::
+
+ if not lock.locked():
+ yield from lock
+ else:
+ # lock is acquired
+ ...
+
+ .. method:: locked()
+
+ Return ``True`` if lock is acquired.
+
+ .. method:: acquire()
+
+ Acquire a lock.
+
+ This method blocks until the lock is unlocked, then sets it to locked and
+ returns ``True``.
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ .. method:: release()
+
+ Release a lock.
+
+ When the lock is locked, reset it to unlocked, and return. If any other
+ coroutines are blocked waiting for the lock to become unlocked, allow
+ exactly one of them to proceed.
+
+ When invoked on an unlocked lock, a :exc:`RuntimeError` is raised.
+
+ There is no return value.
+
+
+.. class:: Event(\*, loop=None)
+
+ An Event implementation, asynchronous equivalent to :class:`threading.Event`.
+
+ Class implementing event objects. An event manages a flag that can be set to
+ true with the :meth:`set` method and reset to false with the :meth:`clear`
+ method. The :meth:`wait` method blocks until the flag is true. The flag is
+ initially false.
+
+ .. method:: is_set()
+
+ Return ``True`` if and only if the internal flag is true.
+
+ .. method:: set()
+
+ Set the internal flag to true. All coroutines waiting for it to become
+ true are awakened. Coroutine that call :meth:`wait` once the flag is true
+ will not block at all.
+
+ .. method:: clear()
+
+ Reset the internal flag to false. Subsequently, coroutines calling
+ :meth:`wait` will block until :meth:`set` is called to set the internal
+ flag to true again.
+
+ .. method:: wait()
+
+ Block until the internal flag is true.
+
+ If the internal flag is true on entry, return ``True`` immediately.
+ Otherwise, block until another coroutine calls :meth:`set` to set the
+ flag to true, then return ``True``.
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+
+.. class:: Condition(\*, loop=None)
+
+ A Condition implementation, asynchronous equivalent to
+ :class:`threading.Condition`.
+
+ This class implements condition variable objects. A condition variable
+ allows one or more coroutines to wait until they are notified by another
+ coroutine.
+
+ A new :class:`Lock` object is created and used as the underlying lock.
+
+ .. method:: wait()
+
+ Wait until notified.
+
+ If the calling coroutine has not acquired the lock when this method is
+ called, a :exc:`RuntimeError` is raised.
+
+ This method releases the underlying lock, and then blocks until it is
+ awakened by a :meth:`notify` or :meth:`notify_all` call for the same
+ condition variable in another coroutine. Once awakened, it re-acquires
+ the lock and returns ``True``.
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ .. method:: wait_for(predicate)
+
+ Wait until a predicate becomes true.
+
+ The predicate should be a callable which result will be interpreted as a
+ boolean value. The final predicate value is the return value.
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ .. method:: notify(n=1)
+
+ By default, wake up one coroutine waiting on this condition, if any.
+ If the calling coroutine has not acquired the lock when this method is
+ called, a :exc:`RuntimeError` is raised.
+
+ This method wakes up at most *n* of the coroutines waiting for the
+ condition variable; it is a no-op if no coroutines are waiting.
+
+ .. note::
+
+ An awakened coroutine does not actually return from its :meth:`wait`
+ call until it can reacquire the lock. Since :meth:`notify` does not
+ release the lock, its caller should.
+
+ .. method:: notify_all()
+
+ Wake up all threads waiting on this condition. This method acts like
+ :meth:`notify`, but wakes up all waiting threads instead of one. If the
+ calling thread has not acquired the lock when this method is called, a
+ :exc:`RuntimeError` is raised.
+
+
+.. class:: Semaphore(value=1, \*, loop=None)
+
+ A Semaphore implementation.
+
+ 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`.
+
+ Semaphores also support the context manager protocol.
+
+ The optional argument gives the initial value for the internal counter; it
+ defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError`
+ is raised.
+
+ .. method:: locked()
+
+ Returns ``True`` if semaphore can not be acquired immediately.
+
+ .. method:: acquire()
+
+ Acquire a semaphore.
+
+ If the internal counter is larger than zero on entry, decrement it by one
+ and return ``True`` immediately. If it is zero on entry, block, waiting
+ until some other coroutine has called :meth:`release` to make it larger
+ than ``0``, and then return ``True``.
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ .. method:: release()
+
+ Release a semaphore, incrementing the internal counter by one. When it
+ was zero on entry and another coroutine is waiting for it to become
+ larger than zero again, wake up that coroutine.
+
+
+.. class:: BoundedSemaphore(value=1, \*, loop=None)
+
+ A bounded semaphore implementation. Inherit from :class:`Semaphore`.
+
+ This raises :exc:`ValueError` in :meth:`~Semaphore.release` if it would
+ increase the value above the initial value.
+
+
.. class:: Queue(maxsize=0, \*, loop=None)
A queue, useful for coordinating producer and consumer coroutines.
diff --git a/Lib/asyncio/locks.py b/Lib/asyncio/locks.py
--- a/Lib/asyncio/locks.py
+++ b/Lib/asyncio/locks.py
@@ -79,7 +79,7 @@
return '<{} [{}]>'.format(res[1:-1], extra)
def locked(self):
- """Return true if lock is acquired."""
+ """Return True if lock is acquired."""
return self._locked
@tasks.coroutine
@@ -138,7 +138,7 @@
class Event:
- """An Event implementation, our equivalent to threading.Event.
+ """An Event implementation, asynchronous equivalent to threading.Event.
Class implementing event objects. An event manages a flag that can be set
to true with the set() method and reset to false with the clear() method.
@@ -162,7 +162,7 @@
return '<{} [{}]>'.format(res[1:-1], extra)
def is_set(self):
- """Return true if and only if the internal flag is true."""
+ """Return True if and only if the internal flag is true."""
return self._value
def set(self):
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list