java.util.concurrent
インタフェース BlockingQueue<E>

型パラメータ:

E - コレクション内に存在する要素の型

すべてのスーパーインタフェース:

Collection<E>, Iterable<E>, Queue<E>

既知のサブインタフェースの一覧:

BlockingDeque<E>

既知の実装クラスの一覧:

ArrayBlockingQueue, DelayQueue, LinkedBlockingDeque, LinkedBlockingQueue, PriorityBlockingQueue, SynchronousQueue

public interface BlockingQueue<E>
extends Queue<E>

要素の取得時にキューが空でなくなるまで待機したり、要素の格納時にキュー内に空きが生じるまで待機する操作を追加でサポートする Queue です。

BlockingQueue メソッドには 4 つの形式があり、すぐには達成できなくても将来のある時点で達成できる可能性がある操作を異なる方法で処理します。1 つめは例外をスローし、2 つめは特殊な値 (操作に応じて null と false のいずれか) を返し、3 つめは操作が正常に完了するまで現在のスレッドを無期限にブロックし、4 つめは処理を中止するまで指定された制限時間内のみブロックします。これらのメソッドについて、次の表にまとめます。

	例外のスロー	特殊な値	ブロック	タイムアウト
挿入	add(e)	offer(e)	put(e)	offer(e, time, unit)
削除	remove()	poll()	take()	poll(time, unit)
検査	element()	peek()	適用外	適用外

BlockingQueue は null 要素を受け入れません。null の add、put、または offer が試みられると、実装により NullPointerException がスローされます。null は、poll オペレーションが失敗したことを示す標識値として使用されます。

BlockingQueue は、容量が制限される場合があります。その場合は remainingCapacity を持ち、これを超過すると、追加要素の put はブロックされます。組み込み容量制限なしで BlockingQueue を使用すると、Integer.MAX_VALUE の残りの容量が常に報告されます。

BlockingQueue の実装は、主にプロデューサとコンシューマの間のキューで使用するように設計されていますが、加えて Collection インタフェースもサポートします。したがって、たとえば remove(x) を使用してキューから任意の要素を削除することが可能です。ただし、このような操作は一般に実行の効率が悪いので、キュー内のメッセージの取り消しなど特定の用途がある場合にのみ実行されることを想定しています。

BlockingQueue 実装はスレッドセーフです。すべてのキューイングメソッドは、内部ロックまたは別の形式の並行処理制御を使用して効果を原子的に達成します。ただし、コレクションの一括オペレーションである addAll、containsAll、retainAll、および removeAll は、実装で特に指定されていないかぎり、必ずしも原始的には実行されません。したがって、たとえば、addAll(c) では c に要素の一部だけを追加したあとに、例外をスローして失敗する可能性があります。

BlockingQueue は、本来、項目がこれ以上追加されないことを示す「クローズ」または「シャットダウン」オペレーションを一切サポートしません。このような機能のニーズや使用は、実装に依存する傾向があります。たとえば、プロデューサで特殊な end-of-stream または poison オブジェクトを挿入し、コンシューマによる取得時にこれらが適宜解釈される、という方法が一般的です。

次に、プロデューサとコンシューマの通常のシナリオに基づく使用例を示します。BlockingQueue は複数のプロデューサおよび複数のコンシューマで安全に使用できます。

 class Producer implements Runnable {
   private final BlockingQueue queue;
   Producer(BlockingQueue q) { queue = q; }
   public void run() {
     try {
       while (true) { queue.put(produce()); }
     } catch (InterruptedException ex) { ... handle ...}
   }
   Object produce() { ... }
 }

 class Consumer implements Runnable {
   private final BlockingQueue queue;
   Consumer(BlockingQueue q) { queue = q; }
   public void run() {
     try {
       while (true) { consume(queue.take()); }
     } catch (InterruptedException ex) { ... handle ...}
   }
   void consume(Object x) { ... }
 }

 class Setup {
   void main() {
     BlockingQueue q = new SomeQueueImplementation();
     Producer p = new Producer(q);
     Consumer c1 = new Consumer(q);
     Consumer c2 = new Consumer(q);
     new Thread(p).start();
     new Thread(c1).start();
     new Thread(c2).start();
   }
 }
 

メモリー整合性効果:ほかの並行処理コレクションと同様、オブジェクトを BlockingQueue に配置する前のスレッド内のアクションは、別のスレッドでのその要素へのアクセスまたは BlockingQueue からの削除に続くアクションよりも「前に発生」します。

このインタフェースは、Java Collections Framework のメンバーです。

導入されたバージョン:

1.5

メソッドの概要

boolean	add(E e) 指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。
boolean	contains(Object o) 指定された要素がキューに含まれている場合に true を返します。
int	drainTo(Collection<? super E> c) このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。
int	drainTo(Collection<? super E> c, int maxElements) 指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。
boolean	offer(E e) 指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。
boolean	offer(E e, long timeout, TimeUnit unit) 指定された要素をこのキューに挿入します。
E	poll(long timeout, TimeUnit unit) このキューの先頭を取得して削除します。
void	put(E e) 指定された要素をこのキューに挿入します。
int	remainingCapacity() 理想的な状態 (メモリーやリソースの制限がない状態) で、このキューがブロックせずに受け入れることができる追加要素の数を返します。
boolean	remove(Object o) 指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。
E	take() このキューの先頭を取得して削除します。

インタフェース java.util.Queue から継承されたメソッド

element, peek, poll, remove

インタフェース java.util.Collection から継承されたメソッド

addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, removeAll, retainAll, size, toArray, toArray

メソッドの詳細

add

boolean add(E e)

指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合は true を返し、使用可能な空き領域がその時点で存在しない場合は IllegalStateException をスローします。容量制限のあるキューを使用する場合、通常は offer を使用することをお勧めします。

定義:

インタフェース Collection<E> 内の add

定義:

インタフェース Queue<E> 内の add

パラメータ:

e - 追加する要素

戻り値:

true (Collection.add(E) で指定されているとおり)

例外:

IllegalStateException - 容量制限のために要素をその時点で追加できない場合

ClassCastException - 指定された要素のクラスが原因で、キューに要素を追加できない場合

NullPointerException - 指定された要素が null である場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このキューに要素を追加できない場合

offer

boolean offer(E e)

指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合は true を返し、使用可能な空き領域がその時点で存在しない場合は false を返します。容量の制限されたキューを使用する場合には基本的に、要素の挿入失敗時に例外をスローするだけの add(E) よりも、このメソッドのほうを使用するようにしてください。

定義:

インタフェース Queue<E> 内の offer

パラメータ:

e - 追加する要素

戻り値:

このキューに要素が追加された場合は true、それ以外の場合は false

例外:

ClassCastException - 指定された要素のクラスが原因で、キューに要素を追加できない場合

NullPointerException - 指定された要素が null である場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このキューに要素を追加できない場合

put

void put(E e)
         throws InterruptedException

指定された要素をこのキューに挿入します。必要に応じて、空きが生じるまで待機します。

パラメータ:

e - 追加する要素

例外:

InterruptedException - 待機中に割り込みが発生した場合

ClassCastException - 指定された要素のクラスが原因で、キューに要素を追加できない場合

NullPointerException - 指定された要素が null である場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このキューに要素を追加できない場合

offer

boolean offer(E e,
              long timeout,
              TimeUnit unit)
              throws InterruptedException

指定された要素をこのキューに挿入します。必要に応じて、指定された時間まで空きが生じるのを待機します。

パラメータ:

e - 追加する要素

timeout - 処理を中止するまでの待機時間。単位は unit

unit - timeout パラメータの解釈方法を決定する TimeUnit

戻り値:

成功した場合は true、空きが生じる前に指定された待機時間が経過した場合は false

例外:

InterruptedException - 待機中に割り込みが発生した場合

ClassCastException - 指定された要素のクラスが原因で、キューに要素を追加できない場合

NullPointerException - 指定された要素が null である場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このキューに要素を追加できない場合

take

E take()
       throws InterruptedException

このキューの先頭を取得して削除します。必要に応じて、要素が利用可能になるまで待機します。

戻り値:

キューの先頭

例外:

InterruptedException - 待機中に割り込みが発生した場合

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException

このキューの先頭を取得して削除します。必要に応じて、指定された待機時間まで要素が利用可能になるのを待機します。

パラメータ:

timeout - 処理を中止するまでの待機時間。単位は unit

unit - timeout パラメータの解釈方法を決定する TimeUnit

戻り値:

このキューの先頭。空きが生じる前に指定された待機時間が経過した場合は null

例外:

InterruptedException - 待機中に割り込みが発生した場合

remainingCapacity

int remainingCapacity()

理想的な状態 (メモリーやリソースの制限がない状態) で、このキューがブロックせずに受け入れることができる追加要素の数を返します。組み込み制限が存在しない場合は Integer.MAX_VALUE を返します。

remainingCapacity を調べても要素の挿入試行が成功するかどうかがわかるとはかぎりません。これは別のスレッドが要素を挿入または削除しようとしている可能性があるためです。

戻り値:

残りの容量

remove

boolean remove(Object o)

指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。つまり、キュー内に、o.equals(e) に該当する要素 e が 1 つ以上含まれている場合は、そのような要素を削除します。指定された要素がこのキューに含まれていた場合、つまり、呼び出しの結果としてこのキューが変更された場合に true を返します。

定義:

インタフェース Collection<E> 内の remove

パラメータ:

o - キューから削除される要素 (その要素が存在する場合)

戻り値:

この呼び出しの結果、このキューが変更された場合は true

例外:

ClassCastException - 指定された要素のクラスがこのキューと互換性のないクラスである場合 (省略可能)

NullPointerException - 指定された要素が null である場合 (省略可能)

contains

boolean contains(Object o)

指定された要素がキューに含まれている場合に true を返します。つまり、キューに、o.equals(e) となる要素 e が 1 つ以上含まれている場合にだけ true を返します。

定義:

インタフェース Collection<E> 内の contains

パラメータ:

o - このキューに含まれているかどうかを調べるオブジェクト

戻り値:

指定された要素がこのキューに含まれている場合は true

例外:

ClassCastException - 指定された要素のクラスがこのキューと互換性のないクラスである場合 (省略可能)

NullPointerException - 指定された要素が null である場合 (省略可能)

drainTo

int drainTo(Collection<? super E> c)

このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。このオペレーションは、このキューを繰り返しポーリングする場合よりも効率的な場合があります。コレクション c に要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentException がスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。

パラメータ:

c - 要素の転送先のコレクション

戻り値:

転送された要素の数

例外:

UnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合

ClassCastException - このキューの要素のクラスが原因で、その要素を指定されたコレクションに追加できない場合

NullPointerException - 指定されたコレクションが null である場合

IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティーが原因で指定されたコレクションに追加できない場合

drainTo

int drainTo(Collection<? super E> c,
            int maxElements)

指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。コレクション c に要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentException がスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。

パラメータ:

c - 要素の転送先のコレクション

maxElements - 転送する要素の最大数

戻り値:

転送された要素の数

例外:

UnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合

ClassCastException - このキューの要素のクラスが原因で、その要素を指定されたコレクションに追加できない場合

NullPointerException - 指定されたコレクションが null である場合

IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティーが原因で指定されたコレクションに追加できない場合