bpo-14976: Reentrant simple queue (#3346) · python/cpython@94e1696 (original) (raw)
`@@ -23,8 +23,14 @@ the first retrieved (operating like a stack). With a priority queue,
`
23
23
`` the entries are kept sorted (using the :mod:heapq module) and the
``
24
24
`lowest valued entry is retrieved first.
`
25
25
``
26
``
`-
Internally, the module uses locks to temporarily block competing threads;
`
27
``
`-
however, it is not designed to handle reentrancy within a thread.
`
``
26
`+
Internally, those three types of queues use locks to temporarily block
`
``
27
`+
competing threads; however, they are not designed to handle reentrancy
`
``
28
`+
within a thread.
`
``
29
+
``
30
`+
In addition, the module implements a "simple"
`
``
31
`` +
:abbr:FIFO (first-in, first-out) queue type where
``
``
32
`+
specific implementations can provide additional guarantees
`
``
33
`+
in exchange for the smaller functionality.
`
28
34
``
29
35
`` The :mod:queue module defines the following classes and exceptions:
``
30
36
``
`` @@ -67,6 +73,14 @@ The :mod:queue module defines the following classes and exceptions:
``
67
73
` priority: int
`
68
74
` item: Any=field(compare=False)
`
69
75
``
``
76
`+
.. class:: SimpleQueue()
`
``
77
+
``
78
`` +
Constructor for an unbounded :abbr:FIFO (first-in, first-out) queue.
``
``
79
`+
Simple queues lack advanced functionality such as task tracking.
`
``
80
+
``
81
`+
.. versionadded:: 3.7
`
``
82
+
``
83
+
70
84
`.. exception:: Empty
`
71
85
``
72
86
`` Exception raised when non-blocking :meth:~Queue.get (or
``
`@@ -201,6 +215,60 @@ Example of how to wait for enqueued tasks to be completed::
`
201
215
` t.join()
`
202
216
``
203
217
``
``
218
`+
SimpleQueue Objects
`
``
219
`+
`
``
220
+
``
221
`` +
:class:SimpleQueue objects provide the public methods described below.
``
``
222
+
``
223
`+
.. method:: SimpleQueue.qsize()
`
``
224
+
``
225
`+
Return the approximate size of the queue. Note, qsize() > 0 doesn't
`
``
226
`+
guarantee that a subsequent get() will not block.
`
``
227
+
``
228
+
``
229
`+
.. method:: SimpleQueue.empty()
`
``
230
+
``
231
Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
``
232
returns ``False`` it doesn't guarantee that a subsequent call to get()
``
233
`+
will not block.
`
``
234
+
``
235
+
``
236
`+
.. method:: SimpleQueue.put(item, block=True, timeout=None)
`
``
237
+
``
238
`+
Put item into the queue. The method never blocks and always succeeds
`
``
239
`+
(except for potential low-level errors such as failure to allocate memory).
`
``
240
`+
The optional args block and timeout are ignored and only provided
`
``
241
`` +
for compatibility with :meth:Queue.put.
``
``
242
+
``
243
`+
.. impl-detail::
`
``
244
`+
This method has a C implementation which is reentrant. That is, a
`
``
245
``put()`` or ``get()`` call can be interrupted by another ``put()``
``
246
`+
call in the same thread without deadlocking or corrupting internal
`
``
247
`+
state inside the queue. This makes it appropriate for use in
`
``
248
destructors such as ``__del__`` methods or :mod:`weakref` callbacks.
``
249
+
``
250
+
``
251
`+
.. method:: SimpleQueue.put_nowait(item)
`
``
252
+
``
253
Equivalent to ``put(item)``, provided for compatibility with
``
254
`` +
:meth:Queue.put_nowait.
``
``
255
+
``
256
+
``
257
`+
.. method:: SimpleQueue.get(block=True, timeout=None)
`
``
258
+
``
259
`+
Remove and return an item from the queue. If optional args block is true and
`
``
260
*timeout* is ``None`` (the default), block if necessary until an item is available.
``
261
`+
If timeout is a positive number, it blocks at most timeout seconds and
`
``
262
`` +
raises the :exc:Empty exception if no item was available within that time.
``
``
263
`+
Otherwise (block is false), return an item if one is immediately available,
`
``
264
`` +
else raise the :exc:Empty exception (timeout is ignored in that case).
``
``
265
+
``
266
+
``
267
`+
.. method:: SimpleQueue.get_nowait()
`
``
268
+
``
269
Equivalent to ``get(False)``.
``
270
+
``
271
+
204
272
`.. seealso::
`
205
273
``
206
274
`` Class :class:multiprocessing.Queue
``
`@@ -210,4 +278,3 @@ Example of how to wait for enqueued tasks to be completed::
`
210
278
`` :class:collections.deque is an alternative implementation of unbounded
``
211
279
`` queues with fast atomic :meth:~collections.deque.append and
``
212
280
`` :meth:~collections.deque.popleft operations that do not require locking.
``
213
``
-