limiter.go

package equalizer

import "context"

// A token represents a single unit of capacity for the rate limiter.
type token struct{}

// Limiter represents a rate limiter.
//
// Rate limiters control the rate at which requests are processed by allocating
// a certain number of tokens. Each token represents the ability to process a
// single request. When a request is made, the limiter checks if there are any
// available tokens. If there are, it deducts one token and allows the request
// to proceed. If there are no tokens available, the request is blocked until a
// token becomes available.
//
// By controlling the number of tokens available, rate limiters can ensure that
// requests are processed at a controlled rate, preventing overloading and
// ensuring fair access to resources.
type Limiter interface {
	// Acquire blocks the calling goroutine until a token is acquired, the Context
	// is canceled, or the wait time exceeds the Context's Deadline.
	Acquire(ctx context.Context) error
	// TryAcquire attempts to acquire a token without blocking.
	// Returns true if a token was acquired, false if no tokens are available.
	TryAcquire() bool
}