\section{\module{Queue} ---
         同期キュークラス}

\declaremodule{standard}{Queue}
\modulesynopsis{同期キュークラス}


\module{Queue}モジュールは、多生産者-多消費者FIFOキューを実装します。
これは、複数のスレッドの間で情報を安全に交換しなければならないときの
スレッドプログラミングで特に有益です。
このモジュールの\class{Queue}クラスは、
必要なすべてのロックセマンティクスを実装しています。
これはPythonのスレッドサポートの状況に依存します。


\module{Queue}モジュールは以下のクラスと例外を定義します:


\begin{classdesc}{Queue}{maxsize}
クラスのコンストラクタです。
\var{maxsize}はキューに置くことのできる要素数の上限を設定する整数です。
いったんこの大きさに達したら、挿入はキューの要素が消費されるまでブロック
されます。
もし\var{maxsize}が0以下であるならば、キューの大きさは無限です。
\end{classdesc}

\begin{excdesc}{Empty}
空な\class{Queue}オブジェクトで、
非ブロックメソッドとして\method{get()}(または\method{get_nowait()})
が呼ばれたとき、送出される例外です。
\end{excdesc}

\begin{excdesc}{Full}
満杯な\class{Queue}オブジェクトで、
非ブロックメソッドとして\method{put()}(または\method{put_nowait()})
が呼ばれたとき、送出される例外です。
\end{excdesc}

\subsection{キューオブジェクト}
\label{QueueObjects}

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

\begin{methoddesc}[Queue]{qsize}{}
キューの大まかなサイズを返します。
マルチスレッドセマンティクスにおいて、この値は信頼できません。
\end{methoddesc}

\begin{methoddesc}[Queue]{empty}{}
キューが空なら\code{True}を返し、そうでないなら\code{False}を返します。
マルチスレッドセマンティクスにおいて、この値は信頼できません。
\end{methoddesc}

\begin{methoddesc}[Queue]{full}{}
キューが満杯なら\code{True}を返し、そうでないなら\code{False}を返します。
マルチスレッドセマンティクスにおいて、この値は信頼できません。
\end{methoddesc}

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

\versionadded[the timeout parameter]{2.3}

\end{methoddesc}

\begin{methoddesc}[Queue]{put_nowait}{item}
\code{put(\var{item}, False)}と同じ意味です。
\end{methoddesc}

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

\versionadded[the timeout parameter]{2.3}

\end{methoddesc}

\begin{methoddesc}[Queue]{get_nowait}{}
\code{get(False)}と同じ意味です。
\end{methoddesc}

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

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

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

キューにあるよりitemの個数よりも多く呼び出された場合、 \exception{ValueError} が送出されます。
\versionadded{2.5}
\end{methoddesc}

\begin{methoddesc}[Queue]{join}{}
キューの中の全アイテムが処理される間でブロックします。

キューにitemが追加される度に、未完了タスクカウントが増やされます。
消費者スレッドが \method{task_done()} を呼び出して、itemを受け取ってそれに
対する処理が完了した事を知らせる度に、未完了タスクカウントが減らされます。
未完了タスクカウントが0になったときに、join() のブロックが解除されます。
\versionadded{2.5}
\end{methoddesc}

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

\begin{verbatim}
    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()       # 全タスクが完了するまでブロック
\end{verbatim}
