org.jctools.queues

Class SpscLinkedQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

org.jctools.queues.SpscLinkedQueue<E>

Type Parameters:

E -

All Implemented Interfaces:

Iterable<E>, Collection<E>, Queue<E>

public final class SpscLinkedQueue<E>
extends AbstractQueue<E>

This is a weakened version of the MPSC algorithm as presented on 1024 Cores by D. Vyukov. The original has been adapted to Java and it's quirks with regards to memory model and layout:

1. Use inheritance to ensure no false sharing occurs between producer/consumer node reference fields.
2. As this is an SPSC we have no need for XCHG, an ordered store is enough.

The queue is initialized with a stub node which is set to both the producer and consumer node references. From this point follow the notes on offer/poll.

Author:

nitsanw

Field Summary

Fields

Modifier and Type	Field and Description
protected static long	C_NODE_OFFSET
protected org.jctools.queues.LinkedQueueNode<E>	consumerNode
protected static long	P_NODE_OFFSET
protected org.jctools.queues.LinkedQueueNode<E>	producerNode

Constructor Summary

Constructors

Constructor and Description
SpscLinkedQueue()

Method Summary

Modifier and Type	Method and Description
boolean	isEmpty()
Iterator<E>	iterator()
protected org.jctools.queues.LinkedQueueNode<E>	lpConsumerNode()
protected org.jctools.queues.LinkedQueueNode<E>	lpProducerNode()
protected org.jctools.queues.LinkedQueueNode<E>	lvConsumerNode()
protected org.jctools.queues.LinkedQueueNode<E>	lvProducerNode()
boolean	offer(E nextValue) IMPLEMENTATION NOTES: Offer is allowed from a SINGLE thread. Offer allocates a new node (holding the offered value) and: Sets that node as the producerNode.next Sets the new node as the producerNode From this follows that producerNode.next is always null and for all other nodes node.next is not null.
E	peek()
E	poll() IMPLEMENTATION NOTES: Poll is allowed from a SINGLE thread. Poll reads the next node from the consumerNode and: If it is null, the queue is empty.
int	size()
protected void	spConsumerNode(org.jctools.queues.LinkedQueueNode<E> node)
protected void	spProducerNode(org.jctools.queues.LinkedQueueNode<E> node)

Methods inherited from class java.util.AbstractQueue

add, addAll, clear, element, remove

Methods inherited from class java.util.AbstractCollection

contains, containsAll, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

contains, containsAll, equals, hashCode, parallelStream, remove, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable

forEach

Field Detail

C_NODE_OFFSET

protected static final long C_NODE_OFFSET

consumerNode

protected org.jctools.queues.LinkedQueueNode<E> consumerNode

P_NODE_OFFSET

protected static final long P_NODE_OFFSET

producerNode

protected org.jctools.queues.LinkedQueueNode<E> producerNode

Constructor Detail

SpscLinkedQueue

public SpscLinkedQueue()

Method Detail

offer

public boolean offer(E nextValue)

IMPLEMENTATION NOTES:
Offer is allowed from a SINGLE thread.
Offer allocates a new node (holding the offered value) and:

1. Sets that node as the producerNode.next
2. Sets the new node as the producerNode

From this follows that producerNode.next is always null and for all other nodes node.next is not null.

See Also:

MessagePassingQueue.offer(Object), Queue.offer(java.lang.Object)

poll

public E poll()

IMPLEMENTATION NOTES:
Poll is allowed from a SINGLE thread.
Poll reads the next node from the consumerNode and:

1. If it is null, the queue is empty.
2. If it is not null set it as the consumer node and return it's now evacuated value.

This means the consumerNode.value is always null, which is also the starting point for the queue. Because null values are not allowed to be offered this is the only node with it's value set to null at any one time.

peek

public E peek()

iterator

public final Iterator<E> iterator()

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in class AbstractCollection<E>

size

public final int size()

IMPLEMENTATION NOTES:
This is an O(n) operation as we run through all the nodes and count them.

Specified by:

size in interface Collection<E>

Specified by:

size in class AbstractCollection<E>

See Also:

Collection.size()

isEmpty

public final boolean isEmpty()

IMPLEMENTATION NOTES:
Queue is empty when producerNode is the same as consumerNode. An alternative implementation would be to observe the producerNode.value is null, which also means an empty queue because only the consumerNode.value is allowed to be null.

Specified by:

isEmpty in interface Collection<E>

Overrides:

isEmpty in class AbstractCollection<E>

See Also:

MessagePassingQueue.isEmpty()

spConsumerNode

protected final void spConsumerNode(org.jctools.queues.LinkedQueueNode<E> node)

lvConsumerNode

protected final org.jctools.queues.LinkedQueueNode<E> lvConsumerNode()

lpConsumerNode

protected final org.jctools.queues.LinkedQueueNode<E> lpConsumerNode()

spProducerNode

protected final void spProducerNode(org.jctools.queues.LinkedQueueNode<E> node)

lvProducerNode

protected final org.jctools.queues.LinkedQueueNode<E> lvProducerNode()

lpProducerNode

protected final org.jctools.queues.LinkedQueueNode<E> lpProducerNode()