Package com.fasterxml.jackson.core.util

Interface RecyclerPool<P extends RecyclerPool.WithPool<P>>

Type Parameters:

P - Type of Objects pool recycles

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

JsonRecyclerPools.BoundedPool, JsonRecyclerPools.ConcurrentDequePool, JsonRecyclerPools.LockFreePool, JsonRecyclerPools.NonRecyclingPool, JsonRecyclerPools.ThreadLocalPool, RecyclerPool.BoundedPoolBase, RecyclerPool.ConcurrentDequePoolBase, RecyclerPool.LockFreePoolBase, RecyclerPool.NonRecyclingPoolBase, RecyclerPool.StatefulImplBase, RecyclerPool.ThreadLocalPoolBase

public interface RecyclerPool<P extends RecyclerPool.WithPool<P>>
extends java.io.Serializable

API for object pools that control creation and possible reuse of objects that are costly to create (often things like encoding/decoding buffers).

Also contains partial (base) implementations for pools that use different strategies on retaining objects for reuse. Following implementations are included:

• RecyclerPool.NonRecyclingPoolBase which does not retain or recycle anything and will always simply construct and return new instance when acquireBufferRecycler is called
• RecyclerPool.ThreadLocalPoolBase which uses ThreadLocal to retain at most 1 object per Thread.
• RecyclerPool.BoundedPoolBase is "bounded pool" and retains at most N objects (default value being RecyclerPool.BoundedPoolBase.DEFAULT_CAPACITY) at any given time.
• Two implementations -- RecyclerPool.ConcurrentDequePoolBase, RecyclerPool.LockFreePoolBase -- are "unbounded" and retain any number of objects released: in practice it is at most the highest number of concurrently used BufferRecyclers.

Default implementations are also included as nested classes.

Since:

2.16

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	RecyclerPool.BoundedPoolBase<P extends RecyclerPool.WithPool<P>>	RecyclerPool implementation that uses a bounded queue (ArrayBlockingQueue for recycling instances.
static class	RecyclerPool.ConcurrentDequePoolBase<P extends RecyclerPool.WithPool<P>>	RecyclerPool implementation that uses ConcurrentLinkedDeque for recycling instances.
static class	RecyclerPool.LockFreePoolBase<P extends RecyclerPool.WithPool<P>>	RecyclerPool implementation that uses a lock free linked list for recycling instances.
static class	RecyclerPool.NonRecyclingPoolBase<P extends RecyclerPool.WithPool<P>>	RecyclerPool implementation that does not use any pool but simply creates new instances when necessary.
static class	RecyclerPool.StatefulImplBase<P extends RecyclerPool.WithPool<P>>	Intermediate base class for instances that are stateful and require special handling with respect to JDK serialization, to retain "global" reference distinct from non-shared ones.
static class	RecyclerPool.ThreadLocalPoolBase<P extends RecyclerPool.WithPool<P>>	Default RecyclerPool implementation that uses ThreadLocal for recycling instances.
static interface	RecyclerPool.WithPool<P extends RecyclerPool.WithPool<P>>	Simple add-on interface that poolable entities must implement.

Method Summary

Modifier and Type	Method	Description
default P	acquireAndLinkPooled()	Method called to acquire a Pooled value from this pool AND make sure it is linked back to this RecyclerPool as necessary for it to be released (see releasePooled(P)) later after usage ends.
P	acquirePooled()	Method for sub-classes to implement for actual acquire logic; called by acquireAndLinkPooled().
default boolean	clear()	Optional method that may allow dropping of all pooled Objects; mostly useful for unbounded pool implementations that may retain significant memory and that may then be cleared regularly.
default int	pooledCount()	Diagnostic method for obtaining an estimate of number of pooled items this pool contains, available for recycling.
void	releasePooled(P pooled)	Method that should be called when previously acquired (see acquireAndLinkPooled()) pooled value that is no longer needed; this lets pool to take ownership for possible reuse.

Method Detail

acquireAndLinkPooled

default P acquireAndLinkPooled()

Method called to acquire a Pooled value from this pool AND make sure it is linked back to this RecyclerPool as necessary for it to be released (see releasePooled(P)) later after usage ends. Actual acquisition is done by a call to acquirePooled().

Default implementation calls acquirePooled() followed by a call to RecyclerPool.WithPool.withPool(com.fasterxml.jackson.core.util.RecyclerPool<P>).

Returns:

Pooled instance for caller to use; caller expected to call releasePooled(P) after it is done using instance.

acquirePooled

P acquirePooled()

Method for sub-classes to implement for actual acquire logic; called by acquireAndLinkPooled().

Returns:

Instance acquired (pooled or just constructed)

releasePooled

void releasePooled(P pooled)

Method that should be called when previously acquired (see acquireAndLinkPooled()) pooled value that is no longer needed; this lets pool to take ownership for possible reuse.

Parameters:

pooled - Pooled instance to release back to pool

clear

default boolean clear()

Optional method that may allow dropping of all pooled Objects; mostly useful for unbounded pool implementations that may retain significant memory and that may then be cleared regularly.

Returns:

true If pool supports operation and dropped all pooled Objects; false otherwise.

Since:

2.17

pooledCount

default int pooledCount()

Diagnostic method for obtaining an estimate of number of pooled items this pool contains, available for recycling. Note that in addition to this information possibly not being available (denoted by return value of -1) even when available this may be just an approximation.

Default method implementation simply returns -1 and is meant to be overridden by concrete sub-classes.

Returns:

Number of pooled entries available from this pool, if available; -1 if not.

Since:

2.18