the token bucket

Imagine a toll booth that hands out one entry token every fixed interval, dropping them into a basket that can hold at most, say, twenty. A car may pass only if it can grab a token from the basket. If the road has been empty, tokens pile up to twenty, so when a convoy arrives, up to twenty cars can pass back-to-back in a burst — but after that, cars can only go as fast as new tokens drip in. The token bucket is this scheme for packets: it controls a flow's long-run average rate while deliberately permitting bursts up to a fixed limit.

Mechanically, tokens are added to a bucket at a steady rate r (say one token per millisecond), and the bucket holds at most b tokens. To send a packet, the flow must remove one token (a refinement charges tokens per byte). If tokens are present, the packet goes immediately and a token is consumed; if the bucket is empty, the packet must wait (in a shaper) or be dropped/marked (in a policer). The two parameters give you precise control: r caps the sustained average rate, and b caps the maximum burst — the most packets that can be sent instantly after an idle period. This is exactly what real traffic wants: a sender that has been quiet can briefly catch up, but cannot exceed its average over the long haul.

Why it matters: the token bucket is the workhorse behind both traffic policing and traffic shaping, the standard way a network describes and enforces a flow's allowed behavior ('this class may average 10 Mbps with bursts up to 1 megabit'). It is more useful than the pure leaky bucket precisely because it tolerates the burstiness real applications produce, while still bounding it. The honest distinction to keep straight: a leaky bucket forces a perfectly constant output (no burst); a token bucket caps the average but allows a controlled burst up to b. Same family of idea, but the token bucket's bounded-burst flexibility is why it dominates in practice.