Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1313af2

Browse files
vstinnervstinner
committed
Merge 3.4 (asyncio doc)
2 parents 961dfa1 + 8370496 commit 1313af2

8 files changed

Lines changed: 201 additions & 166 deletions

‎Doc/library/asyncio-eventloop.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ It provides multiple facilities, amongst which:
2222

2323
Base class of event loops.
2424

25+
This class is :ref:`not thread safe <asyncio-multithreading>`.
26+
2527
Run an event loop
2628
-----------------
2729

@@ -104,6 +106,9 @@ keywords to your callback, use :func:`functools.partial`. For example,
104106

105107
Like :meth:`call_soon`, but thread safe.
106108

109+
See the :ref:`concurrency and multithreading <asyncio-multithreading>`
110+
section of the documentation.
111+
107112

108113
.. _asyncio-delayed-calls:
109114

‎Doc/library/asyncio-protocol.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ then call the transport's methods for various purposes.
2323
subprocess pipes. The methods available on a transport depend on
2424
the transport's kind.
2525

26+
The transport classes are :ref:`not thread safe <asyncio-multithreading>`.
27+
2628

2729
BaseTransport
2830
-------------

‎Doc/library/asyncio-queue.rst‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
.. currentmodule:: asyncio
2+
3+
Queues
4+
======
5+
6+
Queues:
7+
8+
* :class:`Queue`
9+
* :class:`PriorityQueue`
10+
* :class:`LifoQueue`
11+
* :class:`JoinableQueue`
12+
13+
asyncio queue API was designed to be close to classes of the :mod:`queue`
14+
module (:class:`~queue.Queue`, :class:`~queue.PriorityQueue`,
15+
:class:`~queue.LifoQueue`), but it has no *timeout* parameter. The
16+
:func:`asyncio.wait_for` function can be used to cancel a task after a timeout.
17+
18+
Queue
19+
-----
20+
21+
.. class:: Queue(maxsize=0, \*, loop=None)
22+
23+
A queue, useful for coordinating producer and consumer coroutines.
24+
25+
If *maxsize* is less than or equal to zero, the queue size is infinite. If
26+
it is an integer greater than ``0``, then ``yield from put()`` will block
27+
when the queue reaches *maxsize*, until an item is removed by :meth:`get`.
28+
29+
Unlike the standard library :mod:`queue`, you can reliably know this Queue's
30+
size with :meth:`qsize`, since your single-threaded asyncio application won't
31+
be interrupted between calling :meth:`qsize` and doing an operation on the
32+
Queue.
33+
34+
This class is :ref:`not thread safe <asyncio-multithreading>`.
35+
36+
.. versionchanged:: 3.4.3
37+
New :meth:`join` and :meth:`task_done` methods.
38+
39+
.. method:: empty()
40+
41+
Return ``True`` if the queue is empty, ``False`` otherwise.
42+
43+
.. method:: full()
44+
45+
Return ``True`` if there are :attr:`maxsize` items in the queue.
46+
47+
.. note::
48+
49+
If the Queue was initialized with ``maxsize=0`` (the default), then
50+
:meth:`full()` is never ``True``.
51+
52+
.. coroutinemethod:: get()
53+
54+
Remove and return an item from the queue. If queue is empty, wait until
55+
an item is available.
56+
57+
This method is a :ref:`coroutine <coroutine>`.
58+
59+
.. seealso::
60+
61+
The :meth:`empty` method.
62+
63+
.. method:: get_nowait()
64+
65+
Remove and return an item from the queue.
66+
67+
Return an item if one is immediately available, else raise
68+
:exc:`QueueEmpty`.
69+
70+
.. coroutinemethod:: join()
71+
72+
Block until all items in the queue have been gotten and processed.
73+
74+
The count of unfinished tasks goes up whenever an item is added to the
75+
queue. The count goes down whenever a consumer thread calls
76+
:meth:`task_done` to indicate that the item was retrieved and all work on
77+
it is complete. When the count of unfinished tasks drops to zero,
78+
:meth:`join` unblocks.
79+
80+
This method is a :ref:`coroutine <coroutine>`.
81+
82+
.. versionadded:: 3.4.3
83+
84+
.. coroutinemethod:: put(item)
85+
86+
Put an item into the queue. If the queue is full, wait until a free slot
87+
is available before adding item.
88+
89+
This method is a :ref:`coroutine <coroutine>`.
90+
91+
.. seealso::
92+
93+
The :meth:`full` method.
94+
95+
.. method:: put_nowait(item)
96+
97+
Put an item into the queue without blocking.
98+
99+
If no free slot is immediately available, raise :exc:`QueueFull`.
100+
101+
.. method:: qsize()
102+
103+
Number of items in the queue.
104+
105+
.. method:: task_done()
106+
107+
Indicate that a formerly enqueued task is complete.
108+
109+
Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a
110+
subsequent call to :meth:`task_done` tells the queue that the processing
111+
on the task is complete.
112+
113+
If a :meth:`join` is currently blocking, it will resume when all items
114+
have been processed (meaning that a :meth:`task_done` call was received
115+
for every item that had been :meth:`~Queue.put` into the queue).
116+
117+
Raises :exc:`ValueError` if called more times than there were items
118+
placed in the queue.
119+
120+
.. versionadded:: 3.4.3
121+
122+
.. attribute:: maxsize
123+
124+
Number of items allowed in the queue.
125+
126+
127+
PriorityQueue
128+
-------------
129+
130+
.. class:: PriorityQueue
131+
132+
A subclass of :class:`Queue`; retrieves entries in priority order (lowest
133+
first).
134+
135+
Entries are typically tuples of the form: (priority number, data).
136+
137+
138+
LifoQueue
139+
---------
140+
141+
.. class:: LifoQueue
142+
143+
A subclass of :class:`Queue` that retrieves most recently added entries
144+
first.
145+
146+
147+
JoinableQueue
148+
^^^^^^^^^^^^^
149+
150+
.. class:: JoinableQueue
151+
152+
Deprecated alias for :class:`Queue`.
153+
154+
.. deprecated:: 3.4.3
155+
156+
157+
Exceptions
158+
^^^^^^^^^^
159+
160+
.. exception:: QueueEmpty
161+
162+
Exception raised when the :meth:`~Queue.get_nowait` method is called on a
163+
:class:`Queue` object which is empty.
164+
165+
166+
.. exception:: QueueFull
167+
168+
Exception raised when the :meth:`~Queue.put_nowait` method is called on a
169+
:class:`Queue` object which is full.

‎Doc/library/asyncio-stream.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,8 @@ StreamReader
8585

8686
.. class:: StreamReader(limit=None, loop=None)
8787

88+
This class is :ref:`not thread safe <asyncio-multithreading>`.
89+
8890
.. method:: exception()
8991

9092
Get the exception.
@@ -155,6 +157,8 @@ StreamWriter
155157
wait for flow control. It also adds a transport attribute which references
156158
the :class:`Transport` directly.
157159

160+
This class is :ref:`not thread safe <asyncio-multithreading>`.
161+
158162
.. attribute:: transport
159163

160164
Transport.

‎Doc/library/asyncio-subprocess.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,9 @@ Process
193193
:meth:`~subprocess.Popen.wait` method of the :class:`~subprocess.Popen`
194194
class is implemented as a busy loop.
195195

196+
This class is :ref:`not thread safe <asyncio-multithreading>`. See also the
197+
:ref:`Subprocess and threads <asyncio-subprocess-threads>` section.
198+
196199
.. coroutinemethod:: wait()
197200

198201
Wait for child process to terminate. Set and return :attr:`returncode`
@@ -310,6 +313,8 @@ are limits:
310313
subprocesses from other threads. Call the :func:`get_child_watcher`
311314
function in the main thread to instantiate the child watcher.
312315

316+
The :class:`asyncio.subprocess.Process` class is not thread safe.
317+
313318
.. seealso::
314319

315320
The :ref:`Concurrency and multithreading in asyncio

0 commit comments

Comments
 (0)