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

형태 파라미터:

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

모든 슈퍼 인터페이스:

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

알려진 구현 클래스 목록:

ArrayBlockingQueue, DelayQueue, LinkedBlockingQueue, PriorityBlockingQueue, SynchronousQueue

public interface BlockingQueue<E>
extends Queue <E>

요소의 취득시에 큐가 빌 때까지 대기하거나 요소의 포함시에 큐내의 공간이 이용 가능하게 될 때까지 대기하는 조작을 추가 지원하는 Queue .

BlockingQueue는 null 요소를 받아들이지 않습니다. null add, put, 또는 offer가 시도되면, 구현에 의해 NullPointerException이 발생 됩니다. poll 조작이 실패한 것을 나타내는 표지값으로 null가 사용됩니다.

BlockingQueue는 용량이 제한되는 경우가 있습니다. 이것이 언젠가는 remainingCapacity를 초과하면, 블록없이 추가 요소를 put 할 수 없게 됩니다. 빌트인 용량 제한없이 BlockingQueue를 사용하면, Integer.MAX_VALUE 나머지의 용량이 항상 리포트됩니다.

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

BlockingQueue 구현은 thread 세이프입니다. 모든 큐잉 메서드는 내부 락 또는 다른 병렬적인 제어 형식을 사용해 효과를 불가분에 달성합니다. 그러나, 컬렉션 조작을 「일괄」하는 addAll, containsAll, retainAll 및 removeAll는 구현시에 다른 지정이되어 있지 않은 한, 불가분에 실행할 필요는 반드시 없습니다. 따라서, 예를 들어, 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();
   }
 }
 

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

도입된 버전 :

1.5

메서드 개요

boolean	add (E o) 이 큐로 지정된 요소를 추가합니다.
int	drainTo (Collection <? super E > c) 이용 가능한 모든 요소를 이 큐로부터 삭제해, 지정된 컬렉션에 추가합니다.
int	drainTo (Collection <? super E > c, int maxElements) 지정된 수이내의 이용 가능한 요소를 이 큐로부터 삭제해, 지정된 컬렉션에 추가합니다.
boolean	offer (E o) 가능한 경우, 지정된 요소를 이 큐에 삽입합니다.
boolean	offer (E o, long timeout, TimeUnit unit) 지정된 요소를 이 큐에 삽입합니다.
E	poll (long timeout, TimeUnit unit) 이 큐의 선두를 취득 및 삭제합니다.
void	put (E o) 지정된 요소를 이 큐에 추가합니다.
int	remainingCapacity () 이 큐가 이상적인 상태 (메모리나 자원의 제한이 존재하지 않는다)로 블로킹없이 받아들일 수 있는 요소의 수를 리턴합니다.
E	take () 이 큐의 선두를 취득 및 삭제합니다.

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

element, peek, poll, remove

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

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

메서드의 상세

offer

boolean offer(E  o)

가능한 경우, 지정된 요소를 이 큐에 삽입합니다. 용량 제한등의 삽입 제한을 부과하는 큐를 사용하는 경우, 예외를 Throw 하는 것만으로 요소의 삽입에 실패하는 Collection.add(E) 메서드보다 offer 메서드를 사용하는 것을 추천합니다.

정의:

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

파라미터:

o - 추가하는 요소

반환값:

요소를 이 큐에 추가 가능한 경우는 true, 그렇지 않은 경우는 false

예외:

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

offer

boolean offer(E  o,
              long timeout,
              TimeUnit  unit)
              throws InterruptedException 

지정된 요소를 이 큐에 삽입합니다. 필요하게 응해 공간이 이용 가능하게 되는 것을 지정된 시간까지 대기합니다.

파라미터:

o - 추가하는 요소

timeout - 처리를 중지할 때까지의 대기 시간. 단위는 unit

unit - timeout 파라미터의 해석 방법을 지정하는 TimeUnit

반환값:

성공했을 경우는 true, 공간이 이용 가능하게 되기 전으로 지정된 대기 시간이 경과했을 경우는 false

예외:

InterruptedException - 대기중에 인터럽트가 발생했을 경우

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

poll

E  poll(long timeout,
       TimeUnit  unit)
       throws InterruptedException 

이 큐의 선두를 취득 및 삭제합니다. 이 큐에 요소가 존재하지 않는 경우는 필요에 따라서 지정된 시간만 대기합니다.

파라미터:

timeout - 처리를 중지할 때까지의 대기 시간. 단위는 unit

unit - timeout 파라미터의 해석 방법을 지정하는 TimeUnit

반환값:

이 큐의 선두. 지정된 대기 시간이 경과해도 요소가 존재하지 않는 경우는 null

예외:

InterruptedException - 대기중에 인터럽트가 발생했을 경우

take

E  take()
       throws InterruptedException 

이 큐의 선두를 취득 및 삭제합니다. 이 큐에 요소가 존재하지 않는 경우는 대기합니다.

반환값:

큐의 선두

예외:

InterruptedException - 대기중에 인터럽트가 발생했을 경우

put

void put(E  o)
         throws InterruptedException 

지정된 요소를 이 큐에 추가합니다. 필요하게 응해 공간이 이용 가능하게 될 때까지 대기합니다.

파라미터:

o - 추가하는 요소

예외:

InterruptedException - 대기중에 인터럽트가 발생했을 경우

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

remainingCapacity

int remainingCapacity()

이 큐가 이상적인 상태 (메모리나 자원의 제한이 존재하지 않는다)로 블로킹없이 받아들일 수 있는 요소의 수를 리턴합니다. 빌트인 제한이 존재하지 않는 경우는 Integer.MAX_VALUE를 리턴합니다.

remainingCapacity를 확인하면, 요소의 add 조작이 언제나 성공하는 것은 아닌 것을 압니다. 이것은 다른 thread가 요소의 put 또는 take 조작을 실행하려고 하고 있는 경우가 있기 때문에입니다.

반환값:

나머지의 용량

add

boolean add(E  o)

이 큐로 지정된 요소를 추가합니다. 가능하면 즉석에서 실행됩니다. 성공했을 경우는 true, 그렇지 않은 경우는 IllegalStateException가 발생 됩니다.

정의:

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

파라미터:

o - 요소

반환값:

true (Collection.add 일반 규약에 따른다)

예외:

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

IllegalStateException - 요소를 추가할 수 없는 경우

drainTo

int drainTo(Collection <?  super E > c)

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

파라미터:

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

반환값:

전송 되는 요소의 수

예외:

NullPointerException - c가 null인 경우

IllegalArgumentException - c가 이 큐인 경우

drainTo

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

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

파라미터:

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

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

반환값:

전송 되는 요소의 수

예외:

NullPointerException - c가 null인 경우

IllegalArgumentException - c가 이 큐인 경우