java.util.concurrent
인터페이스 BlockingQueue<E>

형태 파라미터:

E - 컬렉션내에 존재하는 요소의 형태

모든 슈퍼 인터페이스:

Collection <E>, Iterable <E>, Queue <E>

기존의 서브 인터페이스의 일람:

BlockingDeque <E>

기존의 구현 클래스의 일람:

ArrayBlockingQueue , DelayQueue , LinkedBlockingDeque , LinkedBlockingQueue , PriorityBlockingQueue , SynchronousQueue

public interface BlockingQueue<E>
extends Queue <E>

요소의 취득시에 큐가 빈 상태(empty)이 아니게 될 때까지 대기하거나 요소의 포함시에 큐내에 빈 곳이 생길 때까지 대기하는 조작을 추가로 지원하는 Queue 입니다.

BlockingQueue 메소드에는 4 개의 형식이 있어, 곧바로는 달성할 수 없어도 장래가 있는 시점에서 달성할 수 있을 가능성이 있는 조작을 다른 방법으로 처리합니다. 1 개째는 예외를 throw 해, 2 개째는 특수한 값 (조작에 응해 null 와 false 의 어느쪽이든)을 돌려주어, 3 개째는 조작이 정상적으로 완료할 때까지 현재의 thread를 무기한으로 블록 해, 4 개째는 처리를 중지할 때까지 지정된 제한 시간내만 블록 합니다. 이러한 메소드에 대해, 다음의 표에 정리합니다.

	예외의 throw	특수한 값	블록	타임 아웃
삽입	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 가 throw 됩니다. null 는,poll 오퍼레이션이 실패한 것을 나타내는 표지치로서 사용됩니다.

BlockingQueue 는, 용량이 제한되는 경우가 있습니다. 그 경우는 remainingCapacity 를 가져, 이것을 초과하면(자), 추가 요소의 put 는 블록 됩니다. 편입 용량 제한없이 BlockingQueue 를 사용하면(자),Integer.MAX_VALUE 의 나머지의 용량이 항상 보고됩니다.

BlockingQueue 의 구현은, 주로 프로듀서와 컨슈머(consumer)의 사이의 큐로 사용하도록(듯이) 설계되고 있습니다만, 더해 Collection 인터페이스도 지원합니다. 따라서, 예를 들어 remove(x) 를 사용해 큐로부터 임의의 요소를 삭제하는 것이 가능합니다. 다만, 이러한 조작은 일반적으로 실행의 효율이 나쁘기 때문에, 큐내의 메세지의 취소 등 특정의 용도가 있는 경우에게만 실행되는 것을 상정하고 있습니다.

BlockingQueue 구현은 thread 세이프입니다. 모든 큐잉 메소드는, 내부 락 또는 다른 형식의 동시성 처리 제어를 사용해 효과를 원자적으로 달성합니다. 다만, 컬렉션의 일괄 오퍼레이션인 addAll,containsAll,retainAll, 및 removeAll 는, 구현으로 특히 지정되어 있지 않은 한, 반드시 프리미티브(primitive)으로는 실행되지 않습니다. 따라서, 예를 들어,addAll(c) 에서는 c 에 요소의 일부만을 추가한 뒤에, 예외를 throw 해 실패할 가능성이 있습니다.

BlockingQueue 는, 본래, 항목이 더 이상 추가되지 않는 것을 나타내는 「클로즈」또는 「종료」오퍼레이션을 일절 지원하지 않습니다. 이러한 기능의 요구나 사용은, 구현에 의존하는 경향이 있습니다. 예를 들어, 프로듀서로 특수한 end-of-stream 또는 poison 객체를 삽입해, 컨슈머(consumer)에 의한 취득시에 이것들이 적당 해석된다, 라고 할 방법이 일반적입니다.

다음에, 프로듀서와 컨슈머(consumer)의 일반적으로의 시나리오에 근거하는 사용예를 나타냅니다. BlockingQueue 은 복수의 프로듀서 및 복수의 컨슈머(consumer)로 안전하게 사용할 수 있습니다.

 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 에 배치하기 전의 thread내의 액션은, 다른 thread에서의 그 요소에의 액세스 또는 BlockingQueue 로부터의 삭제에 계속되는 액션보다「전에 발생」 합니다.

이 인터페이스는,Java Collections Framework 의 멤버입니다.

도입된 버젼:

1.5

메소드의 개요

boolean	add (E e) 지정된 요소를, 이 큐에 용량 제한으로 위반하는 것 없이 곧바로 삽입할 수 있는 경우에는, 그렇게 하겠습니다.
boolean	contains (Object o) 지정된 요소가 큐에 포함되어 있는 경우에 true 를 돌려줍니다.
int	drainTo (Collection <? super E > c) 이 큐로부터 이용 가능한 모든 요소를 삭제해, 그것들이 지정된 컬렉션에 추가합니다.
int	drainTo (Collection <? super E > c, int maxElements) 지정된 수이내의 이용 가능한 요소를 이 큐로부터 삭제해, 지정된 컬렉션에 추가합니다.
boolean	offer (E e) 지정된 요소를, 이 큐에 용량 제한으로 위반하는 것 없이 곧바로 삽입할 수 있는 경우에는, 그렇게 하겠습니다.
boolean	offer (E e, long timeout, TimeUnit unit) 지정된 요소를 이 큐에 삽입합니다.
E	poll (long timeout, TimeUnit unit) 이 큐의 선두를 취득해 삭제합니다.
void	put (E e) 지정된 요소를 이 큐에 삽입합니다.
int	remainingCapacity () 이상적인 상태 (메모리나 자원의 제한이 없는 상태)로, 이 큐가 블록 하지 않고 받아들일 수가 있는 추가 요소의 수를 돌려줍니다.
boolean	remove (Object o) 지정된 요소의 단일의 인스턴스가 이 큐에 존재하는 경우는, 큐로부터 삭제합니다.
E	take () 이 큐의 선두를 취득해 삭제합니다.

인터페이스 java.util. Queue 로부터 상속된 메소드

element , peek , poll , remove

인터페이스 java.util. Collection 로부터 상속된 메소드

addAll , clear , containsAll , equals , hashCode , isEmpty , iterator , removeAll , retainAll , size , toArray , toArray

메소드의 상세

add

boolean add(E  e)

지정된 요소를, 이 큐에 용량 제한으로 위반하는 것 없이 곧바로 삽입할 수 있는 경우에는, 그렇게 하겠습니다. 성공했을 경우는 true 를 돌려주어, 사용 가능한 빈영역이 그 시점에서 존재하지 않는 경우는 IllegalStateException 를 throw 합니다. 용량 제한이 있는 큐를 사용하는 경우, 일반적으로은 offer 를 사용하는 것을 추천합니다.

정의:

인터페이스 Collection <E > 내의 add

정의:

인터페이스 Queue <E > 내의 add

파라미터:

e - 추가하는 요소

반환값:

true (Collection.add(E) 로 지정되고 있는 대로)

예외:

IllegalStateException - 용량 제한이 원인으로 이 시점에서 요소를 추가할 수 없는 경우

ClassCastException - 지정된 요소의 클래스가 원인으로, 이 큐에 요소를 추가할 수 없는 경우

NullPointerException - 지정된 요소가 null 인 경우

IllegalArgumentException - 지정된 요소가 있는 프로퍼티이 원인으로, 이 큐에 요소를 추가할 수 없는 경우

offer

boolean offer(E  e)

지정된 요소를, 이 큐에 용량 제한으로 위반하는 것 없이 곧바로 삽입할 수 있는 경우에는, 그렇게 하겠습니다. 성공했을 경우는 true 를 돌려주어, 사용 가능한 빈영역이 그 시점에서 존재하지 않는 경우는 false 를 돌려줍니다. 용량 제한이 있는 큐를 사용하는 경우, 일반적으로은, 요소의 삽입에 실패했을 경우에 예외를 throw 할 뿐(만큼)의 add(E) 보다 이 메소드를 사용하는 것을 추천합니다.

정의:

인터페이스 Queue <E > 내의 offer

파라미터:

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 를 조사해도 요소의 삽입 시행이 성공할지 어떨지를 안다고는인가 선. 이것은 다른 thread가 요소를 삽입 또는 삭제하려고 하고 있을 가능성이 있기 (위해)때문에입니다.

반환값:

나머지의 용량

remove

boolean remove(Object  o)

지정된 요소의 단일의 인스턴스가 이 큐에 존재하는 경우는, 큐로부터 삭제합니다. 즉, 큐내에,o.equals(e) 에 해당하는 요소 e 가 1 개 이상 포함되어 있는 경우는, 그러한 요소를 삭제합니다. 지정된 요소가 이 큐에 포함되어 있었을 경우, 즉, 호출의 결과로서 이 큐가 변경되었을 경우에 true 를 돌려줍니다.

정의:

인터페이스 Collection <E > 내의 remove

파라미터:

o - 이 큐로부터 삭제되는 요소 (그 요소가 존재하는 경우)

반환값:

이 호출의 결과, 이 큐가 변경되었을 경우는 true

예외:

ClassCastException - 지정된 요소의 클래스가 이 큐와 호환성이 없는 클래스인 경우 (생략 가능)

NullPointerException - 지정된 요소가 null 인 경우 (생략 가능)

contains

boolean contains(Object  o)

지정된 요소가 큐에 포함되어 있는 경우에 true 를 돌려줍니다. 즉, 큐에,o.equals(e) 가 되는 요소 e 가 1 개 이상 포함되어 있는 경우에만 true 를 돌려줍니다.

정의:

인터페이스 Collection <E > 내의 contains

파라미터:

o - 이 큐에 포함되어 있는지 어떤지를 조사하는 객체

반환값:

지정된 요소가 이 큐에 포함되어 있는 경우는 true

예외:

ClassCastException - 지정된 요소의 클래스가 이 큐와 호환성이 없는 클래스인 경우 (생략 가능)

NullPointerException - 지정된 요소가 null 인 경우 (생략 가능)

drainTo

int drainTo(Collection <?  super E > c)

이 큐로부터 이용 가능한 모든 요소를 삭제해, 그것들이 지정된 컬렉션에 추가합니다. 이 오퍼레이션은, 이 큐를 반복해 폴링 하는 경우보다 효율적인 경우가 있습니다. 컬렉션 c 에 요소를 추가하려고 했을 때에 장해가 발생하면(자), 관련하는 예외의 throw시에, 요소가 이 큐와 컬렉션의 어느 것에도 존재하지 않는 경우와 한편 또는 양쪽 모두에 존재하는 경우가 있습니다. 큐를 그 자체에 배출하려고 하면(자),IllegalArgumentException 가 throw 됩니다. 또, 오퍼레이션의 진행중으로 지정된 컬렉션이 변경되었을 경우의, 이 오퍼레이션의 동작은 정의되고 있지 않습니다.

파라미터:

c - 요소의 전송처의 컬렉션

반환값:

전송 된 요소의 수

예외:

UnsupportedOperationException - 지정된 컬렉션으로 추가의 요소가 지원되어 있지 않은 경우

ClassCastException - 이 큐의 요소의 클래스가 원인으로, 그 요소가 지정된 컬렉션에 추가할 수 없는 경우

NullPointerException - 지정된 컬렉션이 null 인 경우

IllegalArgumentException - 지정된 컬렉션이 이 큐인 경우, 또는 이 큐의 요소가 있는 프로퍼티이 원인으로 지정된 컬렉션에 추가할 수 없는 경우

drainTo

int drainTo(Collection <?  super E > c,
            int maxElements)

지정된 수이내의 이용 가능한 요소를 이 큐로부터 삭제해, 지정된 컬렉션에 추가합니다. 컬렉션 c 에 요소를 추가하려고 했을 때에 장해가 발생하면(자), 관련하는 예외의 throw시에, 요소가 이 큐와 컬렉션의 어느 것에도 존재하지 않는 경우와 한편 또는 양쪽 모두에 존재하는 경우가 있습니다. 큐를 그 자체에 배출하려고 하면(자),IllegalArgumentException 가 throw 됩니다. 또, 오퍼레이션의 진행중으로 지정된 컬렉션이 변경되었을 경우의, 이 오퍼레이션의 동작은 정의되고 있지 않습니다.

파라미터:

c - 요소의 전송처의 컬렉션

maxElements - 전송 하는 요소의 최대수

반환값:

전송 된 요소의 수

예외:

UnsupportedOperationException - 지정된 컬렉션으로 추가의 요소가 지원되어 있지 않은 경우

ClassCastException - 이 큐의 요소의 클래스가 원인으로, 그 요소가 지정된 컬렉션에 추가할 수 없는 경우

NullPointerException - 지정된 컬렉션이 null 인 경우

IllegalArgumentException - 지정된 컬렉션이 이 큐인 경우, 또는 이 큐의 요소가 있는 프로퍼티이 원인으로 지정된 컬렉션에 추가할 수 없는 경우