Class RateLimiter

java.lang.Object
com.loomcache.server.ratelimit.RateLimiter
public class RateLimiter extends Object
Token bucket rate limiter with thread-safe non-blocking and blocking acquisition modes. Uses System.nanoTime() for precise token refill timing. Tracks comprehensive statistics on permit acquisition.

  • Constructor Details

    • RateLimiter

      public RateLimiter(RateLimiter.RateLimiterConfig config)
      Initialize rate limiter with configuration.
      Parameters:
      config - the rate limiter configuration (must not be null)

  • Method Details

    • tryAcquire

      public boolean tryAcquire()
      Non-blocking attempt to acquire a single permit. Returns true if a permit was available, false otherwise.

    • tryAcquire

      public boolean tryAcquire(int permits)
      Non-blocking attempt to acquire multiple permits. Returns true if all permits were available, false otherwise.
      Parameters:
      permits - the number of permits to acquire
      Returns:
      true if permits were acquired, false otherwise
      Throws:
      IllegalArgumentException - if permits invalid input: '<'= 0

    • acquire

      public void acquire()
      Blocking acquisition of a single permit. Waits indefinitely until a permit becomes available.

    • acquire

      public boolean acquire(Duration timeout)
      Blocking acquisition of a single permit with timeout. Returns true if permit was acquired, false if timeout occurred.

    • acquire

      public boolean acquire(int permits, Duration timeout)
      Blocking acquisition of multiple permits with timeout. Returns true if all permits were acquired, false if timeout occurred.

    • getAvailableTokens

      public long getAvailableTokens()
      Get the current number of available tokens (for testing/monitoring).

    • getAvailablePermits

      public long getAvailablePermits()
      Get the number of available permits.

    • reset

      public void reset()
      Reset the rate limiter to its initial state. Clears all statistics and refills tokens to the burst size.

    • getStatistics

      public RateLimiter.RateLimiterStats getStatistics()
      Get comprehensive statistics for this rate limiter.

    • getTotalAllowed

      public long getTotalAllowed()
      Get the total number of acquisition attempts that were allowed.

    • getTotalDenied

      public long getTotalDenied()
      Get the total number of acquisition attempts that were denied.

    • getDenyRate

      public double getDenyRate()
      Get the current deny rate (denied / (allowed + denied)).

    • tryAcquireWithWait

      public boolean tryAcquireWithWait(long timeoutMillis)
      Try to acquire a single permit with a timeout in milliseconds. Returns true if a permit was acquired within the timeout, false otherwise.

    • getRemainingPermits

      public long getRemainingPermits()
      Get the number of remaining permits available in the current window.

    • getTimeUntilNextPermit

      public long getTimeUntilNextPermit()
      Get the time in milliseconds until the next permit becomes available. Returns 0 if permits are already available.

    • burst

      public boolean burst(int permits)
      Try to acquire multiple permits at once (burst acquisition). Returns true if all permits were acquired, false otherwise.

    • setRate

      public void setRate(double permitsPerSecond)
      Dynamically change the rate limit. Updates the permitsPerSecond and recalculates nanosecondsPerPermit. Preserves current token count. Note: config.permitsPerSecond() retains the original value; use getEffectiveRate() to retrieve the current rate after calling setRate().

    • getEffectiveRate

      public double getEffectiveRate()
      Get the current effective rate, which may differ from config.permitsPerSecond() if setRate() has been called.
      Returns:
      the effective permits per second

    • snapshot

      public RateLimiter.RateLimiterSnapshot snapshot()
      Get a snapshot of the current rate limiter state.