Top Description Inners Fields Constructors Methods
java.util.concurrent

public Class DelayQueue<E extends Delayed>

extends AbstractQueue<E extends Delayed>
implements BlockingQueue<E extends Delayed>
Class Inheritance
All Implemented Interfaces
java.util.concurrent.BlockingQueue, java.util.Queue, java.util.Collection, java.lang.Iterable
Type Parameters
<E>
the type of elements held in this queue
Static Imports
java.util.concurrent.TimeUnit.NANOSECONDS

An unbounded blocking queue of Delayed elements, in which an element generally becomes eligible for removal when its delay has expired.

An element is considered expired when its getDelay(TimeUnit.NANOSECONDS) method would return a value less than or equal to zero.

An element is considered the head of the queue if it is the element with the earliest expiration time, whether in the past or the future, if there is such an element.

An element is considered the expired head of the queue if it is the expired element with the earliest expiration time in the past, if there is such an element. The expired head, when present, is also the head.

While this class implements the BlockingQueue interface, it intentionally violates the general contract of BlockingQueue, in that the following methods disregard the presence of unexpired elements and only ever remove the expired head:

All other methods operate on both expired and unexpired elements. For example, the size() method returns the count of all elements. Method peek() may return the (non-null) head even when take() would block waiting for that element to expire.

This queue does not permit null elements.

This class and its iterator implement all of the optional methods of the Collection and Iterator interfaces. The Iterator provided in method iterator() is not guaranteed to traverse the elements of the DelayQueue in any particular order.

This class is a member of the Java Collections Framework.

Author
Doug Lea
Since
1.5

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
DelayQueue.Itr

Snapshot iterator that works off copy of underlying q array.

Field Summary

Modifier and TypeField and Description
private final Condition
available

Condition signalled when a newer element becomes available at the head of the queue or a new thread may need to become leader.

private Thread
leader

Thread designated to wait for the element at the head of the queue.

private final transient ReentrantLock
private final PriorityQueue<E>
q

Constructor Summary

AccessConstructor and Description
public
DelayQueue()

Creates a new DelayQueue that is initially empty.

public
DelayQueue(Collection<? extends E>
the collection of elements to initially contain
c
)

Creates a DelayQueue initially containing the elements of the given collection of Delayed instances.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true (as specified by Collection#add)
add
(E
the element to add
e
)

Overrides java.util.AbstractQueue.add.

Implements java.util.concurrent.BlockingQueue.add, java.util.Queue.add, java.util.Collection.add.

Inserts the specified element into this delay queue.

public void
clear()

Overrides java.util.AbstractQueue.clear.

Implements java.util.Collection.clear.

Atomically removes all of the elements from this delay queue.

public int
drainTo(Collection<? super E>
the collection to transfer elements into
c
)

Implements java.util.concurrent.BlockingQueue.drainTo.

Removes all available elements from this queue and adds them to the given collection.

public int
drainTo(Collection<? super E>
the collection to transfer elements into
c
,
int
the maximum number of elements to transfer
maxElements
)

Implements java.util.concurrent.BlockingQueue.drainTo.

Removes at most the given number of available elements from this queue and adds them to the given collection.

public Iterator<E>

Returns:

an iterator over the elements in this queue
iterator
()

Implements abstract java.util.AbstractCollection.iterator.

Implements java.util.Collection.iterator.

Returns an iterator over all the elements (both expired and unexpired) in this queue.

public boolean

Returns:

true
offer
(E
the element to add
e
)

Implements java.util.concurrent.BlockingQueue.offer, java.util.Queue.offer.

Inserts the specified element into this delay queue.

public boolean

Returns:

true
offer
(E
the element to add
e
,
long
This parameter is ignored as the method never blocks
timeout
,
TimeUnit
This parameter is ignored as the method never blocks
unit
)

Implements java.util.concurrent.BlockingQueue.offer.

Inserts the specified element into this delay queue.

public E

Returns:

the head of this queue, or null if this queue is empty
peek
()

Implements java.util.Queue.peek.

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

public E

Returns:

the expired head of this queue, or null if this queue has no elements with an expired delay
poll
()

Implements java.util.Queue.poll.

Retrieves and removes the expired head of this queue, or returns null if this queue has no expired elements.

public E

Returns:

the expired head of this queue, or null if the specified waiting time elapses before an element with an expired delay becomes available
poll
(long
how long to wait before giving up, in units of unit
timeout
,
TimeUnit
a TimeUnit determining how to interpret the timeout parameter
unit
)

Implements java.util.concurrent.BlockingQueue.poll.

Retrieves and removes the expired head of this queue, waiting if necessary until an expired element is available on this queue, or the specified wait time expires.

public void
put(E
the element to add
e
)

Implements java.util.concurrent.BlockingQueue.put.

Inserts the specified element into this delay queue.

public int

Returns:

Integer.MAX_VALUE
remainingCapacity
()

Implements java.util.concurrent.BlockingQueue.remainingCapacity.

Always returns Integer.MAX_VALUE because a DelayQueue is not capacity constrained.

public E

Returns:

the expired head of this queue
remove
()

Overrides java.util.AbstractQueue.remove.

Implements java.util.Queue.remove.

Retrieves and removes the expired head of this queue, or throws an exception if this queue has no expired elements.

public boolean
remove(Object
element to be removed from this queue, if present
o
)

Overrides java.util.AbstractCollection.remove.

Implements java.util.concurrent.BlockingQueue.remove, java.util.Collection.remove.

Removes a single instance of the specified element from this queue, if it is present, whether or not it has expired.

pack-priv void
removeEQ(Object o)

Identity-based version for use in Itr.remove.

public int
size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.Collection.size.

Returns the number of elements in this collection.

public E

Returns:

the expired head of this queue
take
()

Implements java.util.concurrent.BlockingQueue.take.

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

public Object[]

Returns:

an array containing all of the elements in this queue
toArray
()

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Returns an array containing all of the elements in this queue.

public <T> T[]

Returns:

an array containing all of the elements in this queue
toArray
(T[]
the array into which the elements of the queue are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose
a
)

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Returns an array containing all of the elements in this queue; the runtime type of the returned array is that of the specified array.

Inherited from java.util.AbstractQueue:
addAllelement

Field Detail

availableback to summary
private final Condition available

Condition signalled when a newer element becomes available at the head of the queue or a new thread may need to become leader.

leaderback to summary
private Thread leader

Thread designated to wait for the element at the head of the queue. This variant of the Leader-Follower pattern (http://www.cs.wustl.edu/~schmidt/POSA/POSA2/) serves to minimize unnecessary timed waiting. When a thread becomes the leader, it waits only for the next delay to elapse, but other threads await indefinitely. The leader thread must signal some other thread before returning from take() or poll(...), unless some other thread becomes leader in the interim. Whenever the head of the queue is replaced with an element with an earlier expiration time, the leader field is invalidated by being reset to null, and some waiting thread, but not necessarily the current leader, is signalled. So waiting threads must be prepared to acquire and lose leadership while waiting.

lockback to summary
private final transient ReentrantLock lock
qback to summary
private final PriorityQueue<E> q

Constructor Detail

DelayQueueback to summary
public DelayQueue()

Creates a new DelayQueue that is initially empty.

DelayQueueback to summary
public DelayQueue(Collection<? extends E> c)

Creates a DelayQueue initially containing the elements of the given collection of Delayed instances.

Parameters
c:Collection<? extends E>

the collection of elements to initially contain

Annotations
@SuppressWarnings:this-escape
Exceptions
NullPointerException:
if the specified collection or any of its elements are null

Method Detail

addback to summary
public boolean add(E e)

Overrides java.util.AbstractQueue.add.

Implements java.util.concurrent.BlockingQueue.add, java.util.Queue.add, java.util.Collection.add.

Inserts the specified element into this delay queue.

Parameters
e:E

the element to add

Returns:boolean

true (as specified by Collection#add)

Exceptions
NullPointerException:
if the specified element is null
clearback to summary
public void clear()

Overrides java.util.AbstractQueue.clear.

Implements java.util.Collection.clear.

Atomically removes all of the elements from this delay queue. The queue will be empty after this call returns. Elements with an unexpired delay are not waited for; they are simply discarded from the queue.

drainToback to summary
public int drainTo(Collection<? super E> c)

Implements java.util.concurrent.BlockingQueue.drainTo.

Doc from java.util.concurrent.BlockingQueue.drainTo.

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:Collection<? super E>

the collection to transfer elements into

Returns:int

the number of elements transferred

Exceptions
UnsupportedOperationException:
if addition of elements is not supported by the specified collection
ClassCastException:
if the class of an element of this queue prevents it from being added to the specified collection
NullPointerException:
if the specified collection is null
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
drainToback to summary
public int drainTo(Collection<? super E> c, int maxElements)

Implements java.util.concurrent.BlockingQueue.drainTo.

Doc from java.util.concurrent.BlockingQueue.drainTo.

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:Collection<? super E>

the collection to transfer elements into

maxElements:int

the maximum number of elements to transfer

Returns:int

the number of elements transferred

Exceptions
UnsupportedOperationException:
if addition of elements is not supported by the specified collection
ClassCastException:
if the class of an element of this queue prevents it from being added to the specified collection
NullPointerException:
if the specified collection is null
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
iteratorback to summary
public Iterator<E> iterator()

Implements abstract java.util.AbstractCollection.iterator.

Implements java.util.Collection.iterator.

Returns an iterator over all the elements (both expired and unexpired) in this queue. The iterator does not return the elements in any particular order.

The returned iterator is weakly consistent.

Returns:Iterator<E>

an iterator over the elements in this queue

offerback to summary
public boolean offer(E e)

Implements java.util.concurrent.BlockingQueue.offer, java.util.Queue.offer.

Inserts the specified element into this delay queue.

Parameters
e:E

the element to add

Returns:boolean

true

Exceptions
NullPointerException:
if the specified element is null
offerback to summary
public boolean offer(E e, long timeout, TimeUnit unit)

Implements java.util.concurrent.BlockingQueue.offer.

Inserts the specified element into this delay queue. As the queue is unbounded this method will never block.

Parameters
e:E

the element to add

timeout:long

This parameter is ignored as the method never blocks

unit:TimeUnit

This parameter is ignored as the method never blocks

Returns:boolean

true

Exceptions
NullPointerException:
if the specified element is null
peekback to summary
public E peek()

Implements java.util.Queue.peek.

Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty. Unlike poll, if no expired elements are available in the queue, this method returns the element that will expire next, if one exists.

Returns:E

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

pollback to summary
public E poll()

Implements java.util.Queue.poll.

Retrieves and removes the expired head of this queue, or returns null if this queue has no expired elements.

Returns:E

the expired head of this queue, or null if this queue has no elements with an expired delay

pollback to summary
public E poll(long timeout, TimeUnit unit) throws InterruptedException

Implements java.util.concurrent.BlockingQueue.poll.

Retrieves and removes the expired head of this queue, waiting if necessary until an expired element is available on this queue, or the specified wait time expires.

Parameters
timeout:long

Doc from java.util.concurrent.BlockingQueue.poll.

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

unit:TimeUnit

Doc from java.util.concurrent.BlockingQueue.poll.

a TimeUnit determining how to interpret the timeout parameter

Returns:E

the expired head of this queue, or null if the specified waiting time elapses before an element with an expired delay becomes available

Exceptions
InterruptedException:
if interrupted while waiting
putback to summary
public void put(E e)

Implements java.util.concurrent.BlockingQueue.put.

Inserts the specified element into this delay queue. As the queue is unbounded this method will never block.

Parameters
e:E

the element to add

Exceptions
NullPointerException:
if the specified element is null
remainingCapacityback to summary
public int remainingCapacity()

Implements java.util.concurrent.BlockingQueue.remainingCapacity.

Always returns Integer.MAX_VALUE because a DelayQueue is not capacity constrained.

Returns:int

Integer.MAX_VALUE

removeback to summary
public E remove()

Overrides java.util.AbstractQueue.remove.

Implements java.util.Queue.remove.

Retrieves and removes the expired head of this queue, or throws an exception if this queue has no expired elements.

Returns:E

the expired head of this queue

Exceptions
NoSuchElementException:
if this queue has no elements with an expired delay
removeback to summary
public boolean remove(Object o)

Overrides java.util.AbstractCollection.remove.

Implements java.util.concurrent.BlockingQueue.remove, java.util.Collection.remove.

Removes a single instance of the specified element from this queue, if it is present, whether or not it has expired.

Parameters
o:Object

Doc from java.util.concurrent.BlockingQueue.remove.

element to be removed from this queue, if present

Returns:boolean

Doc from java.util.concurrent.BlockingQueue.remove.

true if this queue changed as a result of the call

removeEQback to summary
pack-priv void removeEQ(Object o)

Identity-based version for use in Itr.remove.

sizeback to summary
public int size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.Collection.size.

Doc from java.util.Collection.size.

Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:int

the number of elements in this collection

takeback to summary
public E take() throws InterruptedException

Implements java.util.concurrent.BlockingQueue.take.

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

Returns:E

the expired head of this queue

Exceptions
InterruptedException:
if interrupted while waiting
toArrayback to summary
public Object[] toArray()

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Returns an array containing all of the elements in this queue. The returned array elements are in no particular order.

The returned array will be "safe" in that no references to it are maintained by this queue. (In other words, this method must allocate a new array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns:Object[]

an array containing all of the elements in this queue

toArrayback to summary
public <T> T[] toArray(T[] a)

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Returns an array containing all of the elements in this queue; the runtime type of the returned array is that of the specified array. The returned array elements are in no particular order. If the queue fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this queue.

If this queue fits in the specified array with room to spare (i.e., the array has more elements than this queue), the element in the array immediately following the end of the queue is set to null.

Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

The following code can be used to dump a delay queue into a newly allocated array of Delayed:

 Delayed[] a = q.toArray(new Delayed[0]);
Note that toArray(new Object[0]) is identical in function to toArray().
Parameters
<T>

Doc from java.util.Collection.toArray. the component type of the array to contain the collection

a:T[]

the array into which the elements of the queue are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose

Returns:T[]

an array containing all of the elements in this queue

Exceptions
ArrayStoreException:
if the runtime type of the specified array is not a supertype of the runtime type of every element in this queue
NullPointerException:
if the specified array is null
java.util.concurrent back to summary

private Class DelayQueue.Itr

extends Object
implements Iterator<E extends Delayed>
Class Inheritance
All Implemented Interfaces
java.util.Iterator

Snapshot iterator that works off copy of underlying q array.

Field Summary

Modifier and TypeField and Description
pack-priv final Object[]
pack-priv int
pack-priv int

Constructor Summary

AccessConstructor and Description
pack-priv
Itr(Object[] array)

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.

public E
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.

public void
remove()

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

arrayback to summary
pack-priv final Object[] array
cursorback to summary
pack-priv int cursor
lastRetback to summary
pack-priv int lastRet

Constructor Detail

Itrback to summary
pack-priv Itr(Object[] array)

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

nextback to summary
public E next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:E

the next element in the iteration

Annotations
@SuppressWarnings:unchecked
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.