rate_limiter

sqllocks_spindle.streaming.rate_limiter

Token-bucket rate limiter with Poisson inter-arrival time support.

Classes

TokenBucket

Token bucket rate limiter.

Tokens accumulate at rate tokens per second, capped at burst_capacity. Each call to :meth:consume deducts one token. If no token is available, the caller should wait the returned duration before emitting the next event.

Parameters:

Name	Type	Description	Default
rate	float	Target events per second.	required
burst_capacity	float | None	Maximum tokens that can accumulate. Defaults to 2 * rate (allows brief bursts without stalling).	None
clock	Callable[[], float] | None	Monotonic time function — injectable for testing.	None

Methods:

update_rate(rate)

Update the token accumulation rate.

consume()

Consume one token.

Returns:

Type	Description
float	0.0 if a token was available immediately, otherwise the number of
float	seconds the caller should sleep before the next token arrives.

wait_and_consume()

Block until a token is available, then consume it.

Functions:

poisson_interarrival(rate, rng)

Draw a single inter-arrival time from the exponential distribution.

In a Poisson process inter-arrival times are Exponentially distributed with mean 1 / rate. This produces realistic arrival jitter rather than perfectly uniform spacing.

Parameters:

Name	Type	Description	Default
rate	float	Expected events per second (must be > 0).	required
rng		numpy.random.Generator instance.	required

Returns:

Type	Description
float	Seconds to wait before emitting the next event.