mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

asyncio, Tulip issue 220: Update doc of asyncio.Queue, add join and task_done

Browse source 
methods
This commit is contained in:
Victor Stinner 2015-02-17 23:09:52 +01:00
parent e170ed27c6
commit f91d845797
1 changed files with 36 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

64
Doc/library/asyncio-sync.rst
View file

@ -310,6 +310,9 @@ Queue
be interrupted between calling :meth:`qsize` and doing an operation on the be interrupted between calling :meth:`qsize` and doing an operation on the
Queue. Queue.
.. versionchanged:: 3.4.3
New :meth:`join` and :meth:`task_done` methods.
.. method:: empty() .. method:: empty()
Return ``True`` if the queue is empty, ``False`` otherwise. Return ``True`` if the queue is empty, ``False`` otherwise.
@ -341,6 +344,20 @@ Queue
Return an item if one is immediately available, else raise Return an item if one is immediately available, else raise
:exc:`QueueEmpty`. :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) .. coroutinemethod:: put(item)
Put an item into the queue. If the queue is full, wait until a free slot Put an item into the queue. If the queue is full, wait until a free slot
@ -362,6 +379,23 @@ Queue
Number of items in the queue. 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 .. attribute:: maxsize
Number of items allowed in the queue. Number of items allowed in the queue.
@ -392,35 +426,9 @@ JoinableQueue
.. class:: JoinableQueue .. class:: JoinableQueue
A subclass of :class:`Queue` with :meth:`task_done` and :meth:`join` Deprecated alias for :class:`Queue`.
methods.
.. coroutinemethod:: join() .. deprecated:: 3.4.3
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 Exceptions