com.devexperts.util

Class ThreadLocalPool<E>

java.lang.Object

com.devexperts.util.ThreadLocalPool<E>

Type Parameters:

E - type of elements kept in this pool.

public class ThreadLocalPool<E>
extends Object

Encapsulates a small thread-local pool of objects and a global LockFreePool. This class is primarily designed for pooling of moderately-sized objects that may be needed so often, as to raise concern about contention in LockFreePool implementation and memory locality concerns on object reuse.

This class is a thread-safe.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_THREAD_LOCAL_CAPACITY Maximal supported thread local capacity.

Constructor Summary

Constructors

Constructor and Description
ThreadLocalPool(int threadLocalCapacity, int poolCapacity) Creates a ThreadLocalPool with the specified (fixed) capacities.
ThreadLocalPool(String poolName, int defaultThreadLocalCapacity, int defaultPoolCapacity) A convenience constructor that creates a ThreadLocalPool with a the specified default capacities, which can be overriden by a JVM system properties.

Method Summary

Modifier and Type	Method and Description
boolean	offer(E o) Inserts the specified element into this pool.
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 that are available to the current thread.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_THREAD_LOCAL_CAPACITY

public static final int MAX_THREAD_LOCAL_CAPACITY

Maximal supported thread local capacity.

See Also:

Constant Field Values

Constructor Detail

ThreadLocalPool

public ThreadLocalPool(int threadLocalCapacity,
                       int poolCapacity)

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

Parameters:

threadLocalCapacity - the capacity of thread-local pool, e.g. how many objects are pooled per thread.

poolCapacity - the capacity of the global LockFreePool, e.g. how many objects are pooled globally in addition to local ones.

Throws:

IllegalArgumentException - if thread local capacity is less than 1 or greater than MAX_THREAD_LOCAL_CAPACITY or pool capacity is less than 1 or greater than LockFreePool.MAX_CAPACITY.

ThreadLocalPool

public ThreadLocalPool(String poolName,
                       int defaultThreadLocalCapacity,
                       int defaultPoolCapacity)

A convenience constructor that creates a ThreadLocalPool with a the specified default capacities, which can be overriden by a JVM system properties. The corresponding JVM property name for thread local capacity is poolName + ".threadLocalCapacity", and for the global LockFreePool is poolName + ".poolCapacity".

Parameters:

poolName - the base name of the pool.

defaultThreadLocalCapacity - the default capacity of thread-local pool, e.g. how many objects are pooled per thread.

defaultPoolCapacity - the default capacity of the global LockFreePool, e.g. how many objects are pooled globally in addition to local ones.

Throws:

IllegalArgumentException - if thread local capacity is less than 1 or greater than MAX_THREAD_LOCAL_CAPACITY or pool capacity is less than 1 or greater than LockFreePool.MAX_CAPACITY.

Method Detail

size

public int size()

Returns the number of elements in this pool that are available to the current thread.

Returns:

the number of elements in this pool that are available to the current thread.

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. This method always stores the element into the thread local pool, to make sure that thread local pool contains the most "fresh" instance. If thread local pool has no capacity, then its oldest element is moved into the global LockFreePool.

Parameters:

o - the element to insert.

Returns:

Always returns true.

Throws:

NullPointerException - if element is null.

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