Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.emory.mathcs.util.concurrent
Class DynamicArrayBlockingQueue

    java.lang.Object
      java.util.AbstractCollection
          edu.emory.mathcs.backport.java.util.AbstractCollection
              edu.emory.mathcs.backport.java.util.AbstractQueue
                  edu.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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD