Package reactor.pool

Interface Pool<POOLABLE>

All Superinterfaces:
Disposable
All Known Subinterfaces:
InstrumentedPool<POOLABLE>
All Known Implementing Classes:
GracefulShutdownInstrumentedPool, SimpleDequePool
public interface Pool<POOLABLE> extends Disposable
A reactive pool of objects.
Author:
Simon Baslé

  • Nested Class Summary

    Nested classes/interfaces inherited from interface reactor.core.Disposable

    Disposable.Composite, Disposable.Swap

  • Method Summary

    Modifier and Type
    Method
    Description
    Mono<PooledRef<POOLABLE>>
    acquire()
    Manually acquire a POOLABLE from the pool upon subscription and become responsible for its release.
    Mono<PooledRef<POOLABLE>>
    acquire(Duration timeout)
    Manually acquire a POOLABLE from the pool upon subscription and become responsible for its release.
    PoolConfig<POOLABLE>
    config()
    Return the pool's configuration.
    default void
    dispose()
    Shutdown the pool by: notifying every acquire still pending that the pool has been shut down, via a RuntimeException releasing each pooled resource, according to the release handler defined in the PoolBuilder This imperative style method returns once every release handler has been started in step 2, but doesn't necessarily block until full completion of said releases.
    Mono<Void>
    disposeLater()
    Returns a Mono that represents a lazy asynchronous shutdown of this Pool.
    Mono<Integer>
    warmup()
    Warms up the Pool, if needed.
    default <V> Flux<V>
    withPoolable(Function<POOLABLE,Publisher<V>> scopeFunction)
    Acquire a POOLABLE object from the pool upon subscription and declaratively use it, automatically releasing the object back to the pool once the derived usage pipeline terminates or is cancelled.

    Methods inherited from interface reactor.core.Disposable

    isDisposed

  • Method Details

    • warmup

      Mono<Integer> warmup()
      Warms up the Pool, if needed. This typically instructs the pool to check for a minimum size and allocate necessary objects when the minimum is not reached. The resulting Mono emits the number of extra resources it created as a result of the allocation minimum.

      Note that no work nor allocation is performed until the Mono is subscribed to.

      Implementations MAY include more behavior, but there is no restriction on the way this method is called by users (it should be possible to call it at any time, as many times as needed or not at all).

      Returns:
      a cold Mono that triggers resource warmup and emits the number of warmed up resources
      API Note:
      this API is intended to easily reach the minimum allocated size (see PoolBuilder.sizeBetween(int, int)) without paying that cost on the first acquire(). However, implementors should also consider creating the extra resources needed to honor that minimum during the acquire, as one cannot rely on the user calling warmup() consistently.

    • acquire

      Mono<PooledRef<POOLABLE>> acquire()
      Manually acquire a POOLABLE from the pool upon subscription and become responsible for its release. The object is wrapped in a PooledRef which can be used for manually releasing the object back to the pool or invalidating it. As a result, you MUST maintain a reference to it throughout the code that makes use of the underlying resource.

      This is typically the case when one needs to wrap the actual resource into a decorator version, where the reference to the PooledRef can be stored. On the other hand, if the resource and its usage directly expose reactive APIs, you might want to prefer to use withPoolable(Function).

      The resulting Mono emits the PooledRef as the POOLABLE becomes available. Cancelling the Subscription before the POOLABLE has been emitted will either avoid object acquisition entirely or will translate to a release of the POOLABLE. Once the resource is emitted though, it is the responsibility of the caller to release the poolable object via the PooledRef release methods when the resource is not used anymore (directly OR indirectly, eg. the results from multiple statements derived from a DB connection type of resource have all been processed).

      Returns:
      a Mono, each subscription to which represents an individual act of acquiring a pooled object and manually managing its lifecycle from there on
      See Also:

    • acquire

      Mono<PooledRef<POOLABLE>> acquire(Duration timeout)
      Manually acquire a POOLABLE from the pool upon subscription and become responsible for its release. The provided Duration acts as a timeout that only applies if the acquisition is added to the pending queue, i.e. there is no idle resource and no new resource can be created currently, so one needs to wait for a release before a resource can be delivered. For a timeout that covers both this pending case and the time it would take to allocate a new resource, simply apply the Mono.timeout(Duration) operator to the returned Mono. For a timeout that only applies to resource allocation, build the pool with the standard Mono.timeout(Duration) operator chained to the allocator.

      The object is wrapped in a PooledRef which can be used for manually releasing the object back to the pool or invalidating it. As a result, you MUST maintain a reference to it throughout the code that makes use of the underlying resource.

      This is typically the case when one needs to wrap the actual resource into a decorator version, where the reference to the PooledRef can be stored. On the other hand, if the resource and its usage directly expose reactive APIs, you might want to prefer to use withPoolable(Function).

      The resulting Mono emits the PooledRef as the POOLABLE becomes available. Cancelling the Subscription before the POOLABLE has been emitted will either avoid object acquisition entirely or will translate to a release of the POOLABLE. Once the resource is emitted though, it is the responsibility of the caller to release the poolable object via the PooledRef release methods when the resource is not used anymore (directly OR indirectly, eg. the results from multiple statements derived from a DB connection type of resource have all been processed).

      Returns:
      a Mono, each subscription to which represents an individual act of acquiring a pooled object and manually managing its lifecycle from there on
      See Also:

    • withPoolable

      default <V> Flux<V> withPoolable(Function<POOLABLE,Publisher<V>> scopeFunction)
      Acquire a POOLABLE object from the pool upon subscription and declaratively use it, automatically releasing the object back to the pool once the derived usage pipeline terminates or is cancelled. This acquire-use-and-release scope is represented by a user provided Function.

      This is typically useful when the resource (and its usage patterns) directly involve reactive APIs that can be composed within the Function scope.

      The Mono provided to the Function emits the POOLABLE as it becomes available. Cancelling the Subscription before the POOLABLE has been emitted will either avoid object acquisition entirely or will translate to a release of the POOLABLE.

      Parameters:
      scopeFunction - the Function to apply to the Mono delivering the POOLABLE to instantiate and trigger a processing pipeline around it
      Returns:
      a Flux, each subscription to which represents an individual act of acquiring a pooled object, processing it as declared in scopeFunction and automatically releasing it
      See Also:

    • config

      PoolConfig<POOLABLE> config()
      Return the pool's configuration.
      Returns:
      the PoolConfig

    • dispose

      default void dispose()
      Shutdown the pool by:
      • notifying every acquire still pending that the pool has been shut down, via a RuntimeException
      • releasing each pooled resource, according to the release handler defined in the PoolBuilder
      This imperative style method returns once every release handler has been started in step 2, but doesn't necessarily block until full completion of said releases. For a blocking alternative, use disposeLater() and Mono.block().

      By default this is implemented as .disposeLater().subscribe(). As a result failures during release could be swallowed.

      Specified by:
      dispose in interface Disposable

    • disposeLater

      Mono<Void> disposeLater()
      Returns a Mono that represents a lazy asynchronous shutdown of this Pool. Shutdown doesn't happen until the Mono is subscribed. Otherwise, it performs the same steps as in the imperative counterpart, dispose().

      If the pool has been already shut down, returns Mono.empty(). Completion of the Mono indicates completion of the shutdown process.

      Returns:
      a Mono triggering the shutdown of the pool once subscribed.