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