E - このコレクション内に保持される要素の型public interface BlockingQueue<E> extends Queue<E>
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のメンバーです。
| 修飾子と型 | メソッドと説明 |
|---|---|
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()
このキューの先頭を取得して削除します。必要に応じて、要素が利用可能になるまで待機します。
|
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArrayboolean add(E e)
trueを返し、その時点で使用可能な空き領域が存在しない場合はIllegalStateExceptionをスローします。容量制限のあるキューを使用する場合は、一般にofferを使用することをお薦めします。add、インタフェース: Collection<E>add、インタフェース: Queue<E>e - 追加する要素true (Collection.add(E)で指定されているとおり)IllegalStateException - 容量制限のために、この時点で要素を追加できない場合ClassCastException - 指定された要素のクラスが原因で、このキューにその要素を追加できない場合NullPointerException - 指定された要素がnullである場合IllegalArgumentException - 指定された要素のあるプロパティが原因で、このキューに要素を追加できない場合boolean offer(E e)
trueを返し、使用可能な空き領域がその時点で存在しない場合はfalseを返します。容量制限のあるキューを使用する場合、通常は、要素の挿入に失敗した場合に例外をスローするだけのadd(E)よりもこのメソッドを使用することをお薦めします。offer、インタフェース: Queue<E>e - 追加する要素true、それ以外の場合はfalseClassCastException - 指定された要素のクラスが原因で、このキューにその要素を追加できない場合NullPointerException - 指定された要素がnullである場合IllegalArgumentException - 指定された要素のあるプロパティが原因で、このキューに要素を追加できない場合void put(E e) throws InterruptedException
e - 追加する要素InterruptedException - 待機中に割込みが発生した場合ClassCastException - 指定された要素のクラスが原因で、このキューにその要素を追加できない場合NullPointerException - 指定された要素がnullである場合IllegalArgumentException - 指定された要素のあるプロパティが原因で、このキューに要素を追加できない場合boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
e - 追加する要素timeout - 処理を中止するまでの待機時間。単位はunitunit - timeoutパラメータの解釈方法を決定するTimeUnittrue、空きが生じる前に指定された待機時間が経過した場合はfalseInterruptedException - 待機中に割込みが発生した場合ClassCastException - 指定された要素のクラスが原因で、このキューにその要素を追加できない場合NullPointerException - 指定された要素がnullである場合IllegalArgumentException - 指定された要素のあるプロパティが原因で、このキューに要素を追加できない場合E take() throws InterruptedException
InterruptedException - 待機中に割込みが発生した場合E poll(long timeout, TimeUnit unit) throws InterruptedException
timeout - 処理を中止するまでの待機時間。単位はunitunit - timeoutパラメータの解釈方法を決定するTimeUnitnullInterruptedException - 待機中に割込みが発生した場合int remainingCapacity()
Integer.MAX_VALUEを返します。
remainingCapacityを調べても要素の挿入試行が成功するかどうかがわかるとはかぎりません。これは別のスレッドが要素を挿入または削除しようとしている可能性があるためです。
boolean remove(Object o)
o.equals(e)となる要素eが1つ以上含まれている場合は、そのような要素を削除します。指定された要素がこのキューに含まれていた場合、つまり、呼出しの結果としてこのキューが変更された場合にtrueを返します。remove、インタフェース: Collection<E>o - キューから削除される要素(その要素が存在する場合)trueClassCastException - 指定された要素のクラスがこのキューと互換性のないクラスである場合(オプション)NullPointerException - 指定された要素がnullの場合(オプション)boolean contains(Object o)
trueを返します。つまり、このキューにo.equals(e)となる要素eが1つ以上含まれている場合にだけtrueを返します。contains、インタフェース: Collection<E>o - このキューに含まれているかどうかを調べるオブジェクトtrueClassCastException - 指定された要素のクラスがこのキューと互換性のないクラスである場合(オプション)NullPointerException - 指定された要素がnullの場合(オプション)int drainTo(Collection<? super E> c)
cに要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentExceptionがスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。c - 要素の転送先のコレクションUnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合ClassCastException - このキューの要素のクラスが原因で、その要素を指定されたコレクションに追加できない場合NullPointerException - 指定されたコレクションがnullである場合IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティが原因で指定されたコレクションに追加できない場合int drainTo(Collection<? super E> c, int maxElements)
cに要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentExceptionがスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。c - 要素の転送先のコレクションmaxElements - 転送する要素の最大数UnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合ClassCastException - このキューの要素のクラスが原因で、その要素を指定されたコレクションに追加できない場合NullPointerException - 指定されたコレクションがnullである場合IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティが原因で指定されたコレクションに追加できない場合 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.