Class AimdLimit

java.lang.Object

io.helidon.common.concurrency.limits.AimdLimit

All Implemented Interfaces:

RuntimeType.Api<AimdLimitConfig>, Limit, LimitAlgorithm, NamedService

public class AimdLimit
extends Object
implements LimitAlgorithm, Limit, RuntimeType.Api<AimdLimitConfig>

AIMD based limiter.

The additive-increase/multiplicative-decrease (AIMD) algorithm is a feedback control algorithm best known for its use in TCP congestion control. AIMD combines linear growth of the congestion window when there is no congestion with an exponential reduction when congestion is detected.

Nested Class Summary

Nested classes/interfaces inherited from interface Limit

Limit.InitializationContext

Modifier and Type	Interface	Description
static interface	Limit.InitializationContext	Runtime context used when initializing a Limit.

Nested classes/interfaces inherited from interface LimitAlgorithm

LimitAlgorithm.Outcome, LimitAlgorithm.Result<T>, LimitAlgorithm.Token

Modifier and Type	Interface	Description
static interface	LimitAlgorithm.Outcome	Represents the outcome of a limit algorithm decision.
static interface	LimitAlgorithm.Result<T>	Carrier for both the result of a Callable subjected to concurrency limits and the corresponding LimitAlgorithm.Outcome.
static interface	LimitAlgorithm.Token	When a token is retrieved from LimitAlgorithm.tryAcquireOutcome(), one of its methods must be called when the task is over, to release the token back to the pool (such as a permit returned to a Semaphore).

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_QUEUE_LENGTH	Default length of the queue.
static final String	DEFAULT_QUEUE_TIMEOUT_DURATION	Timeout of a request that is enqueued.

Method Summary

Modifier and Type	Method	Description
static AimdLimitConfig.Builder	builder()	Create a new fluent API builder to construct AimdLimit instance.
<T> LimitAlgorithm.Result<T>	call(Callable<T> callable)	Invoke a callable within the limits of this limiter.
Limit	copy()	Create a copy of this limit with the same configuration.
static AimdLimit	create()	Create a new instance with all defaults.
static AimdLimit	create(AimdLimitConfig config)	Create a new instance from configuration.
static AimdLimit	create(Config config)	Create a new instance from configuration.
static AimdLimit	create(Consumer<AimdLimitConfig.Builder> consumer)	Create a new instance customizing its configuration.
void	init(Limit.InitializationContext context)	Initialization method for this limit.
void	init(String originName)	Deprecated.
String	name()	Name of this implementation, as provided in ConfiguredProvider.create(Config, String).
AimdLimitConfig	prototype()	The prototype as it was received when creating this runtime object instance.
LimitAlgorithm.Outcome	run(Runnable runnable)	Invoke a runnable within the limits of this limiter.
LimitAlgorithm.Outcome	tryAcquireOutcome(boolean wait)	Tries to acquire a token, waiting for available permits for the configured amount of time if wait is enabled and the implementation supports queueing, returning immediately otherwise.
String	type()	Type of this implementation, to distinguish instances of same type, with different NamedService.name().

Methods inherited from class Object

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

Methods inherited from interface LimitAlgorithm

tryAcquireOutcome

Modifier and Type	Method	Description
default LimitAlgorithm.Outcome	tryAcquireOutcome()	Try to acquire a token, waiting for available permits for the configured amount of time, if queuing is enabled.

Field Details

DEFAULT_QUEUE_LENGTH

public static final int DEFAULT_QUEUE_LENGTH

Default length of the queue.

See Also:

• Constant Field Values

DEFAULT_QUEUE_TIMEOUT_DURATION

public static final String DEFAULT_QUEUE_TIMEOUT_DURATION

Timeout of a request that is enqueued.

See Also:

• Constant Field Values

Method Details

builder

public static AimdLimitConfig.Builder builder()

Create a new fluent API builder to construct AimdLimit instance.

Returns:

fluent API builder

create

public static AimdLimit create()

Create a new instance with all defaults.

Returns:

a new limit instance

create

public static AimdLimit create(Config config)

Create a new instance from configuration.

Parameters:

config - configuration of the AIMD limit

Returns:

a new limit instance configured from config

create

public static AimdLimit create(AimdLimitConfig config)

Create a new instance from configuration.

Parameters:

config - configuration of the AIMD limit

Returns:

a new limit instance configured from config

create

public static AimdLimit create(Consumer<AimdLimitConfig.Builder> consumer)

Create a new instance customizing its configuration.

Parameters:

consumer - consumer of configuration builder

Returns:

a new limit instance configured from the builder

call

public <T> LimitAlgorithm.Result<T> call(Callable<T> callable)
                                  throws Exception

Description copied from interface: LimitAlgorithm

Invoke a callable within the limits of this limiter.

Custom implementations that override this method should:

• Obtain the outcome for the submitted work from LimitAlgorithm.tryAcquireOutcome(boolean).
• Invoke LimitAlgorithm.Token.success(), LimitAlgorithm.Token.ignore(), or LimitAlgorithm.Token.dropped() on an accepted token to reflect the final state of the work item.
• Throw LimitException if no token is available.

If the callable throws IgnoreTaskException, call IgnoreTaskException.handle() after marking the token as ignored so the return value or wrapped exception is preserved.

Specified by:

call in interface LimitAlgorithm

Type Parameters:

T - the callable return type

Parameters:

callable - callable to execute within the limit

Returns:

result of the callable with the outcome

Throws:

Exception - in case the task failed with an exception

run

public LimitAlgorithm.Outcome run(Runnable runnable)
                           throws Exception

Description copied from interface: LimitAlgorithm

Invoke a runnable within the limits of this limiter.

Custom implementations that override this method should:

• Obtain the outcome for the submitted work from LimitAlgorithm.tryAcquireOutcome(boolean).
• Invoke LimitAlgorithm.Token.success(), LimitAlgorithm.Token.ignore(), or LimitAlgorithm.Token.dropped() on an accepted token to reflect the final state of the work item.
• Throw LimitException if no token is available.

If the runnable throws IgnoreTaskException, call IgnoreTaskException.handle() after marking the token as ignored so the wrapped exception is preserved when present.

Specified by:

run in interface LimitAlgorithm

Parameters:

runnable - runnable to execute within the limit

Returns:

Outcome from the limit algorithm

Throws:

Exception - in case the task failed with an exception

tryAcquireOutcome

public LimitAlgorithm.Outcome tryAcquireOutcome(boolean wait)

Description copied from interface: LimitAlgorithm

Tries to acquire a token, waiting for available permits for the configured amount of time if wait is enabled and the implementation supports queueing, returning immediately otherwise.

If acquired, the caller must call one of the LimitAlgorithm.Token operations to release the token. If the response is rejected, the limit does not have an available token.

Specified by:

tryAcquireOutcome in interface LimitAlgorithm

Parameters:

wait - whether to wait in the queue (if one is configured/available in the limit), or to return immediately

Returns:

outcome of the acquisition attempt

name

public String name()

Description copied from interface: NamedService

Name of this implementation, as provided in ConfiguredProvider.create(Config, String).

Specified by:

name in interface NamedService

Returns:

name of this service

type

public String type()

Description copied from interface: NamedService

Type of this implementation, to distinguish instances of same type, with different NamedService.name(). Use for example ConfiguredProvider.configKey() to define the type.

Specified by:

type in interface NamedService

Returns:

type of this service

prototype

public AimdLimitConfig prototype()

Description copied from interface: RuntimeType.Api

The prototype as it was received when creating this runtime object instance.

Specified by:

prototype in interface RuntimeType.Api<AimdLimitConfig>

Returns:

prototype object used to create this instance

copy

public Limit copy()

Description copied from interface: Limit

Create a copy of this limit with the same configuration.

Specified by:

copy in interface Limit

Returns:

a copy of this limit

init

public void init(Limit.InitializationContext context)

Description copied from interface: Limit

Initialization method for this limit. This method can be used for any task, including metrics initialization.

Specified by:

init in interface Limit

Parameters:

context - the context for limit initialization

init

@Deprecated
public void init(String originName)

Deprecated.

Description copied from interface: Limit

Initialization method for this limit. This method can be used for any task, including metrics initialization.

Specified by:

init in interface Limit

Parameters:

originName - origin name for this limit, such as "@default"