Package org.jctools.queues

This package aims to fill a gap in current JDK implementations in offering lock free (wait free where possible) queues for inter-thread message passing with finer grained guarantees and an emphasis on performance.
At the time of writing the only lock free queue available in the JDK is ConcurrentLinkedQueue which is an unbounded multi-producer, multi-consumer queue which is further encumbered by the need to implement the full range of Queue methods. In this package we offer a range of implementations:

1. Bounded/Unbounded SPSC queues - Serving the Single Producer Single Consumer use case.
2. Bounded/Unbounded MPSC queues - The Multi Producer Single Consumer case also has a multi-lane implementation on offer which trades the FIFO ordering(re-ordering is not limited) for reduced contention and increased throughput under contention.
3. Bounded SPMC/MPMC queues

Limited Queue methods support:
The queues implement a subset of the Queue interface which is documented under the MessagePassingQueue interface. In particular Collection.iterator() is not supported and dependent methods from AbstractQueue are also not supported such as:

1. Collection.remove(Object)
2. Collection.removeAll(java.util.Collection)
3. Collection.removeIf(java.util.function.Predicate)
4. Collection.contains(Object)
5. Collection.containsAll(java.util.Collection)

Memory layout controls and False Sharing:
The classes in this package use what is considered at the moment the most reliable method of controlling class field layout, namely inheritance. The method is described in this post which also covers why other methods are currently suspect.
Note that we attempt to tackle both active (write/write) and passive(read/write) false sharing case:

1. Hot counters (or write locations) are padded.
2. Read-Only shared fields are padded.
3. Array edges are padded.

Use of sun.misc.Unsafe:
A choice is made in this library to utilize sun.misc.Unsafe for performance reasons. In this package we have two use cases:

1. The queue counters in the queues are all inlined (i.e. are primitive fields of the queue classes). To allow lazySet/CAS semantics to these fields we could use AtomicLongFieldUpdater but choose not to for performance reasons. On newer OpenJDKs where AFU is made more performant the difference is small.
2. We use Unsafe to gain volatile/lazySet access to array elements. We could use AtomicReferenceArray but choose not to for performance reasons(extra reference chase and redundant boundary checks).

Both use cases should be made obsolete by VarHandles at some point.

Avoiding redundant loads of fields:
Because a volatile load will force any following field access to reload the field value an effort is made to cache field values in local variables where possible and expose interfaces which allow the code to capitalize on such caching. As a convention the local variable name will be the field name and will be final.

Method naming conventions:
The following convention is followed in method naming to highlight volatile/ordered/plain access to fields:

1. lpFoo/spFoo: these will be plain load or stores to the field. No memory ordering is needed or expected.
2. soFoo: this is an ordered stored to the field (like AtomicInteger.lazySet(int)). Implies an ordering of stores (StoreStore barrier before the store).
3. lv/svFoo: these are volatile load/store. A store implies a StoreLoad barrier, a load implies LoadLoad barrier before and LoadStore after.
4. casFoo: compare and swap the field. StoreLoad if successful. See AtomicInteger.compareAndSet(int, int)
5. xchgFoo: atomically get and set the field. Effectively a StoreLoad. See AtomicInteger.getAndSet(int)
6. xaddFoo: atomically get and add to the field. Effectively a StoreLoad. See AtomicInteger.getAndAdd(int)

It is generally expected that a volatile load signals the acquire of a field previously released by a non-plain store.

Author:

nitsanw

Interface Summary

Interface	Description
IndexedQueueSizeUtil.IndexedQueue
MessagePassingQueue<T>	This is a tagging interface for the queues in this library which implement a subset of the Queue interface sufficient for concurrent message passing. Message passing queues provide happens before semantics to messages passed through, namely that writes made by the producer before offering the message are visible to the consuming thread after the message has been polled out of the queue.
MessagePassingQueue.Consumer<T>
MessagePassingQueue.ExitCondition
MessagePassingQueue.Supplier<T>
MessagePassingQueue.WaitStrategy
QueueProgressIndicators	This interface is provided for monitoring purposes only and is only available on queues where it is easy to provide it.

Class Summary

Class	Description
BaseMpscLinkedArrayQueue<E>	An MPSC array queue which starts at initialCapacity and grows to maxCapacity in linked chunks of the initial size.
CircularArrayOffsetCalculator
ConcurrentCircularArrayQueue<E>	Common functionality for array backed queues.
ConcurrentSequencedCircularArrayQueue<E>
IndexedQueueSizeUtil
MessagePassingQueueUtil
MpmcArrayQueue<E>	A Multi-Producer-Multi-Consumer queue based on a ConcurrentCircularArrayQueue.
MpscArrayQueue<E>	A Multi-Producer-Single-Consumer queue based on a ConcurrentCircularArrayQueue.
MpscChunkedArrayQueue<E>	An MPSC array queue which starts at initialCapacity and grows to maxCapacity in linked chunks of the initial size.
MpscCompoundQueue<E>
MpscGrowableArrayQueue<E>	An MPSC array queue which starts at initialCapacity and grows to maxCapacity in linked chunks of the initial size.
MpscLinkedQueue<E>	This is a direct Java port of the MPSC algorithm as presented on 1024 Cores by D.
MpscLinkedQueue7<E>
MpscLinkedQueue8<E>
MpscUnboundedArrayQueue<E>	An MPSC array queue which starts at initialCapacity and grows to maxCapacity in linked chunks of the initial size.
PaddedCircularArrayOffsetCalculator
QueueFactory	The queue factory produces Queue instances based on a best fit to the ConcurrentQueueSpec.
SpmcArrayQueue<E>
SpscArrayQueue<E>	A Single-Producer-Single-Consumer queue backed by a pre-allocated buffer.
SpscChunkedArrayQueue<E>
SpscGrowableArrayQueue<E>
SpscLinkedQueue<E>	This is a weakened version of the MPSC algorithm as presented on 1024 Cores by D.
SpscUnboundedArrayQueue<E>