diff options
Diffstat (limited to 'Doc/library/asyncio-sync.rst')
| -rw-r--r-- | Doc/library/asyncio-sync.rst | 192 |
1 files changed, 24 insertions, 168 deletions
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 80974d9ee1..622ff5fd66 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -9,22 +9,16 @@ Locks: * :class:`Lock` * :class:`Event` * :class:`Condition` -* :class:`Semaphore` -* :class:`BoundedSemaphore` -Queues: +Semaphores: -* :class:`Queue` -* :class:`PriorityQueue` -* :class:`LifoQueue` -* :class:`JoinableQueue` +* :class:`Semaphore` +* :class:`BoundedSemaphore` -asyncio locks and queues API were designed to be close to classes of the -:mod:`threading` module (:class:`~threading.Lock`, :class:`~threading.Event`, +asyncio lock API was designed to be close to classes of the :mod:`threading` +module (:class:`~threading.Lock`, :class:`~threading.Event`, :class:`~threading.Condition`, :class:`~threading.Semaphore`, -:class:`~threading.BoundedSemaphore`) and the :mod:`queue` module -(:class:`~queue.Queue`, :class:`~queue.PriorityQueue`, -:class:`~queue.LifoQueue`), but they have no *timeout* parameter. The +:class:`~threading.BoundedSemaphore`), but it has no *timeout* parameter. The :func:`asyncio.wait_for` function can be used to cancel a task after a timeout. Locks @@ -60,6 +54,8 @@ Lock Locks also support the context management protocol. ``(yield from lock)`` should be used as context manager expression. + This class is :ref:`not thread safe <asyncio-multithreading>`. + Usage:: lock = Lock() @@ -89,7 +85,7 @@ Lock Return ``True`` if the lock is acquired. - .. method:: acquire() + .. coroutinemethod:: acquire() Acquire a lock. @@ -123,6 +119,8 @@ Event method. The :meth:`wait` method blocks until the flag is true. The flag is initially false. + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. method:: clear() Reset the internal flag to false. Subsequently, coroutines calling @@ -139,7 +137,7 @@ Event true are awakened. Coroutine that call :meth:`wait` once the flag is true will not block at all. - .. method:: wait() + .. coroutinemethod:: wait() Block until the internal flag is true. @@ -166,7 +164,9 @@ Condition object, and it is used as the underlying lock. Otherwise, a new :class:`Lock` object is created and used as the underlying lock. - .. method:: acquire() + This class is :ref:`not thread safe <asyncio-multithreading>`. + + .. coroutinemethod:: acquire() Acquire the underlying lock. @@ -213,7 +213,7 @@ Condition There is no return value. - .. method:: wait() + .. coroutinemethod:: wait() Wait until notified. @@ -227,7 +227,7 @@ Condition This method is a :ref:`coroutine <coroutine>`. - .. method:: wait_for(predicate) + .. coroutinemethod:: wait_for(predicate) Wait until a predicate becomes true. @@ -258,7 +258,9 @@ Semaphore defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError` is raised. - .. method:: acquire() + This class is :ref:`not thread safe <asyncio-multithreading>`. + + .. coroutinemethod:: acquire() Acquire a semaphore. @@ -273,7 +275,7 @@ Semaphore Returns ``True`` if semaphore can not be acquired immediately. - .. method:: release() + .. coroutinemethod:: 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 @@ -285,154 +287,8 @@ BoundedSemaphore .. 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. - - -Queues ------- - -Queue -^^^^^ - -.. class:: Queue(maxsize=0, \*, loop=None) - - A queue, useful for coordinating producer and consumer coroutines. - - If *maxsize* is less than or equal to zero, the queue size is infinite. If - it is an integer greater than ``0``, then ``yield from put()`` will block - when the queue reaches *maxsize*, until an item is removed by :meth:`get`. - - Unlike the standard library :mod:`queue`, you can reliably know this Queue's - size with :meth:`qsize`, since your single-threaded asyncio application won't - be interrupted between calling :meth:`qsize` and doing an operation on the - Queue. - - .. method:: empty() - - Return ``True`` if the queue is empty, ``False`` otherwise. - - .. method:: full() - - Return ``True`` if there are :attr:`maxsize` items in the queue. - - .. note:: - - If the Queue was initialized with ``maxsize=0`` (the default), then - :meth:`full()` is never ``True``. - - .. method:: get() - - Remove and return an item from the queue. If queue is empty, wait until - an item is available. - - This method is a :ref:`coroutine <coroutine>`. - - .. seealso:: - - The :meth:`empty` method. - - .. method:: get_nowait() - - Remove and return an item from the queue. - - Return an item if one is immediately available, else raise - :exc:`QueueEmpty`. - - .. method:: put(item) - - Put an item into the queue. If the queue is full, wait until a free slot - is available before adding item. - - This method is a :ref:`coroutine <coroutine>`. - - .. seealso:: - - The :meth:`full` method. - - .. method:: put_nowait(item) - - Put an item into the queue without blocking. - - If no free slot is immediately available, raise :exc:`QueueFull`. - - .. method:: qsize() - - Number of items in the queue. - - .. attribute:: maxsize - - Number of items allowed in the queue. - - -PriorityQueue -^^^^^^^^^^^^^ - -.. class:: PriorityQueue - - A subclass of :class:`Queue`; retrieves entries in priority order (lowest - first). - - Entries are typically tuples of the form: (priority number, data). - - -LifoQueue -^^^^^^^^^ - -.. class:: LifoQueue - - A subclass of :class:`Queue` that retrieves most recently added entries - first. - - -JoinableQueue -^^^^^^^^^^^^^ - -.. class:: JoinableQueue - - A subclass of :class:`Queue` with :meth:`task_done` and :meth:`join` - methods. - - .. method:: join() - - Block until all items in the queue have been gotten and processed. - - The count of unfinished tasks goes up whenever an item is added to the - queue. The count goes down whenever a consumer thread calls - :meth:`task_done` to indicate that the item was retrieved and all work on - it is complete. When the count of unfinished tasks drops to zero, - :meth:`join` unblocks. - - This method is a :ref:`coroutine <coroutine>`. - - .. method:: task_done() - - Indicate that a formerly enqueued task is complete. - - Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a - subsequent call to :meth:`task_done` tells the queue that the processing - on the task is complete. - - If a :meth:`join` is currently blocking, it will resume when all items - have been processed (meaning that a :meth:`task_done` call was received - for every item that had been :meth:`~Queue.put` into the queue). - - Raises :exc:`ValueError` if called more times than there were items - placed in the queue. - - -Exceptions -^^^^^^^^^^ - -.. exception:: QueueEmpty - - Exception raised when the :meth:`~Queue.get_nowait` method is called on a - :class:`Queue` object which is empty. - + A bounded semaphore implementation. Inherit from :class:`Semaphore`. -.. exception:: QueueFull + This raises :exc:`ValueError` in :meth:`~Semaphore.release` if it would + increase the value above the initial value. - Exception raised when the :meth:`~Queue.put_nowait` method is called on a - :class:`Queue` object which is full. |