kresil-lib/kresil.ratelimiter.semaphore.implementations/TokenBucketSemaphoreBasedRateLimiter

TokenBucketSemaphoreBasedRateLimiter

internal class TokenBucketSemaphoreBasedRateLimiter(val config: RateLimiterConfig, val semaphoreState: SemaphoreState) : SemaphoreBasedRateLimiter(source)

A counting suspendable Semaphore based implementation of a rate limiter that uses the Token Bucket algorithm to control the number of permits available for requests. The Token Bucket algorithm allows for a smoother distribution of requests over time, compared to the fixed window counter algorithm. Tokens are added to the bucket at a constant rate, up to a maximum capacity, and each request consumes a certain number of tokens. If there are insufficient tokens for a request, the request is either queued or rejected based on the configuration.

Considerations

The Token Bucket algorithm helps prevent bursts of requests and provides a more even distribution of traffic. It can be more effective than the fixed window counter algorithm in scenarios with fluctuating traffic patterns.

Parameters

config

The configuration for the rate limiter mechanism.

semaphoreState

The state of the semaphore which includes an internal in-memory queue to store the excess requests.

See also

Throws

if the coroutine is cancelled while waiting for the permits to be available.

if the request is rejected due to the queue being full or the acquisition timeout being exceeded.

Constructors

Link copied to clipboard
constructor(config: RateLimiterConfig, semaphoreState: SemaphoreState)

Properties

Link copied to clipboard
Link copied to clipboard
private val config: RateLimiterConfig
Link copied to clipboard
Link copied to clipboard
private val lock: Mutex
Link copied to clipboard
private val permitsInUse: Int
Link copied to clipboard
Link copied to clipboard

Functions

Link copied to clipboard
open suspend override fun acquire(permits: Int, timeout: Duration)

Acquires n permits from the semaphore or suspends for the specified timeout if the permits are not available.

Link copied to clipboard
protected open override fun calculateRetryDuration(permits: Int): Duration

Calculates the duration after which the request can be retried. The retry duration depends on the rate limiting algorithm, the current state of the semaphore and the number of permits requested. For example, a token bucket algorithm may return a retry duration based on the time left until the requested permits are available (which may not happen in the next replenishment period).

Link copied to clipboard
private fun createRateLimitedException(permits: Int): RateLimiterRejectedException

Creates a RateLimiterRejectedException with the appropriate retry duration.

Link copied to clipboard
private suspend fun handleExceptionAndCleanup(observedRequestNode: Node<RateLimitedRequest>?, exception: Exception)

Deals with the caught exception while maintaining the integrity of the semaphore state.

Link copied to clipboard
private fun isRateLimited(permits: Int): Boolean

Determines if the request should be rate limited based on the current state of the semaphore.

Link copied to clipboard
open suspend override fun release(permits: Int)

Releases n permits back to the semaphore.

Link copied to clipboard
protected open suspend override fun replenishSemaphoreState()

Depending on the rate limiting algorithm, this function is responsible for replenishing the semaphore state. For example, a fixed window counter algorithm may reset the permits to zero at the end of the window. And a token bucket algorithm may refill the bucket with tokens at a constant rate.

Link copied to clipboard
protected open fun updateSemaphoreStatePermits(updateFunction: (Int) -> Int)

Updates the number of permits in the semaphore state.