lbmq

Interface Pollable<E>

All Known Implementing Classes:

AbstractPollable, LinkedBlockingMultiQueue

public interface Pollable<E>

This interface captures the "head side" of the BlockingQueue interface

Method Summary

Modifier and Type	Method and Description
int	drainTo(java.util.Collection<? super E> c) Removes all available elements from this queue and adds them to the given collection.
int	drainTo(java.util.Collection<? super E> c, int maxElements) Removes at most the given number of available elements from this queue and adds them to the given collection.
E	element() Retrieves, but does not remove, the head of this queue.
E	peek() Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
E	poll() Retrieves and removes the head of this queue, or returns null if this queue is empty.
E	poll(long timeout, java.util.concurrent.TimeUnit unit) Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.
E	remove() Retrieves and removes the head of this queue.
E	take() Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Method Detail

remove

E remove()

Retrieves and removes the head of this queue. This method differs from poll only in that it throws an exception if this queue is empty.

Returns:

the head of this queue

Throws:

java.util.NoSuchElementException - if this queue is empty

poll

E poll()

Retrieves and removes the head of this queue, or returns null if this queue is empty.

Returns:

the head of this queue, or null if this queue is empty

element

E element()

Retrieves, but does not remove, the head of this queue. This method differs from peek only in that it throws an exception if this queue is empty.

Returns:

the head of this queue

Throws:

java.util.NoSuchElementException - if this queue is empty

peek

E peek()

Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.

Returns:

the head of this queue, or null if this queue is empty

take

E take()
throws java.lang.InterruptedException

Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Returns:

the head of this queue

Throws:

java.lang.InterruptedException - if interrupted while waiting

poll

E poll(long timeout,
       java.util.concurrent.TimeUnit unit)
throws java.lang.InterruptedException

Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.

Parameters:

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the head of this queue, or null if the specified waiting time elapses before an element is available

Throws:

java.lang.InterruptedException - if interrupted while waiting

drainTo

int drainTo(java.util.Collection<? super E> c)

Removes all available elements from this queue and adds them to the given collection. This operation may be more efficient than repeatedly polling this queue. A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

c - the collection to transfer elements into

Returns:

the number of elements transferred

Throws:

java.lang.UnsupportedOperationException - if addition of elements is not supported by the specified collection

java.lang.ClassCastException - if the class of an element of this queue prevents it from being added to the specified collection

java.lang.NullPointerException - if the specified collection is null

java.lang.IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

drainTo

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

Removes at most the given number of available elements from this queue and adds them to the given collection. A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters:

c - the collection to transfer elements into

maxElements - the maximum number of elements to transfer

Returns:

the number of elements transferred

Throws:

java.lang.UnsupportedOperationException - if addition of elements is not supported by the specified collection

java.lang.ClassCastException - if the class of an element of this queue prevents it from being added to the specified collection

java.lang.NullPointerException - if the specified collection is null

java.lang.IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection