FileDocCategorySizeDatePackage
DelayQueue.javaAPI DocJava SE 5 API12258Fri Aug 26 14:57:26 BST 2005java.util.concurrent

DelayQueue

public class DelayQueue extends AbstractQueue implements BlockingQueue
An unbounded {@linkplain BlockingQueue blocking queue} of Delayed elements, in which an element can only be taken when its delay has expired. The head of the queue is that Delayed element whose delay expired furthest in the past. If no delay has expired there is no head and poll will return null. Expiration occurs when an element's getDelay(TimeUnit.NANOSECONDS) method returns a value less than or equal to zero. This queue does not permit null elements.

This class and its iterator implement all of the optional methods of the {@link Collection} and {@link Iterator} interfaces.

This class is a member of the Java Collections Framework.

since
1.5
author
Doug Lea
param
the type of elements held in this collection

Fields Summary
private final transient ReentrantLock
lock
private final transient Condition
available
private final PriorityQueue
q
Constructors Summary
public DelayQueue()
Creates a new DelayQueue that is initially empty.


                 
      
public DelayQueue(Collection c)
Creates a DelayQueue initially containing the elements of the given collection of {@link Delayed} instances.

param
c the collection
throws
NullPointerException if c or any element within it is null

        this.addAll(c);
    
Methods Summary
public booleanadd(E o)
Adds the specified element to this queue.

param
o the element to add
return
true (as per the general contract of Collection.add).
throws
NullPointerException if the specified element is null.

        return offer(o);
    
public voidclear()
Atomically removes all of the elements from this delay queue. The queue will be empty after this call returns.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            q.clear();
        } finally {
            lock.unlock();
        }
    
public intdrainTo(java.util.Collection c)

        if (c == null)
            throw new NullPointerException();
        if (c == this)
            throw new IllegalArgumentException();
        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            int n = 0;
            for (;;) {
                E first = q.peek();
                if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
                    break;
                c.add(q.poll());
                ++n;
            }
            if (n > 0)
                available.signalAll();
            return n;
        } finally {
            lock.unlock();
        }
    
public intdrainTo(java.util.Collection c, int maxElements)

        if (c == null)
            throw new NullPointerException();
        if (c == this)
            throw new IllegalArgumentException();
        if (maxElements <= 0)
            return 0;
        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            int n = 0;
            while (n < maxElements) {
                E first = q.peek();
                if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
                    break;
                c.add(q.poll());
                ++n;
            }
            if (n > 0)
                available.signalAll();
            return n;
        } finally {
            lock.unlock();
        }
    
public java.util.Iteratoriterator()
Returns an iterator over the elements in this queue. The iterator does not return the elements in any particular order. The returned iterator is a thread-safe "fast-fail" iterator that will throw {@link java.util.ConcurrentModificationException} upon detected interference.

return
an iterator over the elements in this queue.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return new Itr(q.iterator());
        } finally {
            lock.unlock();
        }
    
public booleanoffer(E o)
Inserts the specified element into this delay queue.

param
o the element to add
return
true
throws
NullPointerException if the specified element is null.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            E first = q.peek();
            q.offer(o);
            if (first == null || o.compareTo(first) < 0)
                available.signalAll();
            return true;
        } finally {
            lock.unlock();
        }
    
public booleanoffer(E o, long timeout, java.util.concurrent.TimeUnit unit)
Inserts the specified element into this delay queue. As the queue is unbounded this method will never block.

param
o the element to add
param
timeout This parameter is ignored as the method never blocks
param
unit This parameter is ignored as the method never blocks
return
true
throws
NullPointerException if the specified element is null.

        return offer(o);
    
public Epeek()
Retrieves, but does not remove, the head of this queue, returning null if this queue has no elements with an unexpired delay.

return
the head of this queue, or null if this queue has no elements with an unexpired delay.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return q.peek();
        } finally {
            lock.unlock();
        }
    
public Epoll(long timeout, java.util.concurrent.TimeUnit unit)
Retrieves and removes the head of this queue, waiting if necessary up to the specified wait time if no elements with an unexpired delay are present on this queue.

param
timeout how long to wait before giving up, in units of unit
param
unit a TimeUnit determining how to interpret the timeout parameter
return
the head of this queue, or null if the specified waiting time elapses before an element with an unexpired delay is present.
throws
InterruptedException if interrupted while waiting.

        final ReentrantLock lock = this.lock;
        lock.lockInterruptibly();
        long nanos = unit.toNanos(timeout);
        try {
            for (;;) {
                E first = q.peek();
                if (first == null) {
                    if (nanos <= 0)
                        return null;
                    else
                        nanos = available.awaitNanos(nanos);
                } else {
                    long delay =  first.getDelay(TimeUnit.NANOSECONDS);
                    if (delay > 0) {
                        if (delay > nanos)
                            delay = nanos;
                        long timeLeft = available.awaitNanos(delay);
                        nanos -= delay - timeLeft;
                    } else {
                        E x = q.poll();
                        assert x != null;
                        if (q.size() != 0)
                            available.signalAll();
                        return x;
                    }
                }
            }
        } finally {
            lock.unlock();
        }
    
public Epoll()
Retrieves and removes the head of this queue, or null if this queue has no elements with an unexpired delay.

return
the head of this queue, or null if this queue has no elements with an unexpired delay.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            E first = q.peek();
            if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
                return null;
            else {
                E x = q.poll();
                assert x != null;
                if (q.size() != 0)
                    available.signalAll();
                return x;
            }
        } finally {
            lock.unlock();
        }
    
public voidput(E o)
Adds the specified element to this delay queue. As the queue is unbounded this method will never block.

param
o the element to add
throws
NullPointerException if the specified element is null.

        offer(o);
    
public intremainingCapacity()
Always returns Integer.MAX_VALUE because a DelayQueue is not capacity constrained.

return
Integer.MAX_VALUE

        return Integer.MAX_VALUE;
    
public booleanremove(java.lang.Object o)
Removes a single instance of the specified element from this queue, if it is present.

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return q.remove(o);
        } finally {
            lock.unlock();
        }
    
public intsize()

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return q.size();
        } finally {
            lock.unlock();
        }
    
public Etake()
Retrieves and removes the head of this queue, waiting if no elements with an unexpired delay are present on this queue.

return
the head of this queue
throws
InterruptedException if interrupted while waiting.

        final ReentrantLock lock = this.lock;
        lock.lockInterruptibly();
        try {
            for (;;) {
                E first = q.peek();
                if (first == null) {
                    available.await();
                } else {
                    long delay =  first.getDelay(TimeUnit.NANOSECONDS);
                    if (delay > 0) {
                        long tl = available.awaitNanos(delay);
                    } else {
                        E x = q.poll();
                        assert x != null;
                        if (q.size() != 0)
                            available.signalAll(); // wake up other takers
                        return x;

                    }
                }
            }
        } finally {
            lock.unlock();
        }
    
public java.lang.Object[]toArray()

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return q.toArray();
        } finally {
            lock.unlock();
        }
    
public T[]toArray(T[] array)

        final ReentrantLock lock = this.lock;
        lock.lock();
        try {
            return q.toArray(array);
        } finally {
            lock.unlock();
        }