[Python-checkins] cpython (3.4): asyncio doc: move queues to a new page
victor.stinner
python-checkins at python.org
Wed Feb 25 14:26:17 CET 2015
https://hg.python.org/cpython/rev/fee2385e2eee
changeset: 94740:fee2385e2eee
branch: 3.4
parent: 94738:c113cdfef1e1
user: Victor Stinner <victor.stinner at gmail.com>
date: Wed Feb 25 13:55:43 2015 +0100
summary:
asyncio doc: move queues to a new page
files:
Doc/library/asyncio-sync.rst | 295 +----------------------
Doc/library/asyncio-sync.rst | 172 +------------
Doc/library/asyncio.rst | 1 +
3 files changed, 15 insertions(+), 453 deletions(-)
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-queue.rst
copy from Doc/library/asyncio-sync.rst
copy to Doc/library/asyncio-queue.rst
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -1,16 +1,7 @@
.. currentmodule:: asyncio
-.. _asyncio-sync:
-Synchronization primitives
-==========================
-
-Locks:
-
-* :class:`Lock`
-* :class:`Event`
-* :class:`Condition`
-* :class:`Semaphore`
-* :class:`BoundedSemaphore`
+Queues
+======
Queues:
@@ -19,284 +10,14 @@
* :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`,
-: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
+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.
-Locks
+Queue
-----
-Lock
-^^^^
-
-.. 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 management 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 the lock is acquired.
-
- .. coroutinemethod:: acquire()
-
- Acquire a lock.
-
- This method blocks until the lock is unlocked, then sets it to locked and
- returns ``True``.
-
- This method is 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.
-
-
-Event
-^^^^^
-
-.. 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:: 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:: 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.
-
- .. coroutinemethod:: 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 is a :ref:`coroutine <coroutine>`.
-
-
-Condition
-^^^^^^^^^
-
-.. class:: Condition(lock=None, \*, 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.
-
- If the *lock* argument is given and not ``None``, it must be a :class:`Lock`
- object, and it is used as the underlying lock. Otherwise,
- a new :class:`Lock` object is created and used as the underlying lock.
-
- .. coroutinemethod:: acquire()
-
- Acquire the underlying lock.
-
- This method blocks until the lock is unlocked, then sets it to locked and
- returns ``True``.
-
- This method is 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:: locked()
-
- Return ``True`` if the underlying lock is acquired.
-
- .. 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.
-
- .. method:: release()
-
- Release the underlying 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.
-
- .. coroutinemethod:: 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 is a :ref:`coroutine <coroutine>`.
-
- .. coroutinemethod:: 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 is a :ref:`coroutine <coroutine>`.
-
-
-Semaphores
-----------
-
-Semaphore
-^^^^^^^^^
-
-.. 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 management 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.
-
- .. coroutinemethod:: 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 is a :ref:`coroutine <coroutine>`.
-
- .. method:: locked()
-
- Returns ``True`` if semaphore can not be acquired immediately.
-
- .. 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
- larger than zero again, wake up that coroutine.
-
-
-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.
@@ -402,7 +123,7 @@
PriorityQueue
-^^^^^^^^^^^^^
+-------------
.. class:: PriorityQueue
@@ -413,7 +134,7 @@
LifoQueue
-^^^^^^^^^
+---------
.. class:: LifoQueue
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -9,22 +9,16 @@
* :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 @@
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.
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -58,6 +58,7 @@
asyncio-stream.rst
asyncio-subprocess.rst
asyncio-sync.rst
+ asyncio-queue.rst
asyncio-dev.rst
.. seealso::
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list