Top Description Inners Fields Constructors Methods
java.util.concurrent

public Class ArrayBlockingQueue<E>

extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.util.concurrent.BlockingQueue, java.util.Queue, java.util.Collection, java.lang.Iterable
Type Parameters
<E>
the type of elements held in this queue
Imports
java.lang.ref.WeakReference, java.util.AbstractQueue, .Arrays, .Collection, .Iterator, .NoSuchElementException, .Objects, .Spliterator, .Spliterators, java.util.concurrent.locks.Condition, .ReentrantLock, java.util.function.Consumer, .Predicate
A bounded blocking queue backed by an array. This queue orders elements FIFO (first-in-first-out). The head of the queue is that element that has been on the queue the longest time. The tail of the queue is that element that has been on the queue the shortest time. New elements are inserted at the tail of the queue, and the queue retrieval operations obtain elements at the head of the queue.

This is a classic "bounded buffer", in which a fixed-sized array holds elements inserted by producers and extracted by consumers. Once created, the capacity cannot be changed. Attempts to put an element into a full queue will result in the operation blocking; attempts to take an element from an empty queue will similarly block.

This class supports an optional fairness policy for ordering waiting producer and consumer threads. By default, this ordering is not guaranteed. However, a queue constructed with fairness set to true grants threads access in FIFO order. Fairness generally decreases throughput but reduces variability and avoids starvation.

This class and its iterator implement all of the optional methods of the Collection and Iterator interfaces.

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
ArrayBlockingQueue.Itr

Iterator for ArrayBlockingQueue.

pack-priv class
ArrayBlockingQueue.Itrs

Shared data between iterators and their queue, allowing queue modifications to update iterators when elements are removed.

Field Summary

Modifier and TypeField and Description
pack-priv int
count

Number of elements in the queue

pack-priv final Object[]
items

The queued items

pack-priv transient ArrayBlockingQueue<E>.Itrs
itrs

Shared state for currently active iterators, or null if there are known not to be any.

pack-priv final ReentrantLock
lock

Main lock guarding all access

private final Condition
notEmpty

Condition for waiting takes

private final Condition
notFull

Condition for waiting puts

pack-priv int
putIndex

items index for next put, offer, or add

private static final long
serialVersionUID

Serialization ID. This class relies on default serialization even for the items array, which is default-serialized, even if it is empty.

pack-priv int
takeIndex

items index for next take, poll, peek or remove

Constructor Summary

AccessConstructor and Description
public
ArrayBlockingQueue(int
the capacity of this queue
capacity)

Creates an ArrayBlockingQueue with the given (fixed) capacity and default access policy.

public
ArrayBlockingQueue(int
the capacity of this queue
capacity, boolean
if true then queue accesses for threads blocked on insertion or removal, are processed in FIFO order; if false the access order is unspecified.
fair)

Creates an ArrayBlockingQueue with the given (fixed) capacity and the specified access policy.

public
ArrayBlockingQueue(int
the capacity of this queue
capacity, boolean
if true then queue accesses for threads blocked on insertion or removal, are processed in FIFO order; if false the access order is unspecified.
fair, Collection<? extends E>
the collection of elements to initially contain
c)

Creates an ArrayBlockingQueue with the given (fixed) capacity, the specified access policy and initially containing the elements of the given collection, added in traversal order of the collection's iterator.

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 at the tail of this queue if it is possible to do so immediately without exceeding the queue's capacity, returning true upon success and throwing an IllegalStateException if this queue is full.
private boolean
bulkRemove(Predicate<? super E> filter)

Implementation of bulk remove methods.

private boolean
bulkRemoveModified(Predicate<? super E> filter, final int
valid index of first element to be deleted
beg)

Helper for bulkRemove, in case of at least one deletion.

pack-priv void
checkInvariants()

debugging

private static void
circularClear(Object[] items, int i, int end)

Nulls out slots starting at array index i, up to index end.

public void
clear()

Overrides java.util.AbstractQueue.clear.

Implements java.util.Collection.clear.

Atomically removes all of the elements from this queue.
public boolean

Returns:

true if this queue contains the specified element
contains(Object
object to be checked for containment in this queue
o)

Overrides java.util.AbstractCollection.contains.

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

Returns true if this queue contains the specified element.
pack-priv static final int
dec(int i, int modulus)

Decrements i, mod modulus.

private E
dequeue()

Extracts element at current take position, advances, and signals.

private int
distanceNonEmpty(int i, int j)

Returns circular distance from i to j, disambiguating i == j to items.length; never returns 0.

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.
private void
enqueue(E e)

Inserts element at current put position, advances, and signals.

public void
forEach(Consumer<? super E>
The action to be performed for each element
action)

Overrides default java.lang.Iterable.forEach.

Performs the given action for each element of the Iterable until all elements have been processed or the action throws an exception.
pack-priv static final int
inc(int i, int modulus)

Increments i, mod modulus.

private boolean
invariantsSatisfied()

private static boolean
isClear(long[] bits, int i)

pack-priv final E
itemAt(int i)

Returns item at index i.

pack-priv static <E> E
itemAt(Object[] items, int i)

Returns element at array index i.

public Iterator<E>

Returns:

an iterator over the elements in this queue in proper sequence
iterator()

Implements abstract java.util.AbstractCollection.iterator.

Implements java.util.Collection.iterator.

Returns an iterator over the elements in this queue in proper sequence.
private static long[]
nBits(int n)

public boolean
offer(E
the element to add
e)

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

Inserts the specified element at the tail of this queue if it is possible to do so immediately without exceeding the queue's capacity, returning true upon success and false if this queue is full.
public boolean
offer(E
the element to add
e, 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.offer.

Inserts the specified element at the tail of this queue, waiting up to the specified wait time for space to become available if the queue is full.
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.
public E
poll()

Implements java.util.Queue.poll.

Retrieves and removes the head of this queue, or returns null if this queue is empty.
public E
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 head of this queue, waiting up to the specified wait time if necessary for an element to become available.
public void
put(E
the element to add
e)

Implements java.util.concurrent.BlockingQueue.put.

Inserts the specified element at the tail of this queue, waiting for space to become available if the queue is full.
private void
readObject(ObjectInputStream
the stream
s)

Reconstitutes this queue from a stream (that is, deserializes it).

public int
remainingCapacity()

Implements java.util.concurrent.BlockingQueue.remainingCapacity.

Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking.
public boolean

Returns:

true if this queue changed as a result of the call
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.
public boolean
removeAll(Collection<?>
collection containing elements to be removed from this collection
c)

Overrides java.util.AbstractCollection.removeAll.

Implements java.util.Collection.removeAll.

Removes all of this collection's elements that are also contained in the specified collection (optional operation).
pack-priv void
removeAt(final int removeIndex)

Deletes item at array index removeIndex.

public boolean
removeIf(Predicate<? super E>
a predicate which returns true for elements to be removed
filter)

Overrides default java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate (optional operation).
public boolean
retainAll(Collection<?>
collection containing elements to be retained in this collection
c)

Overrides java.util.AbstractCollection.retainAll.

Implements java.util.Collection.retainAll.

Retains only the elements in this collection that are contained in the specified collection (optional operation).
private static void
setBit(long[] bits, int i)

public int

Returns:

the number of elements in this queue
size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.Collection.size.

Returns the number of elements in this queue.
public Spliterator<E>

Returns:

a Spliterator over the elements in this queue
spliterator()

Overrides default java.util.Collection.spliterator.

Returns a Spliterator over the elements in this queue.
public E
take()

Implements java.util.concurrent.BlockingQueue.take.

Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.
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, in proper sequence.
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, in proper sequence; the runtime type of the returned array is that of the specified array.
public String
toString()

Overrides java.util.AbstractCollection.toString.

Returns a string representation of this collection.
Inherited from java.util.AbstractQueue:
addAllelementremove