Interface RateLimiter<R>
- Type Parameters:
R
- result type
- All Superinterfaces:
Policy<R>
- All Known Implementing Classes:
RateLimiterImpl
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:
-
Method Summary
Modifier and TypeMethodDescriptiondefault void
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 themaxWaitTime
until one is available, else throwingRateLimitExceededException
if a permit will not be available in time.void
acquirePermits
(int permits) Attempts to acquire the requestedpermits
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 requestedpermits
to perform executions against the rate limiter, waiting up to themaxWaitTime
until they are available, else throwingRateLimitExceededException
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 theconfig
.static <R> RateLimiterBuilder
<R> burstyBuilder
(long maxExecutions, Duration period) Returns theRateLimiterConfig
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
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.reservePermits
(int permits) Reserves thepermits
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 smoothRateLimiterBuilder
for themaxExecutions
andperiod
, which control how frequently an execution is permitted.static <R> RateLimiterBuilder
<R> smoothBuilder
(Duration maxRate) Returns a smoothRateLimiterBuilder
for themaxRate
, which controls how frequently an execution is permitted.default boolean
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 themaxWaitTime
until they are available.boolean
tryAcquirePermits
(int permits) Tries to acquire the requestedpermits
to perform executions against the rate limiter, returning immediately without waiting.boolean
tryAcquirePermits
(int permits, Duration maxWaitTime) Tries to acquire the requestedpermits
to perform executions against the rate limiter, waiting up to themaxWaitTime
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 themaxWaitTime
.tryReservePermits
(int permits, Duration maxWaitTime) Tries to reserve thepermits
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 themaxWaitTime
.Methods inherited from interface dev.failsafe.Policy
toExecutor
-
Method Details
-
smoothBuilder
Returns a smoothRateLimiterBuilder
for themaxExecutions
andperiod
, which control how frequently an execution is permitted. The individual execution rate is computed asperiod / maxExecutions
. For example, withmaxExecutions
of100
and aperiod
of1000 millis
, individual executions will be permitted at a max rate of one every 10 millis.By default, the returned
RateLimiterBuilder
will have amax wait time
of0
.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 perperiod
period
- The period after which permitted executions are reset to themaxExecutions
-
smoothBuilder
Returns a smoothRateLimiterBuilder
for themaxRate
, which controls how frequently an execution is permitted. For example, amaxRate
ofDuration.ofMillis(10)
would allow up to one execution every 10 milliseconds.By default, the returned
RateLimiterBuilder
will have amax wait time
of0
.Executions are performed with no delay until they exceed the
maxRate
, after which executions are either rejected or will block and wait until themax wait time
is exceeded.- Parameters:
maxRate
- at which individual executions should be permitted
-
burstyBuilder
Returns a burstyRateLimiterBuilder
for themaxExecutions
perperiod
. For example, amaxExecutions
value of100
with aperiod
ofDuration.ofSeconds(1)
would allow up to 100 executions every 1 second.By default, the returned
RateLimiterBuilder
will have amax wait time
of0
.Executions are performed with no delay up until the
maxExecutions
are reached for the currentperiod
, after which executions are either rejected or will block and wait until themax wait time
is exceeded.- Parameters:
maxExecutions
- The max number of permitted executions perperiod
period
- The period after which permitted executions are reset to themaxExecutions
-
builder
Creates a new RateLimiterBuilder that will be based on theconfig
. -
getConfig
RateLimiterConfig<R> getConfig()Returns theRateLimiterConfig
that the RateLimiter was built with. -
acquirePermit
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
Attempts to acquire the requestedpermits
to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.- Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1InterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- See Also:
-
acquirePermit
Attempts to acquire a permit to perform an execution against the rate limiter, waiting up to themaxWaitTime
until one is available, else throwingRateLimitExceededException
if a permit will not be available in time.- Throws:
NullPointerException
- ifmaxWaitTime
is nullRateLimitExceededException
- if the rate limiter cannot acquire a permit within themaxWaitTime
InterruptedException
- if the current thread is interrupted while waiting to acquire a permit- See Also:
-
acquirePermits
Attempts to acquire the requestedpermits
to perform executions against the rate limiter, waiting up to themaxWaitTime
until they are available, else throwingRateLimitExceededException
if the permits will not be available in time.- Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1NullPointerException
- ifmaxWaitTime
is nullRateLimitExceededException
- if the rate limiter cannot acquire a permit within themaxWaitTime
InterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- 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
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. Returns0
if the permit is immediately available and no waiting is needed.- See Also:
-
reservePermits
Reserves thepermits
to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits. Returns0
if the permits are immediately available and no waiting is needed.- Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1- See Also:
-
tryReservePermit
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 themaxWaitTime
.- 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 themaxWaitTime
.
- Throws:
NullPointerException
- ifmaxWaitTime
is null- See Also:
-
tryReservePermits
Tries to reserve thepermits
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 themaxWaitTime
.- 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 themaxWaitTime
.
- Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1NullPointerException
- ifmaxWaitTime
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 requestedpermits
to perform executions against the rate limiter, returning immediately without waiting.- Returns:
- whether the requested
permits
are successfully acquired or not - Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1- See Also:
-
tryAcquirePermit
Tries to acquire a permit to perform an execution against the rate limiter, waiting up to themaxWaitTime
until they are available.- Returns:
- whether a permit is successfully acquired
- Throws:
NullPointerException
- ifmaxWaitTime
is nullInterruptedException
- if the current thread is interrupted while waiting to acquire a permit- See Also:
-
tryAcquirePermits
Tries to acquire the requestedpermits
to perform executions against the rate limiter, waiting up to themaxWaitTime
until they are available.- Returns:
- whether the requested
permits
are successfully acquired or not - Throws:
IllegalArgumentException
- ifpermits
is invalid input: '<' 1NullPointerException
- ifmaxWaitTime
is nullInterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- See Also:
-