I'm calling an external REST API that is rate limited to a number of requests per second. Any more than that and an HTTP failure is returned indicting that the requests per second threshold has been exceeded.
While I do want my code to be resilient against the HTTP failure should it occur, it occurs to me that rate limiting my calls to the API would effectively eliminate these failing calls.
I see that Guava provides a RateLimiter class which is designed to limit the rate of requests using it.
The create(double unitsPerSecond) method seems to be pretty much what I want:
Creates a
RateLimiterwith the specified stable throughput, given as "permits per second" (commonly referred to as QPS, queries per second).The returned
RateLimiterensures that on average no more thanpermitsPerSecondare issued during any given second, with sustained requests being smoothly spread over each second. When the incoming request rate exceedspermitsPerSecondthe rate limiter will release one permit every(1.0 / permitsPerSecond)seconds. When the rate limiter is unused, bursts of up topermitsPerSecondpermits will be allowed, with subsequent requests being smoothly limited at the stable rate ofpermitsPerSecond.
The bursting behavior matches my ideal behavior: if the rate is limited to 10/second and I want to make 5 requests after a period of inactivity, I would like those 5 to occur without artificial delay in between them.
One thing that is not clear to me about this class, after reading through the Javadocs: does the Guava rate limiter guarantee that for a given 1-second window, no more than unitsPerSecond calls will be allowed to occur, assuming that permits are only acquired one at a time (e.g. using acquire(1))?
The language "The returned RateLimiter ensures that on average no more than permitsPerSecond are issued during any given second" seems to indicate that there's no guarantee that a given second won't go over rate.
My goal is to never make more than permitsPerSecond calls to the external REST service in any given 1-second window. Will the Guava RateLimiter ensure this?