Class SingleConsumerQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
com.github.benmanes.caffeine.SingleConsumerQueue<E>
Type Parameters:
E - the type of elements held in this collection
All Implemented Interfaces:
Serializable, Iterable<E>, Collection<E>, Queue<E>
@Deprecated public final class SingleConsumerQueue<E> extends AbstractQueue<E> implements Queue<E>, Serializable
Deprecated.
Scheduled for removal in version 3.0.0
A lock-free unbounded queue based on linked nodes that supports concurrent producers and is restricted to a single consumer. 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. Like most other concurrent collection implementations, this class does not permit the use of null elements.

A SingleConsumerQueue is an appropriate choice when many producer threads will share access to a common collection and a single consumer thread drains it. This collection is useful in scenarios such as implementing flat combining, actors, or lock amortization.

This implementation employs combination to transfer elements between threads that are producing concurrently. This approach avoids contention on the queue by combining colliding operations that have identical semantics. When a pair of producers collide, the task of performing the combined set of operations is delegated to one of the threads and the other thread optionally waits for its operation to be completed. This decision of whether to wait for completion is determined by constructing either a linearizable or optimistic queue.

Iterators are weakly consistent, returning elements reflecting the state of the queue at some point at or since the creation of the iterator. They do not throw ConcurrentModificationException, and may proceed concurrently with other operations. Elements contained in the queue since the creation of the iterator will be returned exactly once.

Beware that it is the responsibility of the caller to ensure that a consumer has exclusive read access to the queue. This implementation does not include fail-fast behavior to guard against incorrect consumer usage.

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, and so may report inaccurate results if this collection is modified during traversal.

Warning: This class is scheduled for removal in version 3.0.0.

Author:
ben.manes@gmail.com (Ben Manes)
See Also:

  • Method Details

    • optimistic

      public static <E> SingleConsumerQueue<E> optimistic()
      Deprecated.
      Creates a queue with an optimistic backoff strategy. A thread completes its operation without waiting after it successfully hands off the additional element(s) to another producing thread for batch insertion. This optimistic behavior may result in additions not appearing in FIFO order due to the backoff strategy trying to compensate for queue contention.
      Type Parameters:
      E - the type of elements held in this collection
      Returns:
      a new queue where producers complete their operation immediately if combined with another producing thread's

    • linearizable

      public static <E> SingleConsumerQueue<E> linearizable()
      Deprecated.
      Creates a queue with a linearizable backoff strategy. A thread waits for a completion signal if it successfully hands off the additional element(s) to another producing thread for batch insertion.
      Type Parameters:
      E - the type of elements held in this collection
      Returns:
      a new queue where producers wait for a completion signal after combining its addition with another producing thread's

    • isEmpty

      public boolean isEmpty()
      Deprecated.
      Specified by:
      isEmpty in interface Collection<E>
      Overrides:
      isEmpty in class AbstractCollection<E>

    • size

      public int size()
      Deprecated.
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in class AbstractCollection<E>

    • contains

      public boolean contains(Object o)
      Deprecated.
      Specified by:
      contains in interface Collection<E>
      Overrides:
      contains in class AbstractCollection<E>

    • peek

      public E peek()
      Deprecated.
      Specified by:
      peek in interface Queue<E>

    • offer

      public boolean offer(E e)
      Deprecated.
      Specified by:
      offer in interface Queue<E>

    • poll

      public E poll()
      Deprecated.
      Specified by:
      poll in interface Queue<E>

    • add

      public boolean add(E e)
      Deprecated.
      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface Queue<E>
      Overrides:
      add in class AbstractQueue<E>

    • addAll

      public boolean addAll(Collection<? extends E> c)
      Deprecated.
      Specified by:
      addAll in interface Collection<E>
      Overrides:
      addAll in class AbstractQueue<E>

    • iterator

      public Iterator<E> iterator()
      Deprecated.
      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in class AbstractCollection<E>