Class AbstractRateLimiter<T>

java.lang.Object
ai.redouble.nucleo.harness.admission.AbstractRateLimiter<T>
Type Parameters:
T - the amount type
All Implemented Interfaces:
LimiterIdentity, RateLimiter<T>
Direct Known Subclasses:
CountingGate, ElasticWindowRateLimiter, MemoryPressureGate, TokenBucketRateLimiter
public abstract class AbstractRateLimiter<T> extends Object implements RateLimiter<T>, LimiterIdentity
Base class for accounts that are their own identity: the wake slot Admission installs, the RateLimiter.Replenishment.RELEASE default that fits every capacity gate built directly on this class, and the nominal (null) status indicator.

Emission and waiter counting are not here. Admission owns the wait, so it owns the LimiterEvents that describe it; an account only reports its identity and moves its counters.

The two time-based families override replenishment(): ElasticWindowRateLimiter, whose override is final so none of its per-service subclasses can drift, and TokenBucketRateLimiter. A new limiter whose permits return with the clock rather than with the work must override too.

Since:
0.1 (2026-04-14)
Author:
Andrey Santrosyan

  • Constructor Details

    • AbstractRateLimiter

      public AbstractRateLimiter()

  • Method Details

    • onCapacityChange

      public void onCapacityChange(Runnable wake)
      Description copied from interface: RateLimiter
      Installs the single wake this account runs after any self-change that can only increase capacity: a throttle relaxation, a cap raised from headers, a circuit closing, a pushed fleet allotment. The wake is a bare unpark of the admission evaluator and never re-enters an account or the monitor, so it may be run from anywhere, under any lock. null clears the slot. Decreases never wake anyone.
      Specified by:
      onCapacityChange in interface RateLimiter<T>

    • capacityChanged

      protected final void capacityChanged()
      Runs the installed wake, if any. Subclasses call this after a self-change that can only increase capacity. The wake is a bare unpark and safe to run under any lock.

    • accountFor

      public LimiterIdentity accountFor(T amount)
      Description copied from interface: RateLimiter
      The identity the given amount debits: this limiter for a plain account, the routed bucket for a router. Head reservation, waiter counts and events all key on it.
      Specified by:
      accountFor in interface RateLimiter<T>

    • replenishment

      public RateLimiter.Replenishment replenishment()
      Defaults to RateLimiter.Replenishment.RELEASE, which is what a permit means for the capacity gates built directly on this class - a semaphore slot, a pooled connection, heap headroom. All of those are genuinely free again when the work ends.
      Specified by:
      replenishment in interface RateLimiter<T>

    • statusIndicator

      public String statusIndicator()
      Description copied from interface: LimiterIdentity
      Short human-readable tag describing an abnormal operational state of this account: "blocked", "probing", "throttle:2.0x", "pace:1500ms". Returns null when the account is in its nominal state. Consumers surface it alongside capacity and in-use so an out-of-sorts account is visible even when its numeric columns look calm.
      Specified by:
      statusIndicator in interface LimiterIdentity