edu.emory.mathcs.util.concurrent
Class DynamicArrayBlockingQueue

java.lang.Object
  extended byjava.util.AbstractCollection
      extended byedu.emory.mathcs.backport.java.util.AbstractCollection
          extended byedu.emory.mathcs.backport.java.util.AbstractQueue
              extended byedu.emory.mathcs.util.concurrent.DynamicArrayBlockingQueue
All Implemented Interfaces:
BlockingQueue, java.util.Collection, Queue

public class DynamicArrayBlockingQueue
extends AbstractQueue
implements BlockingQueue

This class represents queue of objects. Data is generally stored at the bottom of the queue by put and related operations, and read from the top of the queue by take and related operations. The putAtHead family of operations is also provided to allow storing data at the head of the queue. The underlying implementation uses an array, so no memory allocation occur on queue operations apart from situations where array needs to be resized. The initial and maximum capacity of the queue can be specified at the construction time. The maximum capacity may be also set to "infinity", in which case put operations will never block.

Version:
1.0
Author:
Dawid Kurzyniec
See Also:
BlockingQueue

Constructor Summary
DynamicArrayBlockingQueue()
          Creates new queue object with initial capacity of 16 and unlimited maximum capacity.
DynamicArrayBlockingQueue(int initcap)
          Creates new queue object with specified initial capacity and unlimited maximum capacity.
DynamicArrayBlockingQueue(int initcap, int maxcap)
          Creates new queue object with specified initial capacity and specified maximum capacity.
 
Method Summary
 int drainTo(java.util.Collection c)
          Removes all available elements from this queue and adds them to the given collection.
 int drainTo(java.util.Collection c, int maxElements)
          Removes at most the given number of available elements from this queue and adds them to the given collection.
 java.util.Iterator iterator()
           
 boolean offer(java.lang.Object o)
          Puts specified object at the bottom of the queue, if possible.
 boolean offer(java.lang.Object o, long timeout, TimeUnit granularity)
          Puts specified object at the bottom of the queue with specified timeout and returns true if operation succeeded, false otherwise.
 boolean offerAtHead(java.lang.Object o)
          Inserts specified object at the top of the queue, so the next call to get() would return this object.
 boolean offerAtHead(java.lang.Object o, int timeout, TimeUnit granularity)
          Inserts specified object at the top of the queue, so the next call to get() would return this object, with specified timeout and returns true if operation succeeded, false otherwise.
 java.lang.Object peek()
          Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
 java.lang.Object poll()
          Remove and return an element from the queue if one is available.
 java.lang.Object poll(long timeout, TimeUnit granularity)
          Gets the object from the top of the queue.
 void put(java.lang.Object o)
          Inserts the specified element into this queue, waiting if necessary for space to become available.
 void putAtHead(java.lang.Object o)
          Inserts specified object at the top of the queue, so the next call to poll() or take() would return this object.
 int remainingCapacity()
          Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer.MAX_VALUE if there is no intrinsic limit.
 int size()
          Returns the number of items in this queue.
 java.lang.Object take()
          Retrieve and remove the first element from the queue, waiting if no objects are present on the queue.
 
Methods inherited from class edu.emory.mathcs.backport.java.util.AbstractQueue
add, addAll, clear, element, remove
 
Methods inherited from class edu.emory.mathcs.backport.java.util.AbstractCollection
toArray, toArray
 
Methods inherited from class java.util.AbstractCollection
contains, containsAll, isEmpty, remove, removeAll, retainAll, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface edu.emory.mathcs.backport.java.util.concurrent.BlockingQueue
add, contains, remove
 
Methods inherited from interface edu.emory.mathcs.backport.java.util.Queue
element, remove
 
Methods inherited from interface java.util.Collection
addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray
 

Constructor Detail

DynamicArrayBlockingQueue

public DynamicArrayBlockingQueue()
Creates new queue object with initial capacity of 16 and unlimited maximum capacity.


DynamicArrayBlockingQueue

public DynamicArrayBlockingQueue(int initcap)
Creates new queue object with specified initial capacity and unlimited maximum capacity. Initial capacity must be greater than 0, otherwise IllegalArgumentException will be thrown.

Parameters:
initcap - initial capacity of the queue.
Throws:
java.lang.IllegalArgumentException - if initial capacity is not greater than 0.

DynamicArrayBlockingQueue

public DynamicArrayBlockingQueue(int initcap,
                                 int maxcap)
Creates new queue object with specified initial capacity and specified maximum capacity. Initial capacity must be greater than 0, otherwise IllegalArgumentException will be thrown. Maximum capacity of less than or equal to 0 indicates no limit. Otherwise if the maximum capacity is positive number, it has to be greater than or equal to initial capacity, or IllegalArgumentException will be thrown.

Parameters:
initcap - initial capacity of the queue.
maxcap - maximum capacity of the queue.
Throws:
java.lang.IllegalArgumentException - if initial capacity is not greater than 0, or maximum capacity is positive number but less than initial capacity.
Method Detail

size

public int size()
Returns the number of items in this queue.

Specified by:
size in interface java.util.Collection

remainingCapacity

public int remainingCapacity()
Description copied from interface: BlockingQueue
Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer.MAX_VALUE if there is no intrinsic limit.

Note that you cannot always tell if an attempt to insert an element will succeed by inspecting remainingCapacity because it may be the case that another thread is about to insert or remove an element.

Specified by:
remainingCapacity in interface BlockingQueue
Returns:
the remaining capacity

iterator

public java.util.Iterator iterator()
Specified by:
iterator in interface java.util.Collection

offer

public boolean offer(java.lang.Object o)
Puts specified object at the bottom of the queue, if possible.

Specified by:
offer in interface BlockingQueue
Parameters:
o - object to be put on the bottom of the queue.
Returns:
true if the element was added to this queue, else false

offer

public boolean offer(java.lang.Object o,
                     long timeout,
                     TimeUnit granularity)
              throws java.lang.InterruptedException
Puts specified object at the bottom of the queue with specified timeout and returns true if operation succeeded, false otherwise. If the length of the queue is equal to its maximum capacity, this method will block until either the length decreases (in which case it proceeds with put and returns true) or timeout expires (in which case it returns false), whichever comes first. If the timeout is a positive number, it indicates a number of milliseconds to wait for available space. If the timeout is equal to 0 and the queue is full, the method will immediately return false. If the timeout is negative, the method will never timeout.

Specified by:
offer in interface BlockingQueue
Parameters:
o - object to be put on the bottom of the queue.
timeout - number of milliseconds to wait for available space.
granularity - a TimeUnit determining how to interpret the timeout parameter
Returns:
true if operation succeeded, false if it was abandoned due to the timeout.
Throws:
java.lang.InterruptedException - if operation is interrupted by other thread

put

public void put(java.lang.Object o)
         throws java.lang.InterruptedException
Description copied from interface: BlockingQueue
Inserts the specified element into this queue, waiting if necessary for space to become available.

Specified by:
put in interface BlockingQueue
Parameters:
o - the element to add
Throws:
java.lang.InterruptedException - if interrupted while waiting

offerAtHead

public boolean offerAtHead(java.lang.Object o)
Inserts specified object at the top of the queue, so the next call to get() would return this object.

Parameters:
o - object to be inserted on the top of the queue.
Throws:
java.lang.InterruptedException - if operation is interrupted by other thread.

putAtHead

public void putAtHead(java.lang.Object o)
               throws java.lang.InterruptedException
Inserts specified object at the top of the queue, so the next call to poll() or take() would return this object. If the length of the queue is equal to its maximum capacity, this method will block until the length decreases so that the operation can proceed.

Parameters:
o - object to be put at the head of the queue.
Throws:
java.lang.InterruptedException - if operation is interrupted by other thread.

offerAtHead

public boolean offerAtHead(java.lang.Object o,
                           int timeout,
                           TimeUnit granularity)
                    throws java.lang.InterruptedException
Inserts specified object at the top of the queue, so the next call to get() would return this object, with specified timeout and returns true if operation succeeded, false otherwise. If the length of the queue is equal to its maximum capacity, this method will block until either the length decreases (in which case it proceeds with insert and returns true) or timeout expires (in which case it returns false), whichever comes first. If the timeout is a positive number, it indicates a number of milliseconds to wait for available space. If the timeout is equal to 0 and the queue is full, the method will immediately return false. If the timeout is negative, the method will never timeout.

Parameters:
o - object to be inserted on the top of the queue.
timeout - number of milliseconds to wait for available space.
Returns:
true if operation succeeded, false if it was abandoned due to the timeout.
Throws:
java.lang.InterruptedException - if operation is interrupted by other thread.

take

public java.lang.Object take()
                      throws java.lang.InterruptedException
Retrieve and remove the first element from the queue, waiting if no objects are present on the queue.

Specified by:
take in interface BlockingQueue
Returns:
the object
Throws:
java.lang.InterruptedException - if interrupted while waiting.

poll

public java.lang.Object poll(long timeout,
                             TimeUnit granularity)
                      throws java.lang.InterruptedException
Gets the object from the top of the queue. If the queue is empty, this method will block until either the length increases (in which case it proceeds with get) or timeout expires (in which case it returns null), whichever comes first. If the timeout is a positive number, it indicates a number of milliseconds to wait. If the timeout is equal to 0 and the queue is empty, the method will immediately return null. If the timeout is negative, the method will never timeout.

Specified by:
poll in interface BlockingQueue
Parameters:
timeout - number of milliseconds to wait for available space.
granularity - a TimeUnit determining how to interpret the timeout parameter
Returns:
object from the top of the queue or null on timeout.
Throws:
java.lang.InterruptedException - if operation is interrupted by other thread.

peek

public java.lang.Object peek()
Description copied from interface: Queue
Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.

Specified by:
peek in interface Queue
Returns:
the head of this queue, or null if this queue is empty

poll

public java.lang.Object poll()
Remove and return an element from the queue if one is available.

Specified by:
poll in interface Queue
Returns:
an element previously on the queue, or null if the queue is empty.

drainTo

public int drainTo(java.util.Collection c)
Description copied from interface: BlockingQueue
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.

Specified by:
drainTo in interface BlockingQueue
Parameters:
c - the collection to transfer elements into
Returns:
the number of elements transferred

drainTo

public int drainTo(java.util.Collection c,
                   int maxElements)
Description copied from interface: BlockingQueue
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.

Specified by:
drainTo in interface BlockingQueue
Parameters:
c - the collection to transfer elements into
maxElements - the maximum number of elements to transfer
Returns:
the number of elements transferred