Performance

Performance and Design

BucketGuard is designed for minimal overhead.

Generic Cell Rate Algorithm (GCRA)

BucketGuard does not use a "thread that adds tokens". Instead, it uses the GCRA.

GCRA is a leaky bucket variant that tracks a "Theoretical Arrival Time" (TAT).

• Zero Allocations: State is managed in a single long (timestamp). Checking a limit involves reading the current time and performing basic arithmetic. No objects are created on the hot path.
• O(1) Complexity: The cost of a check is constant, regardless of the capacity or refill rate.

Memory Efficiency

• Atomic Buckets: A standard bucket consumes only the memory of an AtomicLong and a reference to its spec.
• Keyed Storage: When using EXPIRE_AFTER_ACCESS, BucketGuard uses specialized map values to track access times without checking separate "last accessed" objects, keeping heaps small even with millions of keys.

Thread Safety

• Lock-Free: The core AtomicBucket is completely lock-free, using VarHandle CAS operations.
• Striping: For standard limiters, striping effectively shards the lock contention.
• Keyed Access: Keyed limiters use ConcurrentHashMap for NONE eviction policies, providing non-blocking reads and writes. For LRU and EXPIRE policies, a lightweight synchronized wrapper ensures correctness of the eviction order with minimal overhead.