summaryrefslogtreecommitdiff
path: root/Doc/library/asyncio-sync.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/library/asyncio-sync.rst')
-rw-r--r--Doc/library/asyncio-sync.rst192
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.