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