Class TokenBucketRateLimiter

java.lang.Object
cloud.opencode.base.parallel.executor.TokenBucketRateLimiter
public final class TokenBucketRateLimiter extends Object
Token Bucket Rate Limiter - Standalone non-blocking rate limiter. 令牌桶限流器 - 独立的非阻塞限流器。

Implements a token bucket algorithm that limits the rate of operations. Unlike RateLimitedExecutor which combines rate limiting with task execution, this class is a pure rate limiter primitive suitable for use in any context — including reactive pipelines, cache access guards, and API throttling.

实现令牌桶算法，限制操作速率。与将限流和任务执行结合在一起的 RateLimitedExecutor 不同， 此类是纯粹的限流原语，适用于任何场景，包括响应式管道、缓存访问保护和 API 限流。

Features | 主要功能:

  • Configurable permits-per-second rate - 可配置的每秒许可速率
  • Non-blocking tryAcquire for single or multiple permits - 非阻塞的单个或多个许可获取
  • Automatic time-based token refill - 基于时间的自动令牌补充
  • Available permit count querying - 可用许可数量查询

Usage Examples | 使用示例:

TokenBucketRateLimiter limiter = TokenBucketRateLimiter.of(1000.0); // 1000 permits/second

if (limiter.tryAcquire()) {
    // proceed with operation
} else {
    // request throttled
}

// Acquire multiple permits for batch operation
if (limiter.tryAcquire(5)) {
    // proceed with batch
}

Performance | 性能特性:

  • AtomicLong CAS for lock-free permit consumption - AtomicLong CAS 用于无锁许可消耗
  • Synchronized refill only when new tokens are available - 仅在有新令牌可用时同步补充
  • O(1) for tryAcquire when permits are available - 许可可用时 tryAcquire 为 O(1)

Security | 安全性:

  • Thread-safe: Yes (AtomicLong + synchronized refill) - 线程安全: 是（AtomicLong + 同步补充）
  • Null-safe: Yes (no nullable parameters) - 空值安全: 是（无可空参数）
Since:
JDK 25, opencode-base-parallel V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

      public static TokenBucketRateLimiter of(double permitsPerSecond)
      Creates a rate limiter with the specified permits per second. 创建具有指定每秒许可数的限流器。
      Parameters:
      permitsPerSecond - the maximum permits per second | 每秒最大许可数
      Returns:
      a new rate limiter | 新的限流器
      Throws:
      IllegalArgumentException - if permitsPerSecond is not positive | 如果 permitsPerSecond 不为正数

    • tryAcquire

      public boolean tryAcquire()
      Tries to acquire a single permit without blocking. 尝试获取单个许可，不阻塞。
      Returns:
      true if a permit was acquired, false if the rate limit is exceeded | 如果获取到许可则返回 true，超出速率限制则返回 false

    • tryAcquire

      public boolean tryAcquire(int permits)
      Tries to acquire the specified number of permits without blocking. 尝试获取指定数量的许可，不阻塞。
      Parameters:
      permits - the number of permits to acquire | 要获取的许可数量
      Returns:
      true if all permits were acquired, false if the rate limit is exceeded | 如果获取到所有许可则返回 true，超出速率限制则返回 false
      Throws:
      IllegalArgumentException - if permits is not positive | 如果 permits 不为正数

    • availablePermits

      public long availablePermits()
      Returns the current number of available permits (after refill). 返回当前可用的许可数量（补充后）。
      Returns:
      the available permits | 可用的许可数量

    • getPermitsPerSecond

      public double getPermitsPerSecond()
      Returns the configured permits per second. 返回配置的每秒许可数。
      Returns:
      the permits per second | 每秒许可数

    • getMaxPermits

      public long getMaxPermits()
      Returns the maximum bucket capacity (equal to permitsPerSecond rounded down, minimum 1). 返回最大桶容量（等于 permitsPerSecond 向下取整，最小为 1）。
      Returns:
      the maximum permits in the bucket | 桶中的最大许可数

    • toString

      public String toString()
      Overrides:
      toString in class Object