reactor.pool.introspection

Class SamplingAllocationStrategy

java.lang.Object

reactor.pool.introspection.SamplingAllocationStrategy

All Implemented Interfaces:

AllocationStrategy

public final class SamplingAllocationStrategy
extends Object
implements AllocationStrategy

An AllocationStrategy that delegates to an underlying AllocationStrategy and samples the getPermits(int) and returnPermits(int) methods.

Only a given percentage of calls are sampled, and these are stored as stacktraces in the sampling strategy. If a AllocationStrategy.returnPermits(int) call fails, a new IllegalArgumentException is thrown with a composite cause that represents all the sampled calls (see Exceptions.unwrapMultiple(Throwable)).

The two types of calls are sampled separately. The reservoir sampling algorithm is used to instantiate a sampling decision bitset over 100 slots, which are then applied to windows of 100 calls. Access to the delegate field is possible, as well as gettingSamplingRate/returningSamplingRate configuration fields and gettingSamples/returningSamples collections.

Author:

Simon Baslé

Field Summary

Fields

Modifier and Type	Field and Description
AllocationStrategy	delegate The delegate AllocationStrategy backing this sampling strategy.
LinkedList<Throwable>	gettingSamples The list of samples for getPermits(int) calls, as Throwable that trace back to the callers of the sampled calls.
double	gettingSamplingRate The configured sampling rate for getPermits(int) calls, as a double between 0d and 1d (percentage).
LinkedList<Throwable>	returningSamples The list of samples for returnPermits(int) calls, as Throwable that trace back to the callers of the sampled calls.
double	returningSamplingRate The configured sampling rate for returnPermits(int) calls, as a double between 0d and 1d (percentage).

Method Summary

Modifier and Type	Method and Description
int	estimatePermitCount() Best-effort peek at the state of the strategy which indicates roughly how many more resources can currently be allocated.
int	getPermits(int desired) Try to get the permission to allocate a desired positive number of new resources.
int	permitGranted()
int	permitMaximum()
int	permitMinimum() Return the minimum number of permits this strategy tries to maintain granted (reflecting a minimal size for the pool), or 0 for scale-to-zero.
void	returnPermits(int returned) Update the strategy to indicate that N resources were discarded from the Pool, potentially leaving space for N new ones to be allocated.
static SamplingAllocationStrategy	sizeBetweenWithSampling(int min, int max, double getPermitsSamplingRate, double returnPermitsSamplingRate) An SamplingAllocationStrategy that wraps a sizeBetween AllocationStrategy and samples calls to AllocationStrategy.getPermits(int) and AllocationStrategy.returnPermits(int).
int	warmupParallelism() Return the concurrency level used when the allocator is subscribed to during the warmup phase, if any.
static SamplingAllocationStrategy	withSampling(AllocationStrategy delegate, double getPermitsSamplingRate, double returnPermitsSamplingRate) An AllocationStrategy that wraps a delegate and samples calls to AllocationStrategy.getPermits(int) and AllocationStrategy.returnPermits(int).

Methods inherited from class java.lang.Object

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

Field Detail

delegate

public final AllocationStrategy delegate

The delegate AllocationStrategy backing this sampling strategy.

gettingSamples

public final LinkedList<Throwable> gettingSamples

The list of samples for getPermits(int) calls, as Throwable that trace back to the callers of the sampled calls.

gettingSamplingRate

public final double gettingSamplingRate

The configured sampling rate for getPermits(int) calls, as a double between 0d and 1d (percentage).

returningSamples

public final LinkedList<Throwable> returningSamples

The list of samples for returnPermits(int) calls, as Throwable that trace back to the callers of the sampled calls.

returningSamplingRate

public final double returningSamplingRate

The configured sampling rate for returnPermits(int) calls, as a double between 0d and 1d (percentage).

Method Detail

sizeBetweenWithSampling

public static SamplingAllocationStrategy sizeBetweenWithSampling(int min,
                                                                 int max,
                                                                 double getPermitsSamplingRate,
                                                                 double returnPermitsSamplingRate)

An SamplingAllocationStrategy that wraps a sizeBetween AllocationStrategy and samples calls to AllocationStrategy.getPermits(int) and AllocationStrategy.returnPermits(int).

Parameters:

min - the minimum number of permits (see PoolBuilder.sizeBetween(int, int))

max - the maximum number of permits (see PoolBuilder.sizeBetween(int, int))

getPermitsSamplingRate - the sampling rate for AllocationStrategy.getPermits(int) calls (0.0d to 1.0d)

returnPermitsSamplingRate - the sampling rate for AllocationStrategy.returnPermits(int) calls (0.0d to 1.0d)

Returns:

a sampled AllocationStrategy that otherwise behaves like the PoolBuilder.sizeBetween(int, int) strategy

withSampling

public static SamplingAllocationStrategy withSampling(AllocationStrategy delegate,
                                                      double getPermitsSamplingRate,
                                                      double returnPermitsSamplingRate)

An AllocationStrategy that wraps a delegate and samples calls to AllocationStrategy.getPermits(int) and AllocationStrategy.returnPermits(int). Only a given percentage of calls are sampled, and these are stored as stacktraces in the sampling strategy. If a AllocationStrategy.returnPermits(int) call fails, a new IllegalArgumentException is thrown with a composite cause that represents all the sampled calls (see Exceptions.unwrapMultiple(Throwable)).

The two types of calls are sampled separately. The reservoir sampling algorithm is used to instantiate a sampling decision bitset over 100 slots, which are then applied live to windows of 100 calls.

Parameters:

delegate - the underlying AllocationStrategy

getPermitsSamplingRate - the sampling rate for AllocationStrategy.getPermits(int) calls (0.0d to 1.0d)

returnPermitsSamplingRate - the sampling rate for AllocationStrategy.returnPermits(int) calls (0.0d to 1.0d)

Returns:

a sampled AllocationStrategy that otherwise behaves like the delegate

getPermits

public int getPermits(int desired)

Description copied from interface: AllocationStrategy

Try to get the permission to allocate a desired positive number of new resources. Returns the permissible number of resources which MUST be created (otherwise the internal live counter of the strategy might be off). This permissible number might be zero, and it can also be a greater number than desired, which could for example denote a minimum warmed-up size for the pool to maintain (see below). Once a resource is discarded from the pool, it must update the strategy using AllocationStrategy.returnPermits(int) (which can happen in batches or with value 1).

For the warming up case, the typical pattern would be to call this method with a desired of zero.

Specified by:

getPermits in interface AllocationStrategy

Parameters:

desired - the desired number of new resources

Returns:

the actual number of new resources that MUST be created, can be 0 and can be more than desired

returnPermits

public void returnPermits(int returned)

Description copied from interface: AllocationStrategy

Update the strategy to indicate that N resources were discarded from the Pool, potentially leaving space for N new ones to be allocated. Users MUST ensure that this method isn't called with a value greater than the number of held permits it has.

Some strategy MIGHT throw an IllegalArgumentException if it can be determined the number of returned permits is not consistent with the strategy's limits and delivered permits.

Specified by:

returnPermits in interface AllocationStrategy

estimatePermitCount

public int estimatePermitCount()

Description copied from interface: AllocationStrategy

Best-effort peek at the state of the strategy which indicates roughly how many more resources can currently be allocated. Should be paired with AllocationStrategy.getPermits(int) for an atomic permission.

Specified by:

estimatePermitCount in interface AllocationStrategy

Returns:

an ESTIMATED count of how many more resources can currently be allocated

permitGranted

public int permitGranted()

Specified by:

permitGranted in interface AllocationStrategy

Returns:

a best estimate of the number of permits currently granted, between 0 and Integer.MAX_VALUE

permitMinimum

public int permitMinimum()

Description copied from interface: AllocationStrategy

Return the minimum number of permits this strategy tries to maintain granted (reflecting a minimal size for the pool), or 0 for scale-to-zero.

Specified by:

permitMinimum in interface AllocationStrategy

Returns:

the minimum number of permits this strategy tries to maintain, or 0

permitMaximum

public int permitMaximum()

Specified by:

permitMaximum in interface AllocationStrategy

Returns:

the maximum number of permits this strategy can grant in total, or Integer.MAX_VALUE for unbounded

warmupParallelism

public int warmupParallelism()

Description copied from interface: AllocationStrategy

Return the concurrency level used when the allocator is subscribed to during the warmup phase, if any.

The number of resources created concurrently will not exceed the value returned by warmupParallelism(). If the concurrency level is set to 1, pre-allocation of resources will be performed sequentially by subscribing to the allocator one at a time. The process waits for a resource to be created before subscribing again to the allocator. This sequence continues until all pre-allocated resources have been successfully created.

Defaults to 1

Specified by:

warmupParallelism in interface AllocationStrategy

Returns:

The concurrency level used when the allocator is subscribed to during the warmup phase, must be positive, 1 by default