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

型パラメータ:

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

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

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

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

ArrayBlockingQueue, DelayQueue, LinkedBlockingQueue, PriorityBlockingQueue, SynchronousQueue

public interface BlockingQueue<E>
extends Queue<E>

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

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

BlockingQueue は、容量が制限される場合があります。これがいずれかの時点で remainingCapacity を超過すると、ブロックなしで追加要素を put できなくなります。組み込み容量制限なしで BlockingQueue を使用すると、Integer.MAX_VALUE の残りの容量が常にレポートされます。

BlockingQuere の実装は、主にプロデューサとコンシューマの間のキューで使用するように設計されていますが、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();
   }
 }
 

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

導入されたバージョン:

1.5

メソッドの概要

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

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

element, peek, poll, remove

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

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

メソッドの詳細

offer

boolean offer(E o)

可能な場合、指定された要素をこのキューに挿入します。容量制限などの挿入制限を課すキューを使用する場合、例外をスローするだけで要素の挿入に失敗する Collection.add(E) メソッドよりも offer メソッドを使用することをお勧めします。

定義:

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

パラメータ:

o - 追加する要素

戻り値:

要素をこのキューに追加可能な場合は true、そうでない場合は false

例外:

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

offer

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

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

パラメータ:

o - 追加する要素

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

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

戻り値:

成功した場合は true、空間が利用可能になる前に指定された待機時間が経過した場合は false

例外:

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

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

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException

このキューの先頭を取得および削除します。このキューに要素が存在しない場合は、必要に応じて指定された時間だけ待機します。

パラメータ:

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

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

戻り値:

このキューの先頭。指定された待機時間が経過しても要素が存在しない場合は null

例外:

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

take

E take()
       throws InterruptedException

このキューの先頭を取得および削除します。このキューに要素が存在しない場合は待機します。

戻り値:

キューの先頭

例外:

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

put

void put(E o)
         throws InterruptedException

指定された要素をこのキューに追加します。必要に応じ、空間が利用可能になるまで待機します。

パラメータ:

o - 追加する要素

例外:

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

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

remainingCapacity

int remainingCapacity()

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

remainingCapacity を確認すると、要素の add 操作がいつも成功するわけではないことがわかります。これは、別のスレッドが要素の put または take 操作を実行しようとしている場合があるためです。

戻り値:

残りの容量

add

boolean add(E o)

このキューに指定された要素を追加します。可能であれば即座に実行されます。成功した場合は true、そうでない場合は IllegalStateException がスローされます。

定義:

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

パラメータ:

o - 要素

戻り値:

true (Collection.add の一般規約に従う)

例外:

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

IllegalStateException - 要素を追加できない場合

drainTo

int drainTo(Collection<? super E> c)

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

パラメータ:

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

戻り値:

転送される要素の数

例外:

NullPointerException - c が null の場合

IllegalArgumentException - c がこのキューである場合

drainTo

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

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

パラメータ:

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

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

戻り値:

転送される要素の数

例外:

NullPointerException - c が null の場合

IllegalArgumentException - c がこのキューである場合