queue
--- 同期キュークラス¶
ソースコード: Lib/queue.py
queue
モジュールは、複数プロデューサ-複数コンシューマ(multi-producer, multi-consumer)キューを実装します。これは、複数のスレッドの間で情報を安全に交換しなければならないときのマルチスレッドプログラミングで特に有益です。このモジュールの Queue
クラスは、必要なすべてのロックセマンティクスを実装しています。
このモジュールでは3種類のキューが実装されています。それらはキューから取り出されるエントリの順番だけが違います。 FIFO キューでは、最初に追加されたエントリが最初に取り出されます。 LIFO キューでは、最後に追加されたエントリが最初に取り出されます(スタックのように振る舞います)。 優先順位付きキュー(priority queue)では、エントリは(heapq
モジュールを利用して)ソートされ、 最も低い値のエントリが最初に取り出されます。
内部的には、これらの3種類のキューは競争スレッドを一時的にブロックするためにロックを使っています; しかし、スレッド内での再入を扱うようには設計されていません。
In addition, the module implements a "simple"
FIFO queue type, SimpleQueue
, whose
specific implementation provides additional guarantees
in exchange for the smaller functionality.
queue
モジュールは以下のクラスと例外を定義します:
- class queue.Queue(maxsize=0)¶
FIFO キューのコンストラクタです。 maxsize はキューに入れられる要素数の上限を設定する整数です。 いったんこの大きさに達したら、挿入処理はキューの要素が消費されるまでブロックされます。 maxsize が0以下の場合は、キューの大きさは無限です。
- class queue.LifoQueue(maxsize=0)¶
LIFO キューのコンストラクタです。 maxsize はキューに入れられる要素数の上限を設定する整数です。 いったんこの大きさに達したら、挿入処理はキューの要素が消費されるまでブロックされます。 maxsize が0以下の場合は、キューの大きさは無限です。
- class queue.PriorityQueue(maxsize=0)¶
優先順位付きキューのコンストラクタです。maxsize はキューに置くことのできる要素数の上限を設定する整数です。いったんこの大きさに達したら、挿入はキューの要素が消費されるまでブロックされます。もし maxsize が0以下であるならば、キューの大きさは無限です。
最小の値を持つ要素が最初に検索されます (最小の値を持つ値は、
min(entries)
によって返されるものです)。典型的な要素のパターンは、(priority_number, data)
形式のタプルです。If the data elements are not comparable, the data can be wrapped in a class that ignores the data item and only compares the priority number:
from dataclasses import dataclass, field from typing import Any @dataclass(order=True) class PrioritizedItem: priority: int item: Any=field(compare=False)
- class queue.SimpleQueue¶
Constructor for an unbounded FIFO queue. Simple queues lack advanced functionality such as task tracking.
Added in version 3.7.
- exception queue.Empty¶
空の
Queue
オブジェクトで、非ブロックメソッドget()
(またはget_nowait()
) が呼ばれたとき、送出される例外です。
- exception queue.Full¶
満杯の
Queue
オブジェクトで、非ブロックメソッドput()
(またはput_nowait()
) が呼ばれたとき、送出される例外です。
- exception queue.ShutDown¶
Exception raised when
put()
orget()
is called on aQueue
object which has been shut down.Added in version 3.13.
キューオブジェクト¶
キューオブジェクト(Queue
, LifoQueue
, PriorityQueue
)は、以下のpublicメソッドを提供しています。
- Queue.qsize()¶
キューの近似サイズを返します。ここで、qsize() > 0 は後続の get() がブロックしないことを保証しないこと、また qsize() < maxsize が put() がブロックしないことを保証しないことに注意してください。
- Queue.empty()¶
キューが空の場合は
True
を返し、そうでなければFalse
を返します。empty() がTrue
を返しても、後続の put() の呼び出しがブロックしないことは保証されません。同様に、empty() がFalse
を返しても、後続の get() の呼び出しがブロックしないことは保証されません。
- Queue.full()¶
キューが一杯の場合は
True
を返し、そうでなければFalse
を返します。full() がTrue
を返しても、後続の get() の呼び出しがブロックしないことは保証されません。同様に、full() がFalse
を返しても、後続の put() の呼び出しがブロックしないことは保証されません。
- Queue.put(item, block=True, timeout=None)¶
item をキューに入れます。 もしオプション引数 block が真で timeout が
None
(デフォルト) の場合は、必要であればフリースロットが利用可能になるまでブロックします。 timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内に空きスロットが利用可能にならなければ、例外Full
を送出します。 そうでない場合 (block が偽) は、空きスロットが直ちに利用できるならば、キューにアイテムを置きます。 できないならば、例外Full
を送出します (この場合 timeout は無視されます)。Raises
ShutDown
if the queue has been shut down.
- Queue.put_nowait(item)¶
put(item, block=False)
と等価です。
- Queue.get(block=True, timeout=None)¶
キューからアイテムを取り除き、それを返します。 オプション引数 block が真で timeout が
None
(デフォルト) の場合は、必要であればアイテムが取り出せるようになるまでブロックします。 もし timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内でアイテムが取り出せるようにならなければ、例外Empty
を送出します。 そうでない場合 (block が偽) は、直ちにアイテムが取り出せるならば、それを返します。 できないならば、例外Empty
を送出します (この場合 timeout は無視されます)。Prior to 3.0 on POSIX systems, and for all versions on Windows, if block is true and timeout is
None
, this operation goes into an uninterruptible wait on an underlying lock. This means that no exceptions can occur, and in particular a SIGINT will not trigger aKeyboardInterrupt
.Raises
ShutDown
if the queue has been shut down and is empty, or if the queue has been shut down immediately.
- Queue.get_nowait()¶
get(False)
と等価です。
キューに入れられたタスクが全てコンシューマスレッドに処理されたかどうかを追跡するために 2つのメソッドが提供されます。
- Queue.task_done()¶
過去にキューに入れられたタスクが完了した事を示します。キューのコンシューマスレッドに利用されます。タスクの取り出しに使われた各
get()
の後にtask_done()
を呼び出すと、取り出したタスクに対する処理が完了した事をキューに教えます。join()
がブロックされていた場合、全itemが処理された (キューにput()
された全てのitemに対してtask_done()
が呼び出されたことを意味します) 時に復帰します。shutdown(immediate=True)
callstask_done()
for each remaining item in the queue.キューにある要素より多く呼び出された場合
ValueError
が発生します。
- Queue.join()¶
キューにあるすべてのアイテムが取り出されて処理されるまでブロックします。
未完了のタスクのカウント値はキューにアイテムが追加されるときは常に加算され、コンシューマースレッドが
task_done()
を呼び出してアイテムの回収とその全処理の完了が示されるときは常に減算されます。未完了のタスクのカウント値がゼロになった場合、join()
のブロックが解除されます。
キューに入れたタスクが完了するのを待つ例:
import threading
import queue
q = queue.Queue()
def worker():
while True:
item = q.get()
print(f'Working on {item}')
print(f'Finished {item}')
q.task_done()
# Turn-on the worker thread.
threading.Thread(target=worker, daemon=True).start()
# Send thirty task requests to the worker.
for item in range(30):
q.put(item)
# Block until all tasks are done.
q.join()
print('All work completed')
Terminating queues¶
Queue
objects can be made to prevent further interaction by shutting
them down.
- Queue.shutdown(immediate=False)¶
Shut down the queue, making
get()
andput()
raiseShutDown
.By default,
get()
on a shut down queue will only raise once the queue is empty. Set immediate to true to makeget()
raise immediately instead.All blocked callers of
put()
andget()
will be unblocked. If immediate is true, a task will be marked as done for each remaining item in the queue, which may unblock callers ofjoin()
.Added in version 3.13.
SimpleQueue オブジェクト¶
SimpleQueue
オブジェクトは以下のpublicメソッドを提供しています。
- SimpleQueue.qsize()¶
キューの近似サイズを返します。ここで、qsize() > 0 であるからといって、後続の get() の呼び出しがブロックしないことが保証されないことに注意してください。
- SimpleQueue.empty()¶
キューが空の場合は
True
を返し、そうでなければFalse
を返します。 empty() がFalse
を返しても、後続の get() の呼び出しがブロックしないことは保証されません。
- SimpleQueue.put(item, block=True, timeout=None)¶
Put item into the queue. The method never blocks and always succeeds (except for potential low-level errors such as failure to allocate memory). The optional args block and timeout are ignored and only provided for compatibility with
Queue.put()
.CPython 実装の詳細: This method has a C implementation which is reentrant. That is, a
put()
orget()
call can be interrupted by anotherput()
call in the same thread without deadlocking or corrupting internal state inside the queue. This makes it appropriate for use in destructors such as__del__
methods orweakref
callbacks.
- SimpleQueue.put_nowait(item)¶
put(item, block=False)
と等価です。Queue.put_nowait()
との互換性のためのメソッドです。
- SimpleQueue.get(block=True, timeout=None)¶
キューからアイテムを取り除き、それを返します。 オプション引数 block が真で timeout が
None
(デフォルト) の場合は、必要であればアイテムが取り出せるようになるまでブロックします。 もし timeout が正の数の場合は、最大で timeout 秒間ブロックし、その時間内でアイテムが取り出せるようにならなければ、例外Empty
を送出します。 そうでない場合 (block が偽) は、直ちにアイテムが取り出せるならば、それを返します。 できないならば、例外Empty
を送出します (この場合 timeout は無視されます)。
- SimpleQueue.get_nowait()¶
get(False)
と等価です。
参考
multiprocessing.Queue
クラス(マルチスレッドではなく) マルチプロセスの文脈で使用されるキュークラス。
collections.deque
is an alternative implementation of unbounded
queues with fast atomic append()
and
popleft()
operations that do not require locking
and also support indexing.