Package io.lettuce.core.support

Class BoundedAsyncPool<T>

java.lang.Object

io.lettuce.core.support.BasePool

io.lettuce.core.support.BoundedAsyncPool<T>

All Implemented Interfaces:

AsyncCloseable, AsyncCloseable, AsyncPool<T>, Closeable, AutoCloseable

public class BoundedAsyncPool<T>
extends BasePool
implements AsyncPool<T>

Bounded asynchronous object pool. This object pool allows pre-warming with idle objects upon construction. The pool is stateful and requires cleanup once it's no longer in use.

Object pool bounds are maintained on a best-effort basis as bounds are maintained upon object request whereas the actual object creation might finish at a later time. You might see temporarily slight differences in object usage vs. pool count due to asynchronous processing vs. protecting the pool from exceed its bounds.

Since:

5.1

Author:

Mark Paluch

See Also:

BoundedPoolConfig, AsyncObjectFactory

Field Summary

Fields

Modifier and Type	Field	Description
static CompletableFuture<Object>	COMPLETED_FUTURE

Constructor Summary

Constructors

Constructor	Description
BoundedAsyncPool(AsyncObjectFactory<T> factory, BoundedPoolConfig poolConfig)	Create a new BoundedAsyncPool given BasePoolConfig and AsyncObjectFactory.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<T>	acquire()	Acquire an object from this AsyncPool.
void	clear()	Clear the pool.
CompletableFuture<Void>	clearAsync()	Clear the pool.
void	close()
CompletableFuture<Void>	closeAsync()	Requests to close this object and releases any system resources associated with it.
static <T> CompletionStage<BoundedAsyncPool<T>>	create(AsyncObjectFactory<T> factory, BoundedPoolConfig poolConfig)	Create and initialize BoundedAsyncPool asynchronously.
int	getCreationInProgress()
int	getIdle()
int	getMaxIdle()	Returns the cap on the number of "idle" instances in the pool.
int	getMaxTotal()	Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time.
int	getMinIdle()	Returns the target for the minimum number of idle objects to maintain in the pool.
int	getObjectCount()
CompletableFuture<Void>	release(T object)	Release an object back to this AsyncPool.

Methods inherited from class io.lettuce.core.support.BasePool

isTestOnAcquire, isTestOnCreate, isTestOnRelease

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPLETED_FUTURE

public static final CompletableFuture<Object> COMPLETED_FUTURE

Constructor Detail

BoundedAsyncPool

public BoundedAsyncPool(AsyncObjectFactory<T> factory,
                        BoundedPoolConfig poolConfig)

Create a new BoundedAsyncPool given BasePoolConfig and AsyncObjectFactory. The factory creates idle objects upon construction and requires termination once it's no longer in use.

Please note that pre-initialization cannot be awaited when using this constructor. Please use create(AsyncObjectFactory, BoundedPoolConfig) instead.

Parameters:

factory - must not be null.

poolConfig - must not be null.

Method Detail

create

public static <T> CompletionStage<BoundedAsyncPool<T>> create(AsyncObjectFactory<T> factory,
                                                              BoundedPoolConfig poolConfig)

Create and initialize BoundedAsyncPool asynchronously.

Type Parameters:

T - object type that is managed by the pool.

Parameters:

factory - must not be null.

poolConfig - must not be null.

Returns:

a CompletionStage that completes with the BoundedAsyncPool when created and pre-initialized successfully. Completes exceptionally if the pool initialization failed.

Since:

5.3.3

acquire

public CompletableFuture<T> acquire()

Description copied from interface: AsyncPool

Acquire an object from this AsyncPool. The returned CompletableFuture is notified once the acquire is successful and failed otherwise. Behavior upon acquiring objects from an exhausted pool depends on the actual pool implementation whether requests are rejected immediately (exceptional completion with NoSuchElementException) or delayed after exceeding a particular timeout ( TimeoutException). It's required that an acquired object is always released to the pool again once the object is no longer in use..

Specified by:

acquire in interface AsyncPool<T>

release

public CompletableFuture<Void> release(T object)

Description copied from interface: AsyncPool

Release an object back to this AsyncPool. The returned CompletableFuture is notified once the release is successful and failed otherwise. When failed the object will automatically disposed.

Specified by:

release in interface AsyncPool<T>

Parameters:

object - the object to be released. The object must have been acquired from this pool.

clear

public void clear()

Description copied from interface: AsyncPool

Clear the pool.

Specified by:

clear in interface AsyncPool<T>

clearAsync

public CompletableFuture<Void> clearAsync()

Description copied from interface: AsyncPool

Clear the pool.

Specified by:

clearAsync in interface AsyncPool<T>

close

public void close()

Specified by:

close in interface AsyncPool<T>

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

closeAsync

public CompletableFuture<Void> closeAsync()

Description copied from interface: AsyncCloseable

Requests to close this object and releases any system resources associated with it. If the object is already closed then invoking this method has no effect.

Calls to this method return a CompletableFuture that is notified with the outcome of the close request.

Specified by:

closeAsync in interface AsyncCloseable

Specified by:

closeAsync in interface AsyncCloseable

Specified by:

closeAsync in interface AsyncPool<T>

getMaxTotal

public int getMaxTotal()

Returns the maximum number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time. When negative, there is no limit to the number of objects that can be managed by the pool at one time.

Returns:

the cap on the total number of object instances managed by the pool. Unlimited max objects are capped at Integer#MAX_VALUE.

See Also:

BoundedPoolConfig.getMaxTotal()

getMaxIdle

public int getMaxIdle()

Returns the cap on the number of "idle" instances in the pool. If maxIdle is set too low on heavily loaded systems it is possible you will see objects being destroyed and almost immediately new objects being created. This is a result of the active threads momentarily returning objects faster than they are requesting them, causing the number of idle objects to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point.

Returns:

the maximum number of "idle" instances that can be held in the pool. Unlimited idle objects are capped at Integer#MAX_VALUE.

See Also:

BoundedPoolConfig.getMaxIdle()

getMinIdle

public int getMinIdle()

Returns the target for the minimum number of idle objects to maintain in the pool. If this is the case, an attempt is made to ensure that the pool has the required minimum number of instances during idle object eviction runs.

If the configured value of minIdle is greater than the configured value for maxIdle then the value of maxIdle will be used instead.

Returns:

The minimum number of objects.

See Also:

BoundedPoolConfig.getMinIdle()

getIdle

public int getIdle()

getObjectCount

public int getObjectCount()

getCreationInProgress

public int getCreationInProgress()