com.devexperts.qd.util

Class RateLimiter

java.lang.Object

com.devexperts.qd.util.RateLimiter

@Internal
public class RateLimiter
extends Object

Token bucket rate limiter implementation for controlling throughput.

This implementation uses a token bucket algorithm to control the rate of operations:

• Tokens are added to the bucket at a fixed rate (the configured rate limit)
• Each operation consumes one or more tokens from the bucket
• Operations are blocked when insufficient tokens are available
• The bucket has a maximum capacity, allowing for controlled bursts

The bucket capacity is determined by the amortization limit parameter, which defines how much "credit" can be accumulated during idle periods. This allows the system to compensate for pauses by temporarily working at a maximum rate, up to the bucket capacity.

Example: With a rate of 100 tokens/sec and 2s amortization limit:

• Tokens are added at 100/sec continuously
• The bucket can hold up to 200 tokens (100 tokens/sec × 2 seconds)
• After a 2-second idle period, 200 operations can be performed immediately
• The long-term average rate cannot exceed 100 operations/sec

Note: This class is not thread-safe.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIG_UNLIMITED
static RateLimiter	UNLIMITED A rate limiter implementation that imposes no limits on operations.

Method Summary

Modifier and Type	Method and Description
long	available() Returns the number of tokens available for processing at the specified time.
long	availableOrWait() Waits if necessary until at least one token becomes available, then returns the number of tokens available for immediate processing.
void	consume(long tokens) Consumes the specified number of tokens from the rate limiter, blocking if necessary until the tokens become available.
boolean	equals(Object o)
int	hashCode()
boolean	needWait() Checks whether the current thread needs to wait to maintain the rate limit.
static RateLimiter	of(double rate) Creates a rate limiter with the specified rate limit and default amortization limit (1 second).
static RateLimiter	of(double rate, com.devexperts.util.TimePeriod amortizationPeriod) Creates a rate limiter with the specified parameters.
static RateLimiter	ofBucket(long bucketSize, long refillPeriodNanos) Creates a rate limiter with the specified token bucket parameters.
void	reportConsumed(long tokens) Updates the rate limiter after tokens have been processed.
String	toString()
static RateLimiter	valueOf(String config) Creates a rate limiter from a configuration string.
long	waitTime() Returns the number of milliseconds that the caller should wait to maintain the rate limit.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

CONFIG_UNLIMITED

public static final String CONFIG_UNLIMITED

See Also:

Constant Field Values

UNLIMITED

public static final RateLimiter UNLIMITED

A rate limiter implementation that imposes no limits on operations. This implementation never requires waiting and always reports maximum availability.

Method Detail

valueOf

public static RateLimiter valueOf(String config)

Creates a rate limiter from a configuration string.

Special cases:

• null, empty string, or "UNLIMITED" (case-insensitive) - returns the UNLIMITED implementation

Configuration format: <rate>[;<bucket>]

• <rate> - tokens per second, supports fractional values and unit prefixes (required):
  • SI prefixes (powers of 1000): k (10³), M (10⁶), G (10⁹)
  • IEC prefixes (powers of 1024): Ki (2¹⁰), Mi (2²⁰), Gi (2³⁰)
• <bucket> - bucket time period or amortization limit (optional, default: 1s). This represents the maximum accumulated pause that the rate limiter can compensate by working at maximum rate.

Examples:

• "100" - 100 tokens/sec, 1s bucket (100 tokens)
• "0.5;2s" - 0.5 tokens/sec, 2s bucket (one token)
• "0.5k" - 500 tokens/sec, 1s bucket (500 tokens)
• "0.5ki" - 512 tokens/sec, 1s bucket (512 tokens)
• "1M" - 1,000,000 tokens/sec, 1s bucket (1,000,000 tokens)
• "1Mi" - 1,048,576 tokens/sec, 1s bucket (1,048,576 tokens)
• "1000;0.5s" - 1,000 tokens/sec, 0.5s bucket (500 tokens)

Parameters:

config - the configuration string (may be null)

Returns:

a new rate limiter configured according to the specification, or UNLIMITED for null/empty/"UNLIMITED" strings

Throws:

IllegalArgumentException - if the configuration format is invalid

of

public static RateLimiter of(double rate)

Creates a rate limiter with the specified rate limit and default amortization limit (1 second).

Parameters:

rate - the sustained rate limit in tokens per second

Returns:

a new rate limiter with a default amortization limit (1 second)

Throws:

IllegalArgumentException - if the rate limit is not positive

of

public static RateLimiter of(double rate,
                             com.devexperts.util.TimePeriod amortizationPeriod)

Creates a rate limiter with the specified parameters.

Parameters:

rate - the sustained rate limit in tokens per second

amortizationPeriod - the time period for bucket capacity calculation

Returns:

a new rate limiter with the specified parameters

Throws:

IllegalArgumentException - if any parameter is not positive

ofBucket

public static RateLimiter ofBucket(long bucketSize,
                                   long refillPeriodNanos)

Creates a rate limiter with the specified token bucket parameters.

Parameters:

bucketSize - the maximum number of tokens the bucket can hold (burst capacity)

refillPeriodNanos - the time period in nanoseconds for refilling the bucket to its full capacity

Returns:

a new rate limiter with the specified bucket parameters

Throws:

IllegalArgumentException - if bucketSize or refillPeriodNanos is not positive

needWait

public boolean needWait()

Checks whether the current thread needs to wait to maintain the rate limit.

Returns:

true if the thread needs to wait, false otherwise

waitTime

public long waitTime()

Returns the number of milliseconds that the caller should wait to maintain the rate limit. This method does not block the current thread.

Returns:

the number of milliseconds that the caller should wait, or 0 if no waiting is necessary

availableOrWait

public long availableOrWait()
                     throws InterruptedException

Waits if necessary until at least one token becomes available, then returns the number of tokens available for immediate processing.

This method blocks if no tokens are currently available, waiting until the rate limiter refills enough to provide at least one token. Once a token is available, it returns the total number of tokens that can be consumed immediately.

Returns:

the number of tokens available for immediate processing (at least 1)

Throws:

InterruptedException - if the current thread is interrupted while waiting

available

public long available()

Returns the number of tokens available for processing at the specified time.

Returns:

the number of tokens available for processing at the specified time

consume

public void consume(long tokens)
             throws InterruptedException

Consumes the specified number of tokens from the rate limiter, blocking if necessary until the tokens become available.

Parameters:

tokens - the number of tokens to consume (must be non-negative)

Throws:

IllegalArgumentException - if tokens are negative

InterruptedException - if the current thread is interrupted while waiting

reportConsumed

public void reportConsumed(long tokens)

Updates the rate limiter after tokens have been processed.

Parameters:

tokens - the number of tokens that were processed (must be non-negative)

Throws:

IllegalArgumentException - if tokens are negative

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object