型パラメータ:: 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

メソッドのサマリー

すべてのメソッドインスタンス・メソッド抽象メソッド
修飾子と型	メソッド	説明
`boolean`	`add(E e)`	容量制限に違反することなく、指定された要素をこのキューにすぐに挿入できる場合はそうします。成功した場合は`true`を返し、その時点で使用可能な空き領域が存在しない場合は`IllegalStateException`をスローします。
`boolean`	`contains(Object o)`	指定された要素がキューに含まれている場合に`true`を返します。
`int`	`drainTo(Collection<? super E> c)`	このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。
`int`	`drainTo(Collection<? super E> c, int maxElements)`	指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。
`boolean`	`offer(E e)`	指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合は`true`を返し、使用可能な空き領域がその時点で存在しない場合は`false`を返します。
`boolean`	`offer(E e, long timeout, TimeUnit unit)`	指定された要素をこのキューに挿入します。必要に応じて、指定された時間まで空きが生じるのを待機します。
`E`	`poll(long timeout, TimeUnit unit)`	このキューの先頭を取得して削除します。必要に応じて、指定された待機時間まで要素が利用可能になるのを待機します。
`void`	`put(E e)`	指定された要素をこのキューに挿入します。必要に応じて、空きが生じるまで待機します。
`int`	`remainingCapacity()`	理想的な状態(メモリーやリソースの制限がない状態)で、このキューがブロックせずに受け入れることができる追加要素の数を返します。組込み制限が存在しない場合は`Integer.MAX_VALUE`を返します。
`boolean`	`remove(Object o)`	指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。
`E`	`take()`	このキューの先頭を取得して削除します。必要に応じて、要素が利用可能になるまで待機します。

インタフェース java.util.Collectionから継承されたメソッド
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray

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

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

- メソッドの詳細
  - add
```
boolean add(E e)
```
    容量制限に違反することなく、指定された要素をこのキューにすぐに挿入できる場合はそうします。成功した場合はtrueを返し、その時点で使用可能な空き領域が存在しない場合はIllegalStateExceptionをスローします。容量制限のあるキューを使用する場合は、一般にofferを使用することをお薦めします。
    
    定義:
    
    add、インタフェース: Collection<E>
    
    定義:
    
    add、インタフェース: Queue<E>
    
    パラメータ:
    
    e - 追加する要素
    
    戻り値:
    
    true (Collection.add(E)で指定されているとおり)
    
    例外:
    
    IllegalStateException - 容量制限のために、この時点で要素を追加できない場合
    
    ClassCastException - 指定された要素のクラスが原因で、このキューにその要素を追加できない場合
    
    NullPointerException - 指定された要素がnullである場合
    
    IllegalArgumentException - 指定された要素のあるプロパティが原因で、このキューに要素を追加できない場合
  - offer
```
boolean offer(E e)
```
    指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合はtrueを返し、使用可能な空き領域がその時点で存在しない場合はfalseを返します。容量制限のあるキューを使用する場合、通常は、要素の挿入に失敗した場合に例外をスローするだけのadd(E)よりもこのメソッドを使用することをお薦めします。
    
    定義:
    
    offer、インタフェース: Queue<E>
    
    パラメータ:
    
    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を返します。
    
    定義:
    
    remove、インタフェース: Collection<E>
    
    パラメータ:
    
    o - キューから削除される要素(その要素が存在する場合)
    
    戻り値:
    
    呼出しの結果としてこのキューが変更された場合はtrue
    
    例外:
    
    ClassCastException - 指定された要素のクラスがこのキューと互換性のないクラスである場合(オプション)
    
    NullPointerException - 指定された要素がnullの場合(オプション)
  - contains
```
boolean contains(Object o)
```
    指定された要素がキューに含まれている場合にtrueを返します。つまり、このキューにo.equals(e)となる要素eが1つ以上含まれている場合にだけtrueを返します。
    
    定義:
    
    contains、インタフェース: Collection<E>
    
    パラメータ:
    
    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 - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティが原因で指定されたコレクションに追加できない場合

インタフェースBlockingQueue<E>

メソッドのサマリー

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

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

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

メソッドの詳細

add

offer

put

offer

take

poll

remainingCapacity

remove

contains

drainTo

drainTo