Guava Official document-ratelimiter class

reprinted from concurrent Programming network –ifeve.com

Ratelimiter Conceptually, the rate limiter assigns licenses at a configurable rate. If necessary, each acquire () blocks the current thread until the license is available. Once the license is acquired, no further release of the license is required.

Proofreading Note: Ratelimiter is using a flow control algorithm called a token bucket, Ratelimiter will throw tokens at a certain frequency to the bucket, the thread gets the token to execute, such as you want your application QPS not more than 1000, Then Ratelimiter sets the rate of 1000 and throws 1000 tokens into the bucket every second.

Com.google.common.util.concurrent.ratelimiter@threadsafe@betapublic Abstract class extends Object

Ratelimiter are often used to limit the rate of access to some physical or logical resources. Compared to Semaphore, Semaphore limits the number of concurrent accesses rather than the usage rate. (Note that concurrency and rate are closely related, such as the reference Little Law)

Define the Ratelimiter by setting the rate of the license. Under the default configuration, the license is assigned at a fixed rate, and the rate is the number of licenses per second. To ensure that the configuration is maintained at a rate, the license is distributed smoothly and the delay between licenses is adjusted.
There may be a case of configuring a ratelimiter with a warm-up period, during which time the number of licenses allocated per second will grow steadily until a steady rate is reached.

For example, how to use ratelimiter, imagine that we need to work on a task list, but we don't want to submit more than two tasks per second:

// rate is two licenses per second Final Ratelimiter Ratelimiter = ratelimiter.create (2.0); void Submittasks (List tasks, Executor Executor) {    for  (Runnable task:tasks) {        //
     may need to wait for         executor.execute (Task);}    }

As another example, imagine that we have created a data stream and want to process it at a rate of 5kb per second. You can do this by requiring each byte to represent a license, and then specifying 5,000 licenses per second:

// 5,000 licenses per second Final Ratelimiter ratelimiter = ratelimiter.create (5000.0void submitpacket (byte[] packet) {    Ratelimiter.acquire (packet.length);    Networkservice.send (packet);}

It is important to note that the requested number of licenses never affects the limits of the request itself (calling acquire (1) and calling acquire (1000) will get the same throttling effect if such a call exists) but will affect the next request limit, that is, If a high-overhead task arrives at an idle ratelimiter, it will be licensed immediately, but the next request will experience additional restrictions to pay for high-overhead tasks. Note: Ratelimiter does not provide a guarantee of fairness.

Since:13.0 Author: Dimitris Andreou

Method Summary

Modifiers and Types	Methods and descriptions
Double	Acquire () Obtaining a license from Ratelimiter, the method is blocked until the request is obtained
Double	Acquire (int permits) Gets the specified number of licenses from Ratelimiter, and the method is blocked until the request is fetched
Static Ratelimiter	Create (double permitspersecond) Creates a ratelimiter based on the specified stable throughput rate, where the throughput is the number of licenses per second (usually the QPS, how many queries per second)
Static Ratelimiter	Create (double Permitspersecond, long warmupperiod, timeunit unit) The Ratelimiter is created based on the specified stable throughput rate and warm-up period, where the throughput rate is the number of licenses per second (usually the QPS, the number of requests per second), during this warm-up period, Ratelimiter the number of licenses allocated per second will grow steadily until the end of the warm-up period to reach its maximum rate. (As long as there are enough requests to saturate it)
Double	Getrate () Returns the rate of stability in the Ratelimiter configuration, which is the number of licenses per second
void	Setrate (double permitspersecond) Update the stability rate of the Ratelimite, the parameter permitspersecond is provided by the factory method that constructs the Ratelimiter.
String	ToString () Returns the character representation of an object
Boolean	Tryacquire () Obtaining a license from Ratelimiter if the license can be obtained immediately without delay
Boolean	Tryacquire (int permits) The number of licenses obtained from Ratelimiter if the number of licenses can be obtained immediately without delay
Boolean	Tryacquire (int permits, long timeout, timeunit unit) Gets the specified number of licenses from Ratelimiter if the number of licenses can be obtained within a timeout period, or if the number of licenses cannot be obtained before timeout expires, return false immediately (no waiting)
Boolean	Tryacquire (long timeout, timeunit unit) Obtaining a license from Ratelimiter if the license can be obtained within a timeout period, or if the permission cannot be obtained before the timeout expires, return false immediately (no waiting)

Methods inherited from the Java.lang.Object class
Clone, Equals, Finalize, GetClass, Hashcode, notify, Notifyall, wait, wait, wait

Method details

Create

public static Ratelimiter Create (double permitspersecond) Creates a ratelimiter based on the specified stable throughput rate, where the throughput is the number of licenses per second (usually the QPS, how many queries per second). The returned ratelimiter ensures in average no more than Permitspersecond is issued during any given second, with Su Stained requests being smoothly spread over each second. When the incoming request rate exceeds Permitspersecond the rate limiter would release one permit every (1.0/permitsperse Cond) seconds. When the rate limiter was unused, bursts of up to permitspersecond permits would be allowed, with subsequent requests being Smoothly limited at the stable rate of permitspersecond. The returned ratelimiter ensures that, on average, the number of licenses released per second will not exceed Permitspersecond, and requests will continue to be sent every second. When the incoming request rate exceeds Permitspersecond, the rate limiter releases one license per second (1.0/permitspersecond here refers to setting the Permitspersecond to 1.0). When the rate limiter is idle, allowing the number of licenses to burst to Permitspersecond, subsequent requests are smoothed to the stable rate permitspersecond. Parameters: The rate of ratelimiter returned by permitspersecond– means that the number of licenses per second becomes valid. Thrown: illegalargumentexception– If the Permitspersecond is negative or 0

Create

public static Ratelimiter Create (double permitspersecond,long warmupperiod,timeunit unit) Creates a ratelimiter based on the specified stable throughput rate and warm-up period, where the throughput rate is the number of licenses per second (usually the QPS, how many queries per second), during this warm-up period, Ratelimiter the number of licenses allocated per second increases steadily until the warm-up period ends at its maximum rate (as long as there are enough requests to saturate). Similarly, if the ratelimiter is idle for warmupperiod time, it will gradually return to the cooling state. In other words, it will experience the same warm-up period as it was created for the first time. The returned ratelimiter are primarily used for resources that require a warm-up period, which actually satisfies a request (such as a remote service) rather than a resource that can be accessed immediately at a steady (maximum) rate. The returned Ratelimiter is started in a cool state (i.e. the warm-up period will follow), and if it is unused for long periods of time, it will return to the cooling state. Parameters: permitspersecond – means that the number of licenses per second becomes valid. warmupperiod – during this time the ratelimiter will increase its rate, before reaching its stable rate or maximum rate of unit – the time unit of the parameter Warmupperiod Thrown: illegalargumentexception– If the Permitspersecond is negative or 0

Setrate

public Final void set Rate (Double permitspersecond) updates the Ratelimite's stable speed, and the parameter permitspersecond  is provided by the factory method that constructs Ratelimiter. When this method is called, the currently restricted threads are not awakened, so they will not notice the latest rate; only the next request will be. It is important to note that because each request is repaid (by waiting, if necessary) the cost of the last request, this means that the next request that is tightly followed is not affected by the latest rate, after the setrate  is called, and the cost of the last request is repaid, which depends on the previous rate. The behavior of Ratelimiter is not changed in any way, for example, if  RateLimiter  has a 20-second warm-up period configuration, it will warm up for 20 seconds after this method is called. parameter: Permitspersecond –ratelimiter new steady rate thrown: illegalargumentexception – if Permitspersecond is negative or 0

Getrate
public final double g The Etrate () Returns the steady rate in the ratelimiter  configuration, which is the number of licenses per second. Its initial value is equivalent to the parameter permitspersecond  in the factory method that constructs the Ratelimiter, and is not updated until the Setrate (double) is called.

Acquire

public double  Acquire () gets a license from Ratelimiter, and the method is blocked until the request is fetched. If there is a wait, tell the caller how long it takes to get the request. This method is equivalent to acquire (1). returns: Time spent sleeping to enforce rates, in seconds; 0.0 if not rate-limited execution rate of the required sleep times, in units of If not, returns 0 Since: 16.0 (version 13.0 has no return value)

Acquire

public double Acquire (int permits) Gets the specified number of licenses from Ratelimiter, and the method is blocked until the number of requests is fetched. If there is a wait, tell the caller how long it will take to get the number of requests. Parameters: permits– number of licenses to be acquired Return: The desired sleep time of the execution rate, the unit is wonderful; if not, return 0 Thrown: illegalargumentexception– if the requested number of licenses is negative or 0 Since: 16.0 (version 13.0 no return value)

Tryacquire

public boolean tryacquire (Long timeout,timeunit unit) Obtaining a license from Ratelimiter if the license can be obtained within a timeout period, or if the permission cannot be obtained before the timeout expires, return false immediately (without waiting). This method is equivalent to Tryacquire (1, timeout, unit). Parameters: timeout– maximum time to wait for a license, minus 0 processing unit– the time unit of the parameter timeout Return: True to obtain a license, and vice versa to False Thrown: illegalargumentexception– if the requested number of licenses is negative or 0

Tryacquire

public boolean  Tryacquire (int permits) obtains the number of licenses from ratelimiter  if the number of licenses can be obtained without delay. This method is equivalent to Tryacquire (permits, 0, anyunit). parameter: permits – number of licenses to obtain returns: True to obtain a license, and vice versa to False Thrown: illegalargumentexception – If the requested number of licenses is negative or 0 Since: 14.0

Tryacquire
public boolean  Tryacquire () obtains a license from ratelimiter  if the license can be obtained immediately without delay. This method is equivalent to Tryacquire (1). returns: True to obtain a license, and vice versa Since: 14.0

Tryacquire

public boolean  Tryacquire (Int permits,long timeout,timeunit unit) from ratelimiter  Gets the specified number of licenses if the number of licenses can be obtained within a timeout period, or if the number of licenses cannot be obtained before the timeout expires, return false  immediately (without waiting). parameter: permits – required number of licenses timeout – the maximum time to wait for a number of licenses, minus 0 processing unit – parameter timeout The time unit returns: True to obtain a license, and vice versa to False thrown: IllegalArgumentException  -if the requested number of licenses is negative or 0

Tostring

Public String toString () The following description is replicated in the Java.lang.Object class. Returns the character representation of an object. In general, the ToString method returns a string that is a "textual rendering" object. The result should be a concise but easy-to-read information expression. It is recommended that all subclasses override this method. The ToString method returns a string consisting of the instance's class name, the character ' @ ', and the hash value of the object in unsigned hexadecimal notation. In other words, the string returned by the method is equivalent to: GetClass (). GetName () + ' @ ' + integer.tohexstring (hashcode ()) Overload: The ToString method of the object class Return: The character representation of an object

Another article:

http://xiaobaoqiu.github.io/blog/2015/07/02/ratelimiter/

Guava Official document-ratelimiter class