org.spf4j.failsafe

Class RateLimiter

java.lang.Object

org.spf4j.failsafe.RateLimiter

All Implemented Interfaces:

AutoCloseable, PermitSupplier

@Beta
public final class RateLimiter
extends Object
implements AutoCloseable, PermitSupplier

Token bucket algorithm base call rate limiter. see https://en.wikipedia.org/wiki/Token_bucket for more detail. Unlike the Guava implementation, the token replenishment is done in a separate thread. As such permit acquisition methods have lower overhead (no System.nanotime invocation is made when permits available), This lower overhead comes at the cost of increasing the cost of RateLimiter object instance. (a scheduled runnable) This implementation also uses CAS to update the permit bucket which should yield better concurrency characteristics. there is a backoff to handle high contention better as well (see https://dzone.com/articles/wanna-get-faster-wait-bit) The different in performance can be observed in a benchmark where we try to limit 10000000 ops/s: Benchmark Mode Cnt Score Error Units com.google.common.util.concurrent.GuavaRateLimiterBenchmark.acquire thrpt 10 8197739.576 ± 163437.214 ops/s org.spf4j.failsafe.Spf4jRateLimiterBenchmark.acquire thrpt 10 9791489.540 ± 89480.010 ops/s The Guava implementation cannot really get as close to the desired rate as the spf4j implementation. The spf4j implementation tops of at about: Benchmark Mode Cnt Score Error Units Spf4jRateLimiterBenchmark.acquire thrpt 10 15270385.653 ± 507217.444 ops/s these benchmarks are artificial and really measure the overhead of permit acquisition alone without doing anything else, real use cases will accompany a permit acquision with some work which impacts the CAS/lock acquisition perf... Rate Limiter also implements the PermitSupplier abstraction along with GuavaRateLimiter allowing interchangeability between the 2 implementations based on what trade-of work better for you. PermitSupplier allows interchangeability and combination with Semaphore (extends PermitSupplier) implementations.

Author:

Zoltan Farkas

Constructor Summary

Constructors

Constructor and Description
RateLimiter(double maxReqPerSecond, int maxBurstSize)
RateLimiter(double maxReqPerSecond, int maxBurstSize, long minReplenishIntervalMillis)
RateLimiter(double maxReqPerSecond, int maxBurstSize, long minReplenishIntervalMillis, ScheduledExecutorService scheduler, LongSupplier nanoTimeSupplier)
RateLimiter(double maxReqPerSecond, int maxBurstSize, long minReplenishIntervalMillis, ScheduledExecutorService scheduler, LongSupplier nanoTimeSupplier, int concurrencyLevel)
RateLimiter(double maxReqPerSecond, int maxBurstSize, ScheduledExecutorService scheduler)
RateLimiter(double maxReqPerSecond, int maxBurstSize, ScheduledExecutorService scheduler, LongSupplier nanoTimeSupplier)

Method Summary

Modifier and Type	Method and Description
void	close()
long	getLastReplenishmentNanos()
double	getNrPermits()
long	getPermitReplenishIntervalMillis()
double	getPermitsPerReplenishInterval()
String	toString()
boolean	tryAcquire() Try to acquire a permit if available.
boolean	tryAcquire(int nrPermits)
boolean	tryAcquire(int nrPermits, long deadlineNanos)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.spf4j.concurrent.PermitSupplier

acquire, acquire, toSemaphore, tryAcquire, tryAcquire

Constructor Detail

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize,
                   long minReplenishIntervalMillis)

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize)

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize,
                   ScheduledExecutorService scheduler)

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize,
                   ScheduledExecutorService scheduler,
                   LongSupplier nanoTimeSupplier)

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize,
                   long minReplenishIntervalMillis,
                   ScheduledExecutorService scheduler,
                   LongSupplier nanoTimeSupplier)

RateLimiter

public RateLimiter(double maxReqPerSecond,
                   int maxBurstSize,
                   long minReplenishIntervalMillis,
                   ScheduledExecutorService scheduler,
                   LongSupplier nanoTimeSupplier,
                   int concurrencyLevel)

Method Detail

tryAcquire

public boolean tryAcquire()

Try to acquire a permit if available.

Returns:

true if permit acquired. false otherwise.

tryAcquire

public boolean tryAcquire(int nrPermits)

getNrPermits

public double getNrPermits()

tryAcquire

public boolean tryAcquire(int nrPermits,
                          long deadlineNanos)
                   throws InterruptedException

Specified by:

tryAcquire in interface PermitSupplier

Throws:

InterruptedException

close

public void close()

Specified by:

close in interface AutoCloseable

getPermitsPerReplenishInterval

public double getPermitsPerReplenishInterval()

getPermitReplenishIntervalMillis

public long getPermitReplenishIntervalMillis()

getLastReplenishmentNanos

public long getLastReplenishmentNanos()

toString

public String toString()

Overrides:

toString in class Object