Standard Token Bucket Terminology

P.F. Chimento
May 18, 2000

1 The Token Bucket Model

This document tries to explain standard token bucket terminology and to give an example of how the
token bucket works as a shaper (generator) of a stream with particular characteristics and as a policer of
a stream with particular characteristics.
First, a picture (See Figure 1): The operation of the bucket is as follows: Data flows into the mecha-

X
Simple Token Bucket Configuration
Figure 1: A simple Token Bucket

nism from the left in quanta called packets. Token flow into the bucket (green) from the top at rate γ.
When the bucket is full of tokens, new tokens are thrown away. Each token is worth a defined number of
bytes. It is easier if we think of each token as being worth one byte.
When a packet arrives from the left, if there are a number of tokens in the bucket at least equal to
the number of bytes in the packet, the packet may exit the system immediately. If there are not enough
tokens in the bucket, then one of a number of things may happen, depending on how the token bucket is
being used:
1. The packet may be thrown away.
2. The packet may be marked in a particular way.
3. The packet may be buffered (by inserting a buffer between the inflow and the decision point) and
not released until a sufficient number of tokens arrive in the bucket.
There are a number of things to note about this picture:
1. The rate γ is the long-term rate at which the data flows out of the bucket.
2. The bucket depth τ is the maximum amount of information that can flow out of the bucket back-
to-back (i.e. with arbitrary spacing).

1
 3. When the bucket is being used as a shaper, the outflow rate is usually termed the peak rate which
can in fact be much faster than the rate denoted by γ. This rate can be controlled to be a particular
rate β by inserting another buffer/decision point after the token bucket. If no special notations or
adjustments are made, β is assumed to be the physical line rate of the output link.
You can think of γ as the sustained rate at which the data can exit the token bucket system and you
can think of τ as the size of the burst which can flow out of the system at the peak rate β.
Note that the device has a memory by reason of the bucket.

2 Relationship to “QPS Traffic Conditioning”

The token bucket model provides standard terminology for describing the behaviour of a traffic source.
Thoudh it is not clearly stated in [1], I assume that we are talking about the use of the token bucket as a
shaper for an aggregate. Because of this assumption, we would have to add a shaping buffer to Figure 1
in front of the decision point.
It should be clear from the above description that bucket depth τ is the same as what is intended in
[1] by the term “MTU”. However, this appropriation of the term “MTU” is confusing because it conflicts
with the generally accepted definition of “MTU” and I recommend that its use be abandoned.
The definition of “peakRate” in [1] is captured by the token bucket rate, γ as defined above.
Because of the memory (i.e. the bucket) in the model, there is no need for the auxillary definitions in
[1]. Specifically, TMT U as defined in [1] is unnecessary because the token bucket bounds the amount of
data that can be transmitted in any given interval. Given an interval of length δ seconds, and an initial
bucket content of B bits, the maximum flow from the bucket into the network is δ × γ + B bits. This
assumes that β, the exit rate (also known as the peak rate, not equivalent to “peakRate” as defined in
[1]) is (much) faster than γ. Note that as δ → ∞, the maximum flow into the network from the token
bucket approaches δ × γ.
Because the token bucket is defined in terms of bytes, it is independent of packet size and so the
parameter “PacketSize” is not needed. The parameter “BurstSize” as defined in [1] is actually harmful
because it may limit the number of packets transmitted if they are smaller than “PacketSize”.

3 Proposal
In order to keep to more or less accepted terminology and concepts, I suggest that the token bucket model,
as described in [2] for example, be adopted as the traffic descriptor for QPS and for the Bandwidth Broker
design. Further, I think that a good model for us is the TSPEC as described in [4] and [3]. These RFCs
have good descriptions of the parameters necessary to describe traffic streams in terms of token buckets.
If this proposal is accepted, we can work out some detailed definitions and format descriptions.

References
[1] Rüdiger Geib, QPS Traffic Conditioning, unpublished working document, May 2000

[2] Craig Partridge, Gigabit Networking, Addison Wesley Publishing, 1994

[3] J. Wroclawski, Specification of Controlled-Load Network Element Service, RFC 2211, September
1997
[4] S. Shenker, C. Partridge, R. Guérin, Specificatino of Guaranteed Quality of Service, RFC 2212,
September 1997