モジュール java.base
パッケージ java.util.concurrent

インタフェースBlockingQueue<E>

型パラメータ:
E - このキューに保持されている要素の型
すべてのスーパー・インタフェース:
Collection<E>, Iterable<E>, Queue<E>
既知のすべてのサブインタフェース:
BlockingDeque<E>, TransferQueue<E>
既知のすべての実装クラス:
ArrayBlockingQueue, DelayQueue, LinkedBlockingDeque, LinkedBlockingQueue, LinkedTransferQueue, PriorityBlockingQueue, SynchronousQueue
public interface BlockingQueue<E> extends Queue<E>
要素の取得時にキューが空でなくなるまで待機したり、要素の格納時にキュー内に空きが生じるまで待機する操作を追加でサポートしたりするQueueです。

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

BlockingQueueのメソッドのサマリー
例外のスロー 特殊な値 ブロック タイム・アウト
挿入 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