5.10.1 キューオブジェクト

クラスQueueはキューオブジェクトを実装しており、以下のメソッドを持っています。このクラスは、他のキュー構造(例えばスタック)を実装するために派生させられるますが、継承可能なインタフェースはここでは説明しません。詳しいことはソースコードを見てください。公開メソッドは次のものです:

qsize( ): キューの大まかなサイズを返します。マルチスレッドセマンティクスにおいて、この値は信頼できません。

empty( ): キューが空ならTrueを返し、そうでないならFalseを返します。マルチスレッドセマンティクスにおいて、この値は信頼できません。

full( ): キューが満杯ならTrueを返し、そうでないならFalseを返します。マルチスレッドセマンティクスにおいて、この値は信頼できません。

put( item[, block[, timeout]])

itemをキューに入れます。もしオプション引数blockがTrueでtimeoutがNone(デフォルト)ならば、フリースロットが利用可能になるまでブロックします。 timeoutが正の値の場合、最大でtimeout秒間ブロックし、その時間内に空きスロットが利用可能にならなければ、例外Fullを送出します。他方(blockがFalse)、直ちにフリースロットが利用できるならば、キューにアイテムを置きます。できないならば、例外Fullを送出します (この場合timeoutは無視されます)。

バージョン 2.3 で新たに追加された仕様: the timeout parameter

put_nowait( item): put(item, False)と同じ意味です。

get( [block[, timeout]])

キューからアイテムを取り除き、それを返します。もしオプション引数blockがTrueでtimeoutがNone(デフォルト)ならば、アイテムが利用可能になるまでブロックします。もしtimeoutが正の値の場合、最大でtimeout秒間ブロックし、その時間内でアイテムが利用可能にならなければ、例外Emptyを送出します。他方(blockがFalse)、直ちにアイテムが利用できるならば、それを返します。できないならば、例外Emptyを送出します (この場合timeoutは無視されます)。

バージョン 2.3 で新たに追加された仕様: the timeout parameter

get_nowait( ): get(False)と同じ意味です。

キューに入れられたタスクが全て消費者スレッドに処理されたかどうかを追跡するために 2つのメソッドが提供されます。

task_done( )

過去にキューに入れられたタスクが完了した事を示します。キューの消費者スレッドに利用されます。タスクの取り出しに使われた、各 get() に対して、それに続く task_done() の呼び出しは、取り出したタスクに対する処理が完了した事をキューに教えます。

join() がブロックされていた場合、全itemが処理された (キューにput()された全てのitemに対して task_done() が呼び出されたことを意味します) 時に復帰します。

キューにあるよりitemの個数よりも多く呼び出された場合、 ValueError が送出されます。バージョン 2.5 で新たに追加された仕様です。

join( ): キューの中の全アイテムが処理される間でブロックします。
キューにitemが追加される度に、未完了タスクカウントが増やされます。消費者スレッドが task_done() を呼び出して、itemを受け取ってそれに対する処理が完了した事を知らせる度に、未完了タスクカウントが減らされます。未完了タスクカウントが0になったときに、join() のブロックが解除されます。バージョン 2.5 で新たに追加された仕様です。

キューに入れたタスクが完了するのを待つ例:

    def worker(): 
        while True: 
            item = q.get() 
            do_work(item) 
            q.task_done() 

    q = Queue() 
    for i in range(num_worker_threads): 
         t = Thread(target=worker)
         t.setDaemon(True)
         t.start() 

    for item in source():
        q.put(item) 

    q.join()       # 全タスクが完了するまでブロック

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。