public interface Pool<POOLABLE> extends Disposable
Disposable.Composite, Disposable.Swap
Modifier and Type | Method and 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()
|
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. |
isDisposed
Mono<Integer> warmup()
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).
Mono
that triggers resource warmup and emits the number of warmed up resourcesPoolBuilder.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.Mono<PooledRef<POOLABLE>> acquire()
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).
Mono
, each subscription to which represents an individual act of acquiring a pooled object and
manually managing its lifecycle from there onwithPoolable(Function)
Mono<PooledRef<POOLABLE>> acquire(Duration timeout)
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).
Mono
, each subscription to which represents an individual act of acquiring a pooled object and
manually managing its lifecycle from there onwithPoolable(Function)
default <V> Flux<V> withPoolable(Function<POOLABLE,Publisher<V>> scopeFunction)
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
.
scopeFunction
- the Function
to apply to the Mono
delivering the POOLABLE to instantiate and
trigger a processing pipeline around itFlux
, each subscription to which represents an individual act of acquiring a pooled object,
processing it as declared in scopeFunction
and automatically releasing itacquire()
PoolConfig<POOLABLE> config()
configuration
.PoolConfig
default void dispose()
RuntimeException
PoolBuilder
disposeLater()
and Mono.block()
.
By default this is implemented as .disposeLater().subscribe()
. As a result
failures during release could be swallowed.
dispose
in interface Disposable
Mono<Void> disposeLater()
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.