Interface RateLimiter<R>

Type Parameters:
R - result type
All Superinterfaces:
Policy<R>
All Known Implementing Classes:
RateLimiterImpl
public interface RateLimiter<R> extends Policy<R>
A rate limiter allows you to control the rate of executions as a way of preventing system overload.

There are two types of rate limiting: smooth and bursty. Smooth rate limiting will evenly spread out execution requests over-time, effectively smoothing out uneven execution request rates. Bursty rate limiting allows potential bursts of executions to occur, up to a configured max per time period.

Rate limiting is based on permits, which can be requested in order to perform rate limited execution. Permits are automatically refreshed over time based on the rate limiter's configuration.

This class provides methods that block while waiting for permits to become available, and also methods that return immediately. The blocking methods include:

The methods that return immediately include:

This class also provides methods that throw RateLimitExceededException when permits cannot be acquired, and also methods that return a boolean. The acquire methods all throw RateLimitExceededException when permits cannot be acquired, and the tryAcquire methods return a boolean.

The reserve methods attempt to reserve permits and return an expected wait time before the permit can be used. This helps integrate with scenarios where you need to wait externally

This class is threadsafe.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    acquirePermit()
    Attempts to acquire a permit to perform an execution against the rate limiter, waiting until one is available or the thread is interrupted.
    default void
    acquirePermit(Duration maxWaitTime)
    Attempts to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until one is available, else throwing RateLimitExceededException if a permit will not be available in time.
    void
    acquirePermits(int permits)
    Attempts to acquire the requested permits to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.
    default void
    acquirePermits(int permits, Duration maxWaitTime)
    Attempts to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available, else throwing RateLimitExceededException if the permits will not be available in time.
    static <R> RateLimiterBuilder<R>
    builder(RateLimiterConfig<R> config)
    Creates a new RateLimiterBuilder that will be based on the config.
    static <R> RateLimiterBuilder<R>
    burstyBuilder(long maxExecutions, Duration period)
    Returns a bursty RateLimiterBuilder for the maxExecutions per period.
    RateLimiterConfig<R>
    getConfig()
    Returns the RateLimiterConfig that the RateLimiter was built with.
    default boolean
    isBursty()
    Returns whether the rate limiter is bursty.
    default boolean
    isSmooth()
    Returns whether the rate limiter is smooth.
    default Duration
    reservePermit()
    Reserves a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit.
    Duration
    reservePermits(int permits)
    Reserves the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits.
    static <R> RateLimiterBuilder<R>
    smoothBuilder(long maxExecutions, Duration period)
    Returns a smooth RateLimiterBuilder for the maxExecutions and period, which control how frequently an execution is permitted.
    static <R> RateLimiterBuilder<R>
    smoothBuilder(Duration maxRate)
    Returns a smooth RateLimiterBuilder for the maxRate, which controls how frequently an execution is permitted.
    default boolean
    tryAcquirePermit()
    Tries to acquire a permit to perform an execution against the rate limiter, returning immediately without waiting.
    default boolean
    tryAcquirePermit(Duration maxWaitTime)
    Tries to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until they are available.
    boolean
    tryAcquirePermits(int permits)
    Tries to acquire the requested permits to perform executions against the rate limiter, returning immediately without waiting.
    boolean
    tryAcquirePermits(int permits, Duration maxWaitTime)
    Tries to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available.
    default Duration
    tryReservePermit(Duration maxWaitTime)
    Tries to reserve a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit, as long as it's less than the maxWaitTime.
    Duration
    tryReservePermits(int permits, Duration maxWaitTime)
    Tries to reserve the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits, as long as it's less than the maxWaitTime.

    Methods inherited from interface Policy

    toExecutor

  • Method Details

    • smoothBuilder

      static <R> RateLimiterBuilder<R> smoothBuilder(long maxExecutions, Duration period)
      Returns a smooth RateLimiterBuilder for the maxExecutions and period, which control how frequently an execution is permitted. The individual execution rate is computed as period / maxExecutions. For example, with maxExecutions of 100 and a period of 1000 millis, individual executions will be permitted at a max rate of one every 10 millis.

      By default, the returned RateLimiterBuilder will have a max wait time of 0.

      Executions are performed with no delay until they exceed the max rate, after which executions are either rejected or will block and wait until the max wait time is exceeded.

      Parameters:
      maxExecutions - The max number of permitted executions per period
      period - The period after which permitted executions are reset to the maxExecutions

    • smoothBuilder

      static <R> RateLimiterBuilder<R> smoothBuilder(Duration maxRate)
      Returns a smooth RateLimiterBuilder for the maxRate, which controls how frequently an execution is permitted. For example, a maxRate of Duration.ofMillis(10) would allow up to one execution every 10 milliseconds.

      By default, the returned RateLimiterBuilder will have a max wait time of 0.

      Executions are performed with no delay until they exceed the maxRate, after which executions are either rejected or will block and wait until the max wait time is exceeded.

      Parameters:
      maxRate - at which individual executions should be permitted

    • burstyBuilder

      static <R> RateLimiterBuilder<R> burstyBuilder(long maxExecutions, Duration period)
      Returns a bursty RateLimiterBuilder for the maxExecutions per period. For example, a maxExecutions value of 100 with a period of Duration.ofSeconds(1) would allow up to 100 executions every 1 second.

      By default, the returned RateLimiterBuilder will have a max wait time of 0.

      Executions are performed with no delay up until the maxExecutions are reached for the current period, after which executions are either rejected or will block and wait until the max wait time is exceeded.

      Parameters:
      maxExecutions - The max number of permitted executions per period
      period - The period after which permitted executions are reset to the maxExecutions

    • builder

      static <R> RateLimiterBuilder<R> builder(RateLimiterConfig<R> config)
      Creates a new RateLimiterBuilder that will be based on the config.

    • getConfig

      RateLimiterConfig<R> getConfig()
      Returns the RateLimiterConfig that the RateLimiter was built with.
      Specified by:
      getConfig in interface Policy<R>

    • acquirePermit

      default void acquirePermit() throws InterruptedException
      Attempts to acquire a permit to perform an execution against the rate limiter, waiting until one is available or the thread is interrupted.
      Throws:
      InterruptedException - if the current thread is interrupted while waiting to acquire a permit
      See Also:

    • acquirePermits

      void acquirePermits(int permits) throws InterruptedException
      Attempts to acquire the requested permits to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      InterruptedException - if the current thread is interrupted while waiting to acquire the permits
      See Also:

    • acquirePermit

      default void acquirePermit(Duration maxWaitTime) throws InterruptedException
      Attempts to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until one is available, else throwing RateLimitExceededException if a permit will not be available in time.
      Throws:
      NullPointerException - if maxWaitTime is null
      RateLimitExceededException - if the rate limiter cannot acquire a permit within the maxWaitTime
      InterruptedException - if the current thread is interrupted while waiting to acquire a permit
      See Also:

    • acquirePermits

      default void acquirePermits(int permits, Duration maxWaitTime) throws InterruptedException
      Attempts to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available, else throwing RateLimitExceededException if the permits will not be available in time.
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      NullPointerException - if maxWaitTime is null
      RateLimitExceededException - if the rate limiter cannot acquire a permit within the maxWaitTime
      InterruptedException - if the current thread is interrupted while waiting to acquire the permits
      See Also:

    • isSmooth

      default boolean isSmooth()
      Returns whether the rate limiter is smooth.
      See Also:

    • isBursty

      default boolean isBursty()
      Returns whether the rate limiter is bursty.
      See Also:

    • reservePermit

      default Duration reservePermit()
      Reserves a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit. Returns 0 if the permit is immediately available and no waiting is needed.
      See Also:

    • reservePermits

      Duration reservePermits(int permits)
      Reserves the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits. Returns 0 if the permits are immediately available and no waiting is needed.
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      See Also:

    • tryReservePermit

      default Duration tryReservePermit(Duration maxWaitTime)
      Tries to reserve a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit, as long as it's less than the maxWaitTime.
      • Returns the expected wait time for the permit if it was successfully reserved.
      • Returns 0 if the permit was successfully reserved and no waiting is needed.
      • Returns -1 nanoseconds if the permit was not reserved because the wait time would be greater than the maxWaitTime.
      Throws:
      NullPointerException - if maxWaitTime is null
      See Also:

    • tryReservePermits

      Duration tryReservePermits(int permits, Duration maxWaitTime)
      Tries to reserve the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits, as long as it's less than the maxWaitTime.
      • Returns the expected wait time for the permits if they were successfully reserved.
      • Returns 0 if the permits were successfully reserved and no waiting is needed.
      • Returns -1 nanoseconds if the permits were not reserved because the wait time would be greater than the maxWaitTime.
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      NullPointerException - if maxWaitTime is null
      See Also:

    • tryAcquirePermit

      default boolean tryAcquirePermit()
      Tries to acquire a permit to perform an execution against the rate limiter, returning immediately without waiting.
      Returns:
      whether the requested permits are successfully acquired or not
      See Also:

    • tryAcquirePermits

      boolean tryAcquirePermits(int permits)
      Tries to acquire the requested permits to perform executions against the rate limiter, returning immediately without waiting.
      Returns:
      whether the requested permits are successfully acquired or not
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      See Also:

    • tryAcquirePermit

      default boolean tryAcquirePermit(Duration maxWaitTime) throws InterruptedException
      Tries to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until they are available.
      Returns:
      whether a permit is successfully acquired
      Throws:
      NullPointerException - if maxWaitTime is null
      InterruptedException - if the current thread is interrupted while waiting to acquire a permit
      See Also:

    • tryAcquirePermits

      boolean tryAcquirePermits(int permits, Duration maxWaitTime) throws InterruptedException
      Tries to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available.
      Returns:
      whether the requested permits are successfully acquired or not
      Throws:
      IllegalArgumentException - if permits is invalid input: '<' 1
      NullPointerException - if maxWaitTime is null
      InterruptedException - if the current thread is interrupted while waiting to acquire the permits
      See Also: