[#util-TokenBucket]
= xref:util.adoc[util]::TokenBucket
:relfileprefix: ../
:mrdocs:

A token bucket rate limiter.

== Synopsis

Declared in `<util/tokenbucket.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<typename Clock>
class TokenBucket;
----

== Description

Tokens are added at a steady rate (m_rate per second) up to a capacity cap (m_cap). Tokens are removed by calling decrement(), which returns false if the bucket is emptied.

Typical usage: bucket.increment(now); // refill based on elapsed time if (bucket.value() >= 1) bucket.decrement(1); // consume a token

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:util/TokenBucket/clock.adoc[`clock`] 
| The clock type used to measure elapsed time.
| xref:util/TokenBucket/duration.adoc[`duration`] 
| The clock's duration type.
| xref:util/TokenBucket/time_point.adoc[`time_point`] 
| The clock's point‐in‐time type, used for refill timestamps.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:util/TokenBucket/2constructor.adoc[`TokenBucket`]         [.small]#[constructor]#
| Construct a token bucket with a given rate, initial balance, and capacity.
| xref:util/TokenBucket/decrement.adoc[`decrement`] 
| Consume n tokens. Returns false if the balance dropped to/below the given floor.
| xref:util/TokenBucket/increment.adoc[`increment`] 
| Refill tokens based on elapsed time since last call. No refill occurs on the first call (establishes the time baseline).
| xref:util/TokenBucket/value.adoc[`value`] 
| Current token balance.
|===


== Data Members

[cols="1,4"]
|===
| Name| Description
| xref:util/TokenBucket/m_cap.adoc[`m_cap`] 
| Maximum token balance
| xref:util/TokenBucket/m_rate.adoc[`m_rate`] 
| Tokens added per second
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#