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:
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. Theacquire
methods all throwRateLimitExceededException
when permits cannot be acquired, and thetryAcquire
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 externallyThis class is threadsafe.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods 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(java.time.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, java.time.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, java.time.Duration period)
RateLimiterConfig<R>
getConfig()
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 java.time.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.java.time.Duration
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, java.time.Duration period)
Returns a smoothRateLimiterBuilder
for themaxExecutions
andperiod
, which control how frequently an execution is permitted.static <R> RateLimiterBuilder<R>
smoothBuilder(java.time.Duration maxRate)
Returns a smoothRateLimiterBuilder
for themaxRate
, 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(java.time.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, java.time.Duration maxWaitTime)
Tries to acquire the requestedpermits
to perform executions against the rate limiter, waiting up to themaxWaitTime
until they are available.default java.time.Duration
tryReservePermit(java.time.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
.java.time.Duration
tryReservePermits(int permits, java.time.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 Detail
-
smoothBuilder
static <R> RateLimiterBuilder<R> smoothBuilder(long maxExecutions, java.time.Duration period)
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
static <R> RateLimiterBuilder<R> smoothBuilder(java.time.Duration maxRate)
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
static <R> RateLimiterBuilder<R> burstyBuilder(long maxExecutions, java.time.Duration period)
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
static <R> RateLimiterBuilder<R> builder(RateLimiterConfig<R> config)
Creates a new RateLimiterBuilder that will be based on theconfig
.
-
getConfig
RateLimiterConfig<R> getConfig()
Returns theRateLimiterConfig
that the RateLimiter was built with.
-
acquirePermit
default void acquirePermit() throws java.lang.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:
java.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire a permit- See Also:
tryAcquirePermit()
,reservePermit()
-
acquirePermits
void acquirePermits(int permits) throws java.lang.InterruptedException
Attempts to acquire the requestedpermits
to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.- Throws:
java.lang.IllegalArgumentException
- ifpermits
is < 1java.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- See Also:
tryAcquirePermits(int)
,reservePermits(int)
-
acquirePermit
default void acquirePermit(java.time.Duration maxWaitTime) throws java.lang.InterruptedException
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:
java.lang.NullPointerException
- ifmaxWaitTime
is nullRateLimitExceededException
- if the rate limiter cannot acquire a permit within themaxWaitTime
java.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire a permit- See Also:
tryAcquirePermit(Duration)
-
acquirePermits
default void acquirePermits(int permits, java.time.Duration maxWaitTime) throws java.lang.InterruptedException
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:
java.lang.IllegalArgumentException
- ifpermits
is < 1java.lang.NullPointerException
- ifmaxWaitTime
is nullRateLimitExceededException
- if the rate limiter cannot acquire a permit within themaxWaitTime
java.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- See Also:
tryAcquirePermits(int, Duration)
-
isSmooth
default boolean isSmooth()
Returns whether the rate limiter is smooth.
-
isBursty
default boolean isBursty()
Returns whether the rate limiter is bursty.- See Also:
burstyBuilder(long, Duration)
-
reservePermit
default java.time.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. Returns0
if the permit is immediately available and no waiting is needed.- See Also:
acquirePermit()
,tryAcquirePermit()
-
reservePermits
java.time.Duration 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. Returns0
if the permits are immediately available and no waiting is needed.- Throws:
java.lang.IllegalArgumentException
- ifpermits
is < 1- See Also:
acquirePermits(int)
,tryAcquirePermits(int)
-
tryReservePermit
default java.time.Duration tryReservePermit(java.time.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
.- 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:
java.lang.NullPointerException
- ifmaxWaitTime
is null- See Also:
acquirePermit(Duration)
,tryAcquirePermit(Duration)
-
tryReservePermits
java.time.Duration tryReservePermits(int permits, java.time.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
.- 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:
java.lang.IllegalArgumentException
- ifpermits
is < 1java.lang.NullPointerException
- ifmaxWaitTime
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 requestedpermits
to perform executions against the rate limiter, returning immediately without waiting.- Returns:
- whether the requested
permits
are successfully acquired or not - Throws:
java.lang.IllegalArgumentException
- ifpermits
is < 1- See Also:
acquirePermits(int)
-
tryAcquirePermit
default boolean tryAcquirePermit(java.time.Duration maxWaitTime) throws java.lang.InterruptedException
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:
java.lang.NullPointerException
- ifmaxWaitTime
is nulljava.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire a permit- See Also:
acquirePermit(Duration)
-
tryAcquirePermits
boolean tryAcquirePermits(int permits, java.time.Duration maxWaitTime) throws java.lang.InterruptedException
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:
java.lang.IllegalArgumentException
- ifpermits
is < 1java.lang.NullPointerException
- ifmaxWaitTime
is nulljava.lang.InterruptedException
- if the current thread is interrupted while waiting to acquire thepermits
- See Also:
acquirePermits(int, Duration)
-
-