FAQ

Frequently Asked Questions

General

Why use BucketGuard instead of Guava RateLimiter?

• Zero Dependencies: Guava is a large library; BucketGuard is lightweight and dependency-free.
• Garbage Free: BucketGuard's GCRA implementation creates zero objects on the hot path.
• Features: BucketGuard supports Keyed limits (millions of buckets), async acquisition, and strict math out of the box.

Why use BucketGuard instead of Resilience4j?

Resilience4j is an excellent fault-tolerance library. Use BucketGuard if you specifically need a standalone, high-performance rate limiter without the full suite of circuit breakers and bulkheads, or if you need to manage a very large number of keys (e.g., per-user limits) efficiently.

Technical

Does this support distributed rate limiting (e.g., Redis)?

No. BucketGuard is an in-memory, local rate limiter. If you need distributed rate limiting across a cluster, you must use an external store like Redis. Standard BucketGuard runs independently on each JVM. Pattern: You can deploy BucketGuard on each node and configure the limit to be TotalLimit / NodeCount (assuming even load balancing).

Is it thread-safe?

Yes. All implementations are thread-safe.

• Global Limiters: Safe for concurrent access from any number of threads.
• Keyed Limiters: Safe for concurrent access to the same or different keys.

Why Java 21?

BucketGuard utilizes modern Java features, and it's generally just time that people move away from older Java versions.

How does expireAfterAccess work?

It is a passive expiration policy. Keys are checked for expiration only when they are accessed (read/write) or when you explicitly call prune(). It does not run a background thread automatically unless you use startMaintenance().