Module io.helidon.common.concurrency.limits
Package io.helidon.common.concurrency.limits

Interface LimitAlgorithm

All Known Subinterfaces:
Limit
All Known Implementing Classes:
AimdLimit, FixedLimit
public interface LimitAlgorithm
Concurrency limit algorithm.

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.

  • 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.
      Use call(java.util.concurrent.Callable).
      Invoke a callable within the limits of this limiter.

      Limit implementor's note: Make sure to catch IgnoreTaskException from the callable, and call its IgnoreTaskException.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 permit
      Exception - in case the task failed with an exception

    • call

      default <T> LimitAlgorithm.Result<T> call(Callable<T> callable) throws Exception
      Invoke a callable within the limits of this limiter, invoking the provided Consumer with the LimitAlgorithm.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 its IgnoreTaskException.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 suitable LimitOutcome 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 permit
      Exception - in case the task failed with an exception

    • 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.
      Use run(Runnable).
      Invoke a runnable within the limits of this limiter.

      Limit implementor's note: Make sure to catch IgnoreTaskException from the runnable, and call its IgnoreTaskException.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 permit
      Exception - in case the task failed with an exception

    • run

      default LimitAlgorithm.Outcome run(Runnable runnable) throws Exception
      Invoke a runnable within the limits of this limiter, invoking the provided Consumer with the LimitAlgorithm.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 its IgnoreTaskException.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 suitable LimitOutcome 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 permit
      Exception - in case the task failed with an exception

    • tryAcquire

      @Deprecated(since="4.3.0", forRemoval=true) Optional<LimitAlgorithm.Token> tryAcquire()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use 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:
      acquired token, or empty if there is no available token

    • tryAcquireOutcome

      default LimitAlgorithm.Outcome 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(since="4.3.0", forRemoval=true) Optional<LimitAlgorithm.Token> tryAcquire(boolean wait)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use tryAcquireOutcome(boolean)
      Try to acquire a token, waiting for available permits for the configured amount of time, if wait 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

      default LimitAlgorithm.Outcome tryAcquireOutcome(boolean wait)
      Tries to acquire a token, waiting for available permits for the configured amount of time, if wait is enabled, returning immediately otherwise. Concrete implementations should invoke the provided outcomeConsumer.

      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