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

All Methods Instance Methods Abstract Methods Default Methods
`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.
`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