- 型パラメータ:
E
- このキューに保持されている要素の型
- すべてのスーパー・インタフェース:
Collection<E>
,Iterable<E>
,Queue<E>
- 既知のすべてのサブインタフェース:
BlockingDeque<E>
,TransferQueue<E>
- 既知のすべての実装クラス:
ArrayBlockingQueue
,DelayQueue
,LinkedBlockingDeque
,LinkedBlockingQueue
,LinkedTransferQueue
,PriorityBlockingQueue
,SynchronousQueue
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
容量制限に違反することなく、指定された要素をこのキューにすぐに挿入できる場合はそうします。成功した場合はtrue
を返し、その時点で使用可能な空き領域が存在しない場合はIllegalStateException
をスローします。boolean
指定された要素がキューに含まれている場合にtrue
を返します。int
drainTo
(Collection<? super E> c) このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。int
drainTo
(Collection<? super E> c, int maxElements) 指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。boolean
指定された要素を、このキューに容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合はtrue
を返し、使用可能な空き領域がその時点で存在しない場合はfalse
を返します。boolean
指定された要素をこのキューに挿入します。必要に応じて、指定された時間まで空きが生じるのを待機します。このキューの先頭を取得して削除します。必要に応じて、指定された待機時間まで要素が利用可能になるのを待機します。void
指定された要素をこのキューに挿入します。必要に応じて、空きが生じるまで待機します。int
理想的な状態(メモリーやリソースの制限がない状態)で、このキューがブロックせずに受け入れることができる追加要素の数を返します。組込み制限が存在しない場合はInteger.MAX_VALUE
を返します。boolean
指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。take()
このキューの先頭を取得して削除します。必要に応じて、要素が利用可能になるまで待機します。インタフェース java.util.Collectionで宣言されたメソッド
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray, toArray
-
メソッドの詳細
-
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
このキューの先頭を取得して削除します。必要に応じて、指定された待機時間まで要素が利用可能になるのを待機します。- パラメータ:
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
- 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティが原因で指定されたコレクションに追加できない場合
-