Expand description
SharedRateLimiter - cross-process token-bucket rate limiter.
Tokens accumulate at a configured rate up to a configured
capacity; acquire(n) atomically deducts n tokens or returns
Err(InsufficientTokens). Refill happens lazily on each
acquire - no background thread needed.
§Layout
Single MMF file:
+---------------------------+
| RateLimiterHeader (64B) |
| magic, capacity |
| refill_rate_per_sec |
| state: AtomicU64 | // packed (tokens, refill_us_low)
+---------------------------+§Packed state
The hot atomic packs (tokens_remaining: u32, last_refill_us_low: u32)
into one u64. Updates are CAS-only so multiple processes
concurrently acquiring don’t race-update either field
independently.
tokens_remaining(low 32 bits) supports capacities up to ~4B tokens; well past any realistic rate-limit budget.last_refill_us_low(high 32 bits) holds the low 32 bits of the wall-clock-microsecond timestamp at the last refill. Low 32 bits give a 4295-second (~71 minute) window before wrap-around, which is FAR longer than any acquire-to-acquire gap in practice. Wrap-around handles correctly via wrapping subtraction.
§Refill on acquire
Each acquire(n) first computes how many tokens should have
been refilled since the last refill: elapsed_us * refill_rate_per_sec / 1_000_000. The new token count is
min(current + refilled, capacity). Then n is subtracted; if
the result goes negative, the acquire fails without
modifying state.