dev.failsafe

Interface RateLimiter<R>

Type Parameters:

R - result type

All Superinterfaces:

Policy<R>

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:

• acquirePermit()
• acquirePermits(int)
• acquirePermit(Duration)
• acquirePermits(int, Duration)
• tryAcquirePermit(Duration)
• tryAcquirePermits(int, Duration)

The methods that return immediately include:

• tryAcquirePermit()
• tryAcquirePermits(int)
• reservePermit()
• reservePermits(int)
• tryReservePermit(Duration)
• tryReservePermits(int, Duration)

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:

RateLimiterConfig, RateLimiterBuilder, RateLimitExceededException

Method Summary

Modifier and Type	Method and 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(Duration maxRate) Returns a smooth RateLimiterBuilder for the maxRate, which controls how frequently an execution is permitted.
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.
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 dev.failsafe.Policy

toExecutor

Method Detail

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:

tryAcquirePermit(), reservePermit()

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 < 1

InterruptedException - if the current thread is interrupted while waiting to acquire the permits

See Also:

tryAcquirePermits(int), reservePermits(int)

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:

tryAcquirePermit(Duration)

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 < 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:

tryAcquirePermits(int, Duration)

isSmooth

default boolean isSmooth()

Returns whether the rate limiter is smooth.

See Also:

smoothBuilder(long, Duration), smoothBuilder(Duration)

isBursty

default boolean isBursty()

Returns whether the rate limiter is bursty.

See Also:

burstyBuilder(long, Duration)

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:

acquirePermit(), tryAcquirePermit()

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 < 1

See Also:

acquirePermits(int), tryAcquirePermits(int)

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:

acquirePermit(Duration), tryAcquirePermit(Duration)

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 < 1

NullPointerException - if maxWaitTime is null

See Also:

acquirePermit(Duration), tryAcquirePermit(Duration)

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:

acquirePermit(), reservePermits(int)

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 < 1

See Also:

acquirePermits(int)

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:

acquirePermit(Duration)

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 < 1

NullPointerException - if maxWaitTime is null

InterruptedException - if the current thread is interrupted while waiting to acquire the permits

See Also:

acquirePermits(int, Duration)