Module bucket 

The token bucket — configuration, state, and the one pure function that decides whether a unit may go now.

charge takes now as a parameter and reads no clock, following release_timer::plan(now, next, slice). That is the whole reason the exact rate claim is provable: the arithmetic is a function of fabricated Instants, so the_bucket_never_grants_above_rate_plus_burst is a +-0 % assertion over ten thousand steps rather than a measurement that machine load can move.

Units

rate_bps is bytes per second, paired with burst_bytes and with the bytes argument to charge. Everything the scheduler counts is a byte count, and mixing a bit rate into a byte accounting would put a factor of eight between the configuration and every statistic that reports against it. A bit rate is rate_bps * 8.

Why the arithmetic is scaled

Tokens are held in nano-bytes (u128), one byte being a thousand million nano-bytes, and refills are computed from elapsed nanoseconds. An unscaled byte counter would round every sub-byte refill to zero and a bucket paced faster than one byte per nanosecond would drift low without any test noticing; u128 removes the overflow question entirely rather than documenting a ceiling nobody would check.

Structs

BucketConfig

A named token bucket. One per class, or shared by several.

BucketState

The mutable half of a token bucket: what it holds and when it was last refilled.

Enums

Grant

What charge decided about one unit.

Constants

NANO 🔒

Nano-bytes per byte, and equally nanoseconds per second — the two are the same constant because a bucket accumulating rate bytes per second accumulates exactly rate nano-bytes per nanosecond.

Functions

charge

Charge bytes against a bucket and say whether the unit may go.