Interface LimitAlgorithm
- All Known Subinterfaces:
Limit
- All Known Implementing Classes:
AimdLimit
,FixedLimit
There are two options how to use a limit - by handling a token provided by tryAcquire()
,
or by invoking a callable or runnable through one of the invoke methods (such as invoke(Runnable)
.
The invoke methods are backed by the same tryAcquire()
methods, so behavior is consistent.
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Represents the outcome of a limit algorithm decision.static interface
Carrier for both the result of aCallable
subjected to concurrency limits and the correspondingLimitAlgorithm.Outcome
.static interface
When a token is retrieved fromtryAcquire()
, 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 aSemaphore
). -
Method Summary
Modifier and TypeMethodDescriptiondefault <T> LimitAlgorithm.Result
<T> Invoke a callable within the limits of this limiter, invoking the providedConsumer
with theLimitAlgorithm.Outcome
resulting from applying the limit algorithm.default void
Deprecated, for removal: This API element is subject to removal in a future version.default <T> T
Deprecated, for removal: This API element is subject to removal in a future version.default LimitAlgorithm.Outcome
Invoke a runnable within the limits of this limiter, invoking the providedConsumer
with theLimitAlgorithm.Outcome
resulting from applying the limit algorithm.Deprecated, for removal: This API element is subject to removal in a future version.UsetryAcquireOutcome()
.tryAcquire
(boolean wait) Deprecated, for removal: This API element is subject to removal in a future version.default LimitAlgorithm.Outcome
Try to acquire a token, waiting for available permits for the configured amount of time, if queuing is enabled.default LimitAlgorithm.Outcome
tryAcquireOutcome
(boolean wait) Tries to acquire a token, waiting for available permits for the configured amount of time, ifwait
is enabled, returning immediately otherwise.
-
Method Details
-
invoke
@Deprecated(since="4.3.0", forRemoval=true) default <T> T invoke(Callable<T> callable) throws LimitException, Exception Deprecated, for removal: This API element is subject to removal in a future version.Invoke a callable within the limits of this limiter.Limit
implementor's note: Make sure to catchIgnoreTaskException
from the callable, and call itsIgnoreTaskException.handle()
to either return the provided result, or throw the exception after ignoring the timing for future decisions.- Type Parameters:
T
- the callable return type- Parameters:
callable
- callable to execute within the limit- Returns:
- result of the callable
- Throws:
LimitException
- in case the limiter did not have an available permitException
- in case the task failed with an exception
-
call
Invoke a callable within the limits of this limiter, invoking the providedConsumer
with theLimitAlgorithm.Outcome
resulting from applying the limit algorithm.Note that custom implementations of this interface might not implement this method, in which case the caller's limit outcome consumer receives an "unknown" outcome. Clearly the algorithm made a decision, but does not expose it to callers.
Limit
implementor's notes:- Make sure to catch
IgnoreTaskException
from the callable, and call itsIgnoreTaskException.handle()
to either return the provided result, or throw the exception after ignoring the timing for future decisions. - Make sure the
limitOutcomeConsumer
is non-null, and after determining the disposition of the item of work create a suitableLimitOutcome
and pass it to the consumer. Also, make sure to use an outcome-aware token internally so when the caller invokes the token's methods the outcome is updated accordingly.
- Type Parameters:
T
- the callable return type- Parameters:
callable
- callable to execute within the limit- Returns:
- result of the callable with the outcome
- Throws:
LimitException
- in case the limiter did not have an available permitException
- in case the task failed with an exception
- Make sure to catch
-
invoke
@Deprecated(since="4.3.0", forRemoval=true) default void invoke(Runnable runnable) throws LimitException, Exception Deprecated, for removal: This API element is subject to removal in a future version.Userun(Runnable)
.Invoke a runnable within the limits of this limiter.Limit
implementor's note: Make sure to catchIgnoreTaskException
from the runnable, and call itsIgnoreTaskException.handle()
to either return the provided result, or throw the exception after ignoring the timing for future decisions.- Parameters:
runnable
- runnable to execute within the limit- Throws:
LimitException
- in case the limiter did not have an available permitException
- in case the task failed with an exception
-
run
Invoke a runnable within the limits of this limiter, invoking the providedConsumer
with theLimitAlgorithm.Outcome
resulting from applying the limit algorithm.Note that custom implementations of this interface might not implement this method, in which case the caller's limit outcome consumer receives an "unknown" outcome. Clearly the algorithm made a decision, but does not expose it to callers.
Limit
implementor's notes:- Make sure to catch
IgnoreTaskException
from the runnable, and call itsIgnoreTaskException.handle()
to either return the provided result, or throw the exception after ignoring the timing for future decisions. - Make sure the
limitOutcomeConsumer
is non-null, and after determining the disposition of the item of work create a suitableLimitOutcome
and pass it to the consumer. Also, make sure to use an outcome-aware token internally so when the caller invokes the token's methods the outcome is updated accordingly.
- Parameters:
runnable
- runnable to execute within the limit- Returns:
Outcome
from the limit algorithm- Throws:
LimitException
- in case the limiter did not have an available permitException
- in case the task failed with an exception
- Make sure to catch
-
tryAcquire
Deprecated, for removal: This API element is subject to removal in a future version.UsetryAcquireOutcome()
.Try to acquire a token, waiting for available permits for the configured amount of time, if queuing is enabled.If acquired, the caller must call one of the
LimitAlgorithm.Token
operations to release the token. If the response is empty, the limit does not have an available token.- Returns:
- acquired token, or empty if there is no available token
-
tryAcquireOutcome
Try to acquire a token, waiting for available permits for the configured amount of time, if queuing is enabled.If acquired, the caller must call one of the
LimitAlgorithm.Token
operations to release the token. If the response is empty, the limit does not have an available token.- Returns:
LimitAlgorithm.Outcome
of the tryAcquire attempt.
-
tryAcquire
Deprecated, for removal: This API element is subject to removal in a future version.Try to acquire a token, waiting for available permits for the configured amount of time, ifwait
is enabled, returning immediately otherwise.If acquired, the caller must call one of the
LimitAlgorithm.Token
operations to release the token. If the response is empty, the limit does not have an available token.- Parameters:
wait
- whether to wait in the queue (if one is configured/available in the limit), or to return immediately- Returns:
- acquired token, or empty if there is no available token
-
tryAcquireOutcome
Tries to acquire a token, waiting for available permits for the configured amount of time, ifwait
is enabled, returning immediately otherwise. Concrete implementations should invoke the providedoutcomeConsumer
.Note that custom implementations of this interface might not implement this method, in which case the caller's limit outcome consumer receives an "unknown" outcome. Clearly the algorithm made a decision, but does not expose it to callers.
If acquired, the caller must call one of the
LimitAlgorithm.Token
operations to release the token. If the response is empty, the limit does not have an available token.- Parameters:
wait
- whether to wait in the queue (if one is configured/available in the limit), or to return immediately- Returns:
- acquired token, or empty if there is no available token
-
run(Runnable)
.