com.devexperts.util

Class LockFreePool<E>

java.lang.Object

com.devexperts.util.LockFreePool<E>

Type Parameters:

E - type of elements kept in this pool.

public class LockFreePool<E>
extends Object

A collection designed for pooling elements so that they can be reused later. This class is primarily designed for pooling of very, very large objects that occupy a lot of memory and are extremely expensive to create, to make sure that as few as possible of those objects are allocated and are kept in the pool.

The LockFreePool is a fixed-capacity (or "bounded") stack as it orders elements in a LIFO (last-in-first-out) manner. This class is a thread-safe and provides lock-free access.

If you need a pool of moderately-sized objects that may be needed so often, as to raise concern about contention on this LockFreePool implementation and memory locality concerns on object reuse, then use ThreadLocalPool class and keeps an additional per-thread pool of objects.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_CAPACITY Maximal supported pool capacity.

Constructor Summary

Constructors

Constructor and Description
LockFreePool(int poolCapacity) Creates a LockFreePool with the specified (fixed) capacity.
LockFreePool(String poolName, int defaultPoolCapacity) A convenience constructor that creates a LockFreePool with a the specified default capacity, which can be overriden by a JVM system property.

Method Summary

Modifier and Type	Method and Description
boolean	offer(E o) Inserts the specified element into this pool, if possible.
E	poll() Retrieves and removes the element from this pool, or null if this pool is empty.
int	size() Returns the number of elements in this pool.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_CAPACITY

public static final int MAX_CAPACITY

Maximal supported pool capacity.

See Also:

Constant Field Values

Constructor Detail

LockFreePool

public LockFreePool(int poolCapacity)

Creates a LockFreePool with the specified (fixed) capacity. Using a fixed capacity in production code is a bad practise. Use a convenience constructor LockFreePool(poolName, defaultCapacity) that enables an override of pool's default capacity via JVM system property if needed.

Parameters:

poolCapacity - the capacity of this pool.

Throws:

IllegalArgumentException - if pool capacity is less than 1 or greater than MAX_CAPACITY.

LockFreePool

public LockFreePool(String poolName,
                    int defaultPoolCapacity)

A convenience constructor that creates a LockFreePool with a the specified default capacity, which can be overriden by a JVM system property. The corresponding JVM property name is poolName + ".poolCapacity".

Parameters:

poolName - the base name of the pool.

defaultPoolCapacity - the default capacity of this pool.

Throws:

IllegalArgumentException - if pool capacity is less than 1 or greater than MAX_CAPACITY.

Method Detail

size

public int size()

Returns the number of elements in this pool.

Returns:

the number of elements in this pool.

poll

public E poll()

Retrieves and removes the element from this pool, or null if this pool is empty.

Returns:

the element from this pool, or null if this pool is empty.

offer

public boolean offer(E o)

Inserts the specified element into this pool, if possible.

Parameters:

o - the element to insert.

Returns:

true if element was inserted into this pool, else false.

Throws:

NullPointerException - if element is null.

IllegalStateException - if element is already in the pool (best effort check only).