"Queue" — A synchronized queue class
************************************

注釈: The "Queue" module has been renamed to "queue" in Python 3.
  The *2to3* tool will automatically adapt imports when converting
  your sources to Python 3.

**Source code:** Lib/Queue.py

======================================================================

The "Queue" module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must
be exchanged safely between multiple threads.  The "Queue" class in
this module implements all the required locking semantics.  It depends
on the availability of thread support in Python; see the "threading"
module.

The module implements three types of queue, which differ only in the
order in which the entries are retrieved.  In a FIFO queue, the first
tasks added are the first retrieved. In a LIFO queue, the most
recently added entry is the first retrieved (operating like a stack).
With a priority queue, the entries are kept sorted (using the "heapq"
module) and the lowest valued entry is retrieved first.

The "Queue" module defines the following classes and exceptions:

class Queue.Queue(maxsize=0)

   Constructor for a FIFO queue.  *maxsize* is an integer that sets
   the upperbound limit on the number of items that can be placed in
   the queue.  Insertion will block once this size has been reached,
   until queue items are consumed.  If *maxsize* is less than or equal
   to zero, the queue size is infinite.

class Queue.LifoQueue(maxsize=0)

   Constructor for a LIFO queue.  *maxsize* is an integer that sets
   the upperbound limit on the number of items that can be placed in
   the queue.  Insertion will block once this size has been reached,
   until queue items are consumed.  If *maxsize* is less than or equal
   to zero, the queue size is infinite.

   バージョン 2.6 で追加.

class Queue.PriorityQueue(maxsize=0)

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

   最小の値を持つ要素が最初に検索されます (最小の値を持つ値は、
   "sorted(list(entries))[0]" によって返されるものです)。典型的な要素
   のパターンは、"(priority_number, data)" 形式のタプルです。

   バージョン 2.6 で追加.

exception Queue.Empty

   Exception raised when non-blocking "get()" (or "get_nowait()") is
   called on a "Queue" object which is empty.

exception Queue.Full

   Exception raised when non-blocking "put()" (or "put_nowait()") is
   called on a "Queue" object which is full.

参考: "collections.deque" is an alternative implementation of
  unbounded queues with fast atomic "append()" and "popleft()"
  operations that do not require locking.


キューオブジェクト
==================

Queue objects ("Queue", "LifoQueue", or "PriorityQueue") provide the
public methods described below.

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[, timeout]])

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

   バージョン 2.3 で追加: The *timeout* parameter.

Queue.put_nowait(item)

   "put(item, False)" と等価です。

Queue.get([block[, timeout]])

   キューからアイテムを取り除き、それを返します。 オプション引数
   *block* が真で *timeout* が "None" (デフォルト) の場合は、必要であ
   ればアイテムが取り出せるようになるまでブロックします。 もし
   *timeout* が正の数の場合は、最大で *timeout* 秒間ブロックし、その時
   間内でアイテムが取り出せるようにならなければ、例外 "Empty" を送出し
   ます。 そうでない場合 (*block* が偽) は、直ちにアイテムが取り出せる
   ならば、それを返します。 できないならば、例外 "Empty" を送出します
   (この場合 *timeout* は無視されます)。

   バージョン 2.3 で追加: The *timeout* parameter.

Queue.get_nowait()

   "get(False)" と等価です。

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

Queue.task_done()

   過去にキューに入れられたタスクが完了した事を示します。キューのコン
   シューマスレッドに利用されます。タスクの取り出しに使われた各
   "get()" の後に "task_done()" を呼び出すと、取り出したタスクに対する
   処理が完了した事をキューに教えます。

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

   キューにある要素より多く呼び出された場合 "ValueError" が発生します
   。

   バージョン 2.5 で追加.

Queue.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.daemon = True
        t.start()

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

   q.join()       # block until all tasks are done
