Package com.fasterxml.jackson.core.util

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

Type Parameters:
  `P` - Type of Objects pool recycles

All Superinterfaces:
  `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 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 `BufferRecycler`s.

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()`.
`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 Details

### 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