Package reactor.pool.decorators

Class GracefulShutdownInstrumentedPool<T>

java.lang.Object
reactor.pool.decorators.GracefulShutdownInstrumentedPool<T>
All Implemented Interfaces:
Disposable, InstrumentedPool<T>, Pool<T>
public final class GracefulShutdownInstrumentedPool<T> extends Object implements InstrumentedPool<T>
A decorating InstrumentedPool that adds the capacity to gracefully shut down the pool. Apply to any InstrumentedPool via the InstrumentedPoolDecorators.gracefulShutdown(InstrumentedPool) factory method.

Adds the getOriginalPool(), disposeGracefully(Duration), isGracefullyShuttingDown() and isInGracePeriod() methods.

Author:
Simon Baslé

  • Method Details

    • getOriginalPool

      public InstrumentedPool<T> getOriginalPool()
      Return the original pool. Note that in order for this decorator to work correctly, the original pool MUST NOT be used in conjunction with the decorated pool, so use this method carefully.
      Returns:
      the original decorated InstrumentedPool

    • acquire

      public Mono<PooledRef<T>> acquire()
      Description copied from interface: Pool
      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 Pool.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).

      Specified by:
      acquire in interface Pool<T>
      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

      public Mono<PooledRef<T>> acquire(Duration timeout)
      Description copied from interface: Pool
      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 Pool.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).

      Specified by:
      acquire in interface Pool<T>
      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:

    • disposeGracefully

      public Mono<Void> disposeGracefully(Duration gracefulTimeout)
      Trigger a "graceful shutdown" of the pool, with a grace period timeout. From there on, calls to Pool.acquire() and Pool.acquire(Duration) will fail fast with a PoolShutdownException. However, for the provided Duration, pending acquires will get a chance to be served.

      If the wrapper detects that all pending acquires are either released or invalidated, the returned Mono will complete successfully. It will do so after having internally called and waited for the original pool's Pool.disposeLater() method, effectively shutting down the pool for good.

      If the timeout triggers before that, the returned Mono will also trigger the Pool.disposeLater() method, but will terminate by emitting a TimeoutException. Since it means that at that point some pending acquire are still registered, these are terminated with a PoolShutdownException by the disposeLater() method.

      Note that the rejection of new acquires and the grace timer start immediately, irrespective of subscription to the returned Mono. Subsequent calls return the same Mono, effectively getting notifications from the first graceful shutdown call and ignoring subsequently provided timeouts.

      The timeout runs on the original pool's PoolConfig.evictInBackgroundScheduler() if it set (and provided the pool correctly exposes its configuration via Pool.config()). Otherwise it uses the parallel Scheduler as a fallback.

      Parameters:
      gracefulTimeout - the maximum Duration for graceful shutdown before full shutdown is forced (resolution: ms)
      Returns:
      a Mono representing the current graceful shutdown of the pool
      See Also:

    • isGracefullyShuttingDown

      public boolean isGracefullyShuttingDown()
      Check if the disposeGracefully(Duration) has been invoked.
      Returns:
      true if the pool is in the process of shutting down gracefully, or has already done so

    • isInGracePeriod

      public boolean isInGracePeriod()
      Check if the disposeGracefully(Duration) has been invoked but there are still pending acquire and the grace period hasn't timed out.

      If isGracefullyShuttingDown() returns true but this method returns false, it means that the pool is now at least in the process of shutting down completely via disposeLater() (or has already done so).

      Returns:
      true if the graceful shutdown is still within the grace period, false otherwise

    • metrics

      public InstrumentedPool.PoolMetrics metrics()
      Specified by:
      metrics in interface InstrumentedPool<T>
      Returns:
      a InstrumentedPool.PoolMetrics object to be used to get live gauges about the Pool

    • config

      public PoolConfig<T> config()
      Description copied from interface: Pool
      Return the pool's configuration.
      Specified by:
      config in interface Pool<T>
      Returns:
      the PoolConfig

    • warmup

      public Mono<Integer> warmup()
      Description copied from interface: Pool
      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).

      Specified by:
      warmup in interface Pool<T>
      Returns:
      a cold Mono that triggers resource warmup and emits the number of warmed up resources

    • disposeLater

      public Mono<Void> disposeLater()
      Description copied from interface: Pool
      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, Pool.dispose().

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

      Specified by:
      disposeLater in interface Pool<T>
      Returns:
      a Mono triggering the shutdown of the pool once subscribed.

    • isDisposed

      public boolean isDisposed()
      Specified by:
      isDisposed in interface Disposable