Class RateLimiter
- java.lang.Object
-
- com.google.common.util.concurrent.RateLimiter
-
@Beta @GwtIncompatible public abstract class RateLimiter extends java.lang.Object
A rate limiter. Conceptually, a rate limiter distributes permits at a configurable rate. Eachacquire()
blocks if necessary until a permit is available, and then takes it. Once acquired, permits need not be released.RateLimiter
is safe for concurrent use: It will restrict the total rate of calls from all threads. Note, however, that it does not guarantee fairness.Rate limiters are often used to restrict the rate at which some physical or logical resource is accessed. This is in contrast to
Semaphore
which restricts the number of concurrent accesses instead of the rate (note though that concurrency and rate are closely related, e.g. see Little's Law).A
RateLimiter
is defined primarily by the rate at which permits are issued. Absent additional configuration, permits will be distributed at a fixed rate, defined in terms of permits per second. Permits will be distributed smoothly, with the delay between individual permits being adjusted to ensure that the configured rate is maintained.It is possible to configure a
RateLimiter
to have a warmup period during which time the permits issued each second steadily increases until it hits the stable rate.As an example, imagine that we have a list of tasks to execute, but we don't want to submit more than 2 per second:
final RateLimiter rateLimiter = RateLimiter.create(2.0); // rate is "2 permits per second" void submitTasks(List<Runnable> tasks, Executor executor) { for (Runnable task : tasks) { rateLimiter.acquire(); // may wait executor.execute(task); } }
As another example, imagine that we produce a stream of data, and we want to cap it at 5kb per second. This could be accomplished by requiring a permit per byte, and specifying a rate of 5000 permits per second:
final RateLimiter rateLimiter = RateLimiter.create(5000.0); // rate = 5000 permits per second void submitPacket(byte[] packet) { rateLimiter.acquire(packet.length); networkService.send(packet); }
It is important to note that the number of permits requested never affects the throttling of the request itself (an invocation to
acquire(1)
and an invocation toacquire(1000)
will result in exactly the same throttling, if any), but it affects the throttling of the next request. I.e., if an expensive task arrives at an idle RateLimiter, it will be granted immediately, but it is the next request that will experience extra throttling, thus paying for the cost of the expensive task.- Since:
- 13.0
- Author:
- Dimitris Andreou
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description double
acquire()
Acquires a single permit from thisRateLimiter
, blocking until the request can be granted.double
acquire(int permits)
Acquires the given number of permits from thisRateLimiter
, blocking until the request can be granted.static RateLimiter
create(double permitsPerSecond)
Creates aRateLimiter
with the specified stable throughput, given as "permits per second" (commonly referred to as QPS, queries per second).static RateLimiter
create(double permitsPerSecond, long warmupPeriod, java.util.concurrent.TimeUnit unit)
Creates aRateLimiter
with the specified stable throughput, given as "permits per second" (commonly referred to as QPS, queries per second), and a warmup period, during which theRateLimiter
smoothly ramps up its rate, until it reaches its maximum rate at the end of the period (as long as there are enough requests to saturate it).double
getRate()
Returns the stable rate (aspermits per seconds
) with which thisRateLimiter
is configured with.void
setRate(double permitsPerSecond)
Updates the stable rate of thisRateLimiter
, that is, thepermitsPerSecond
argument provided in the factory method that constructed theRateLimiter
.java.lang.String
toString()
boolean
tryAcquire()
Acquires a permit from thisRateLimiter
if it can be acquired immediately without delay.boolean
tryAcquire(int permits)
Acquires permits from thisRateLimiter
if it can be acquired immediately without delay.boolean
tryAcquire(int permits, long timeout, java.util.concurrent.TimeUnit unit)
Acquires the given number of permits from thisRateLimiter
if it can be obtained without exceeding the specifiedtimeout
, or returnsfalse
immediately (without waiting) if the permits would not have been granted before the timeout expired.boolean
tryAcquire(long timeout, java.util.concurrent.TimeUnit unit)
Acquires a permit from thisRateLimiter
if it can be obtained without exceeding the specifiedtimeout
, or returnsfalse
immediately (without waiting) if the permit would not have been granted before the timeout expired.
-
-
-
Method Detail
-
create
public static RateLimiter create(double permitsPerSecond)
Creates aRateLimiter
with the specified stable throughput, given as "permits per second" (commonly referred to as QPS, queries per second).The returned
RateLimiter
ensures that on average no more thanpermitsPerSecond
are issued during any given second, with sustained requests being smoothly spread over each second. When the incoming request rate exceedspermitsPerSecond
the rate limiter will release one permit every(1.0 / permitsPerSecond)
seconds. When the rate limiter is unused, bursts of up topermitsPerSecond
permits will be allowed, with subsequent requests being smoothly limited at the stable rate ofpermitsPerSecond
.- Parameters:
permitsPerSecond
- the rate of the returnedRateLimiter
, measured in how many permits become available per second- Throws:
java.lang.IllegalArgumentException
- ifpermitsPerSecond
is negative or zero
-
create
public static RateLimiter create(double permitsPerSecond, long warmupPeriod, java.util.concurrent.TimeUnit unit)
Creates aRateLimiter
with the specified stable throughput, given as "permits per second" (commonly referred to as QPS, queries per second), and a warmup period, during which theRateLimiter
smoothly ramps up its rate, until it reaches its maximum rate at the end of the period (as long as there are enough requests to saturate it). Similarly, if theRateLimiter
is left unused for a duration ofwarmupPeriod
, it will gradually return to its "cold" state, i.e. it will go through the same warming up process as when it was first created.The returned
RateLimiter
is intended for cases where the resource that actually fulfills the requests (e.g., a remote server) needs "warmup" time, rather than being immediately accessed at the stable (maximum) rate.The returned
RateLimiter
starts in a "cold" state (i.e. the warmup period will follow), and if it is left unused for long enough, it will return to that state.- Parameters:
permitsPerSecond
- the rate of the returnedRateLimiter
, measured in how many permits become available per secondwarmupPeriod
- the duration of the period where theRateLimiter
ramps up its rate, before reaching its stable (maximum) rateunit
- the time unit of the warmupPeriod argument- Throws:
java.lang.IllegalArgumentException
- ifpermitsPerSecond
is negative or zero orwarmupPeriod
is negative
-
setRate
public final void setRate(double permitsPerSecond)
Updates the stable rate of thisRateLimiter
, that is, thepermitsPerSecond
argument provided in the factory method that constructed theRateLimiter
. Currently throttled threads will not be awakened as a result of this invocation, thus they do not observe the new rate; only subsequent requests will.Note though that, since each request repays (by waiting, if necessary) the cost of the previous request, this means that the very next request after an invocation to
setRate
will not be affected by the new rate; it will pay the cost of the previous request, which is in terms of the previous rate.The behavior of the
RateLimiter
is not modified in any other way, e.g. if theRateLimiter
was configured with a warmup period of 20 seconds, it still has a warmup period of 20 seconds after this method invocation.- Parameters:
permitsPerSecond
- the new stable rate of thisRateLimiter
- Throws:
java.lang.IllegalArgumentException
- ifpermitsPerSecond
is negative or zero
-
getRate
public final double getRate()
Returns the stable rate (aspermits per seconds
) with which thisRateLimiter
is configured with. The initial value of this is the same as thepermitsPerSecond
argument passed in the factory method that produced thisRateLimiter
, and it is only updated after invocations to setRate(double).
-
acquire
@CanIgnoreReturnValue public double acquire()
Acquires a single permit from thisRateLimiter
, blocking until the request can be granted. Tells the amount of time slept, if any.This method is equivalent to
acquire(1)
.- Returns:
- time spent sleeping to enforce rate, in seconds; 0.0 if not rate-limited
- Since:
- 16.0 (present in 13.0 with
void
return type})
-
acquire
@CanIgnoreReturnValue public double acquire(int permits)
Acquires the given number of permits from thisRateLimiter
, blocking until the request can be granted. Tells the amount of time slept, if any.- Parameters:
permits
- the number of permits to acquire- Returns:
- time spent sleeping to enforce rate, in seconds; 0.0 if not rate-limited
- Throws:
java.lang.IllegalArgumentException
- if the requested number of permits is negative or zero- Since:
- 16.0 (present in 13.0 with
void
return type})
-
tryAcquire
public boolean tryAcquire(long timeout, java.util.concurrent.TimeUnit unit)
Acquires a permit from thisRateLimiter
if it can be obtained without exceeding the specifiedtimeout
, or returnsfalse
immediately (without waiting) if the permit would not have been granted before the timeout expired.This method is equivalent to
tryAcquire(1, timeout, unit)
.- Parameters:
timeout
- the maximum time to wait for the permit. Negative values are treated as zero.unit
- the time unit of the timeout argument- Returns:
true
if the permit was acquired,false
otherwise- Throws:
java.lang.IllegalArgumentException
- if the requested number of permits is negative or zero
-
tryAcquire
public boolean tryAcquire(int permits)
Acquires permits from thisRateLimiter
if it can be acquired immediately without delay.This method is equivalent to
tryAcquire(permits, 0, anyUnit)
.- Parameters:
permits
- the number of permits to acquire- Returns:
true
if the permits were acquired,false
otherwise- Throws:
java.lang.IllegalArgumentException
- if the requested number of permits is negative or zero- Since:
- 14.0
-
tryAcquire
public boolean tryAcquire()
Acquires a permit from thisRateLimiter
if it can be acquired immediately without delay.This method is equivalent to
tryAcquire(1)
.- Returns:
true
if the permit was acquired,false
otherwise- Since:
- 14.0
-
tryAcquire
public boolean tryAcquire(int permits, long timeout, java.util.concurrent.TimeUnit unit)
Acquires the given number of permits from thisRateLimiter
if it can be obtained without exceeding the specifiedtimeout
, or returnsfalse
immediately (without waiting) if the permits would not have been granted before the timeout expired.- Parameters:
permits
- the number of permits to acquiretimeout
- the maximum time to wait for the permits. Negative values are treated as zero.unit
- the time unit of the timeout argument- Returns:
true
if the permits were acquired,false
otherwise- Throws:
java.lang.IllegalArgumentException
- if the requested number of permits is negative or zero
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-