com.github.benmanes.caffeine

Class ConcurrentLinkedStack<E>

java.lang.Object

java.util.AbstractCollection<E>

com.github.benmanes.caffeine.ConcurrentLinkedStack<E>

Type Parameters:

E - the type of elements held in this collection

All Implemented Interfaces:

Serializable, Iterable<E>, Collection<E>

@Beta
 @ThreadSafe
public final class ConcurrentLinkedStack<E>
extends AbstractCollection<E>
implements Serializable

An unbounded thread-safe stack based on linked nodes. This stack orders elements LIFO (last-in-first-out). The top of the stack is that element that has been on the stack the shortest time. New elements are inserted at and retrieved from the top of the stack. A ConcurrentLinkedStack is an appropriate choice when many threads will exchange elements through shared access to a common collection. Like most other concurrent collection implementations, this class does not permit the use of null elements.

This implementation employs elimination and combination to transfer elements between threads that are pushing and popping concurrently. This technique avoids contention on the stack by attempting to cancel opposing operations and merge additive operations if an immediate update to the stack is not successful. When a pair of additive operations 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 stack.

Iterators are weakly consistent, returning elements reflecting the state of the stack 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 stack since the creation of the iterator will be returned exactly once.

Beware that, unlike in most collections, the size method is NOT a constant-time operation. Because of the asynchronous nature of these stacks, 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.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
boolean	add(E e)
boolean	addAll(Collection<? extends E> c)
Queue<E>	asLifoQueue() Returns a view as a last-in-first-out (LIFO) Queue.
void	clear()
boolean	contains(Object o)
boolean	isEmpty()
Iterator<E>	iterator()
static <E> ConcurrentLinkedStack<E>	linearizable() Creates a stack with a linearizable backoff strategy.
static <E> ConcurrentLinkedStack<E>	optimistic() Creates a stack with an optimistic backoff strategy.
E	peek() Retrieves, but does not remove, the top of the stack (in other words, the last element pushed), or returns null if this stack is empty.
E	pop() Removes and returns the top element or returns null if this stack is empty.
void	push(E e) Pushes an element onto the stack (in other words, adds an element at the top of this stack).
boolean	remove(Object o)
int	size() Returns the number of elements in this stack.

Methods inherited from class java.util.AbstractCollection

containsAll, 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

equals, hashCode, parallelStream, removeIf, spliterator, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

optimistic

public static <E> ConcurrentLinkedStack<E> optimistic()

Creates a stack 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 LIFO order due to the backoff strategy trying to compensate for stack contention.

Type Parameters:

E - the type of elements held in this collection

Returns:

a new stack where producers complete their operation immediately if combined with another thread's

linearizable

public static <E> ConcurrentLinkedStack<E> linearizable()

Creates a stack 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 stack where producers wait for a completion signal after combining its addition with another thread's

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Collection<E>

Overrides:

isEmpty in class AbstractCollection<E>

size

public int size()

Returns the number of elements in this stack.

Beware that, unlike in most collections, this method is NOT a constant-time operation. Because of the asynchronous nature of these stacks, determining the current number of elements requires an O(n) traversal. Additionally, if elements are added or removed during execution of this method, the returned result may be inaccurate. Thus, this method is typically not very useful in concurrent applications.

Specified by:

size in interface Collection<E>

Specified by:

size in class AbstractCollection<E>

Returns:

the number of elements in this stack

clear

public void clear()

Specified by:

clear in interface Collection<E>

Overrides:

clear in class AbstractCollection<E>

contains

public boolean contains(@Nullable
                        Object o)

Specified by:

contains in interface Collection<E>

Overrides:

contains in class AbstractCollection<E>

peek

@Nullable
public E peek()

Retrieves, but does not remove, the top of the stack (in other words, the last element pushed), or returns null if this stack is empty.

Returns:

the top of the stack or null if this stack is empty

pop

@Nullable
public E pop()

Removes and returns the top element or returns null if this stack is empty.

Returns:

the top of this stack, or null if this stack is empty

push

public void push(@Nonnull
                 E e)

Pushes an element onto the stack (in other words, adds an element at the top of this stack).

Parameters:

e - the element to push

add

public boolean add(E e)

Specified by:

add in interface Collection<E>

Overrides:

add in class AbstractCollection<E>

addAll

public boolean addAll(Collection<? extends E> c)

Specified by:

addAll in interface Collection<E>

Overrides:

addAll in class AbstractCollection<E>

remove

public boolean remove(Object o)

Specified by:

remove in interface Collection<E>

Overrides:

remove in class AbstractCollection<E>

iterator

public Iterator<E> iterator()

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in class AbstractCollection<E>

asLifoQueue

public Queue<E> asLifoQueue()

Returns a view as a last-in-first-out (LIFO) Queue. Method add is mapped to push, remove is mapped to pop and so on. This view can be useful when you would like to use a method requiring a Queue but you need LIFO ordering.

Returns:

the queue