mirror of
https://github.com/python/cpython.git
synced 2024-11-27 20:04:41 +08:00
asyncio doc: move queues to a new page
This commit is contained in:
Victor Stinner
parent
7e91af3a91
commit
615a58eaab
167
Doc/library/asyncio-queue.rst
Normal file
167
Doc/library/asyncio-queue.rst
Normal file
@ -0,0 +1,167 @@
|
||||
.. currentmodule:: asyncio
|
||||
|
||||
Queues
|
||||
======
|
||||
|
||||
Queues:
|
||||
|
||||
* :class:`Queue`
|
||||
* :class:`PriorityQueue`
|
||||
* :class:`LifoQueue`
|
||||
* :class:`JoinableQueue`
|
||||
|
||||
asyncio queue API was designed to be close to classes of the :mod:`queue`
|
||||
module (:class:`~queue.Queue`, :class:`~queue.PriorityQueue`,
|
||||
:class:`~queue.LifoQueue`), but it has no *timeout* parameter. The
|
||||
:func:`asyncio.wait_for` function can be used to cancel a task after a timeout.
|
||||
|
||||
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.
|
||||
|
||||
.. versionchanged:: 3.4.3
|
||||
New :meth:`join` and :meth:`task_done` methods.
|
||||
|
||||
.. 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``.
|
||||
|
||||
.. coroutinemethod:: 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`.
|
||||
|
||||
.. coroutinemethod:: 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>`.
|
||||
|
||||
.. versionadded:: 3.4.3
|
||||
|
||||
.. coroutinemethod:: 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.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. versionadded:: 3.4.3
|
||||
|
||||
.. 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
|
||||
|
||||
Deprecated alias for :class:`Queue`.
|
||||
|
||||
.. deprecated:: 3.4.3
|
||||
|
||||
|
||||
Exceptions
|
||||
^^^^^^^^^^
|
||||
|
||||
.. exception:: QueueEmpty
|
||||
|
||||
Exception raised when the :meth:`~Queue.get_nowait` method is called on a
|
||||
:class:`Queue` object which is empty.
|
||||
|
||||
|
||||
.. exception:: QueueFull
|
||||
|
||||
Exception raised when the :meth:`~Queue.put_nowait` method is called on a
|
||||
:class:`Queue` object which is full.
|
||||
@ -9,22 +9,16 @@ Locks:
|
||||
* :class:`Lock`
|
||||
* :class:`Event`
|
||||
* :class:`Condition`
|
||||
|
||||
Semaphores:
|
||||
|
||||
* :class:`Semaphore`
|
||||
* :class:`BoundedSemaphore`
|
||||
|
||||
Queues:
|
||||
|
||||
* :class:`Queue`
|
||||
* :class:`PriorityQueue`
|
||||
* :class:`LifoQueue`
|
||||
* :class:`JoinableQueue`
|
||||
|
||||
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
|
||||
@ -290,157 +284,3 @@ BoundedSemaphore
|
||||
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.
|
||||
|
||||
.. versionchanged:: 3.4.3
|
||||
New :meth:`join` and :meth:`task_done` methods.
|
||||
|
||||
.. 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``.
|
||||
|
||||
.. coroutinemethod:: 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`.
|
||||
|
||||
.. coroutinemethod:: 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>`.
|
||||
|
||||
.. versionadded:: 3.4.3
|
||||
|
||||
.. coroutinemethod:: 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.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. versionadded:: 3.4.3
|
||||
|
||||
.. 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
|
||||
|
||||
Deprecated alias for :class:`Queue`.
|
||||
|
||||
.. deprecated:: 3.4.3
|
||||
|
||||
|
||||
Exceptions
|
||||
^^^^^^^^^^
|
||||
|
||||
.. exception:: QueueEmpty
|
||||
|
||||
Exception raised when the :meth:`~Queue.get_nowait` method is called on a
|
||||
:class:`Queue` object which is empty.
|
||||
|
||||
|
||||
.. exception:: QueueFull
|
||||
|
||||
Exception raised when the :meth:`~Queue.put_nowait` method is called on a
|
||||
:class:`Queue` object which is full.
|
||||
|
||||
@ -58,6 +58,7 @@ Table of contents:
|
||||
asyncio-stream.rst
|
||||
asyncio-subprocess.rst
|
||||
asyncio-sync.rst
|
||||
asyncio-queue.rst
|
||||
asyncio-dev.rst
|
||||
|
||||
.. seealso::
|
||||
|
||||
Loading…
Reference in New Issue
Block a user