public class

ConcurrentLinkedQueue

extends AbstractQueue<E>
implements Serializable Queue<E>
java.lang.Object
   ↳ java.util.AbstractCollection<E>
     ↳ java.util.AbstractQueue<E>
       ↳ java.util.concurrent.ConcurrentLinkedQueue<E>

Class Overview

An unbounded thread-safe queue based on linked nodes. 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. A ConcurrentLinkedQueue is an appropriate choice when many threads will share access to a common collection. This queue does not permit null elements.

This implementation employs an efficient "wait-free" algorithm based on one described in Simple, Fast, and Practical Non-Blocking and Blocking Concurrent Queue Algorithms by Maged M. Michael and Michael L. Scott.

Beware that, unlike in most collections, the size method is NOT a constant-time operation. Because of the asynchronous nature of these queues, determining the current number of elements requires a traversal of the elements.

This class implements all of the optional methods of the Collection and Iterator interfaces.

Summary

Public Constructors
ConcurrentLinkedQueue()
Creates a ConcurrentLinkedQueue that is initially empty.
ConcurrentLinkedQueue(Collection<? extends E> c)
Creates a ConcurrentLinkedQueue initially containing the elements of the given collection, added in traversal order of the collection's iterator.
Public Methods
boolean add(E o)
Adds the specified element to the tail of this queue.
boolean contains(Object o)
Tests whether this Collection contains the specified object.
boolean isEmpty()
Returns if this Collection contains no elements.
Iterator<E> iterator()
Returns an iterator over the elements in this queue in proper sequence.
boolean offer(E o)
Inserts the specified element to the tail of this queue.
E peek()
Gets but does not remove the element at the head of the queue.
E poll()
Gets and removes the element at the head of the queue, or returns null if there is no element in the queue.
boolean remove(Object o)
Removes one instance of the specified object from this Collection if one is contained (optional).
int size()
Returns the number of elements in this queue.
<T> T[] toArray(T[] a)
Returns an array containing all elements contained in this Collection.
Object[] toArray()
Returns a new array containing all elements contained in this Collection.
[Expand]
Inherited Methods
From class java.util.AbstractQueue
From class java.util.AbstractCollection
From class java.lang.Object
From interface java.lang.Iterable
From interface java.util.Collection
From interface java.util.Queue

Public Constructors

public ConcurrentLinkedQueue ()

Since: API Level 1

Creates a ConcurrentLinkedQueue that is initially empty.

public ConcurrentLinkedQueue (Collection<? extends E> c)

Since: API Level 1

Creates a ConcurrentLinkedQueue initially containing the elements of the given collection, added in traversal order of the collection's iterator.

Parameters
c the collection of elements to initially contain
Throws
NullPointerException if c or any element within it is null

Public Methods

public boolean add (E o)

Since: API Level 1

Adds the specified element to the tail of this queue.

Parameters
o the element to add.
Returns
  • true (as per the general contract of Collection.add).
Throws
NullPointerException if the specified element is null

public boolean contains (Object o)

Since: API Level 1

Tests whether this Collection contains the specified object. This implementation iterates over this Collection and tests, whether any element is equal to the given object. If object != null then object.equals(e) is called for each element e returned by the iterator until the element is found. If object == null then each element e returned by the iterator is compared with the test e == null.

Parameters
o the object to search for.
Returns
  • true if object is an element of this Collection, false otherwise.

public boolean isEmpty ()

Since: API Level 1

Returns if this Collection contains no elements. This implementation tests, whether size returns 0.

Returns
  • true if this Collection has no elements, false otherwise.

public Iterator<E> iterator ()

Since: API Level 1

Returns an iterator over the elements in this queue in proper sequence. The returned iterator is a "weakly consistent" iterator that will never throw ConcurrentModificationException, and guarantees to traverse elements as they existed upon construction of the iterator, and may (but is not guaranteed to) reflect any modifications subsequent to construction.

Returns
  • an iterator over the elements in this queue in proper sequence.

public boolean offer (E o)

Since: API Level 1

Inserts the specified element to the tail of this queue.

Parameters
o the element to add.
Returns
  • true (as per the general contract of Queue.offer).
Throws
NullPointerException if the specified element is null

public E peek ()

Since: API Level 1

Gets but does not remove the element at the head of the queue.

Returns
  • the element at the head of the queue or null if there is no element in the queue.

public E poll ()

Since: API Level 1

Gets and removes the element at the head of the queue, or returns null if there is no element in the queue.

Returns
  • the element at the head of the queue or null if there is no element in the queue.

public boolean remove (Object o)

Since: API Level 1

Removes one instance of the specified object from this Collection if one is contained (optional). This implementation iterates over this Collection and tests for each element e returned by the iterator, whether e is equal to the given object. If object != null then this test is performed using object.equals(e), otherwise using object == null. If an element equal to the given object is found, then the remove method is called on the iterator and true is returned, false otherwise. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.

Parameters
o the object to remove.
Returns
  • true if this Collection is modified, false otherwise.

public int size ()

Since: API Level 1

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

Beware that, unlike in most collections, this method is NOT a constant-time operation. Because of the asynchronous nature of these queues, determining the current number of elements requires an O(n) traversal.

Returns
  • the number of elements in this queue.

public T[] toArray (T[] a)

Since: API Level 1

Returns an array containing all elements contained in this Collection. If the specified array is large enough to hold the elements, the specified array is used, otherwise an array of the same type is created. If the specified array is used and is larger than this Collection, the array element following the Collection elements is set to null. If the implementation has ordered elements it will return the element array in the same order as an iterator would return them. toArray(new Object[0]) behaves exactly the same way as toArray() does.

Parameters
a the array.
Returns
  • an array of the elements from this Collection.

public Object[] toArray ()

Since: API Level 1

Returns a new array containing all elements contained in this Collection. If the implementation has ordered elements it will return the element array in the same order as an iterator would return them. The array returned does not reflect any changes of the Collection. A new array is created even if the underlying data structure is already an array.

Returns
  • an array of the elements from this Collection.