Class SingleConsumerQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
com.github.benmanes.caffeine.SCQHeader.PadHead<E>
com.github.benmanes.caffeine.SCQHeader.HeadRef<E>
com.github.benmanes.caffeine.SCQHeader.PadHeadAndTail<E>
com.github.benmanes.caffeine.SCQHeader.HeadAndTailRef<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 SCQHeader.HeadAndTailRef<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.

See Also:

  • Field Details

    • NCPU

      static final int NCPU
      Deprecated.
      The number of CPUs

    • ARENA_LENGTH

      static final int ARENA_LENGTH
      Deprecated.
      The number of slots in the elimination array.

    • ARENA_MASK

      static final int ARENA_MASK
      Deprecated.
      The mask value for indexing into the arena.

    • OPTIMISIC

      static final Function<?,?> OPTIMISIC
      Deprecated.
      The factory for creating an optimistic node.

    • SPINS

      static final int SPINS
      Deprecated.
      The number of times to spin (doing nothing except polling a memory location) before giving up while waiting to eliminate an operation. Should be zero on uniprocessors. On multiprocessors, this value should be large enough so that two threads exchanging items as fast as possible block only when one of them is stalled (due to GC or preemption), but not much longer, to avoid wasting CPU resources. Seen differently, this value is a little over half the number of cycles of an average context switch time on most systems. The value here is approximately the average of those across a range of tested systems.

    • PROBE

      static final long PROBE
      Deprecated.
      The offset to the thread-specific probe field.

    • arena

      final AtomicReference<SingleConsumerQueue.Node<E>>[] arena
      Deprecated.

    • factory

      final Function<E, SingleConsumerQueue.Node<E>> factory
      Deprecated.

    • serialVersionUID

      static final long serialVersionUID
      Deprecated.
      See Also:

  • Constructor Details

  • Method Details

    • ceilingPowerOfTwo

      static int ceilingPowerOfTwo(int x)
      Deprecated.

    • 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>

    • append

      void append(@NonNull SingleConsumerQueue.Node<E> first, @NonNull SingleConsumerQueue.Node<E> last)
      Deprecated.
      Adds the linked list of nodes to the queue.

    • transferOrCombine

      @Nullable SingleConsumerQueue.Node<E> transferOrCombine(@NonNull SingleConsumerQueue.Node<E> first, SingleConsumerQueue.Node<E> last)
      Deprecated.
      Attempts to receive a linked list from a waiting producer or transfer the specified linked list to an arriving producer.
      Parameters:
      first - the first node in the linked list to try to transfer
      last - the last node in the linked list to try to transfer
      Returns:
      either null if the element was transferred, the first node if neither a transfer nor receive were successful, or the received last element from a producer

    • index

      static int index()
      Deprecated.
      Returns the arena index for the current thread.

    • findLast

      static <E> @NonNull SingleConsumerQueue.Node<E> findLast(@NonNull SingleConsumerQueue.Node<E> node)
      Deprecated.
      Returns the last node in the linked list.

    • 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>

    • writeReplace

      Object writeReplace()
      Deprecated.

    • readObject

      private void readObject(ObjectInputStream stream) throws InvalidObjectException
      Deprecated.
      Throws:
      InvalidObjectException