Tor 0.4.9.0-alpha-dev
token_bucket.h
Go to the documentation of this file.
1/* Copyright (c) 2018-2021, The Tor Project, Inc. */
2/* See LICENSE for licensing information */
3
4/**
5 * \file token_bucket.h
6 * \brief Headers for token_bucket.c
7 **/
8
9#ifndef TOR_TOKEN_BUCKET_H
10#define TOR_TOKEN_BUCKET_H
11
12#include "lib/cc/torint.h"
14
15/** Largest allowable burst value for a token buffer. */
16#define TOKEN_BUCKET_MAX_BURST INT32_MAX
17
18/** A generic token buffer configuration: determines the number of tokens
19 * added to the bucket in each time unit (the "rate"), and the maximum number
20 * of tokens in the bucket (the "burst") */
21typedef struct token_bucket_cfg_t {
22 uint32_t rate;
23 int32_t burst;
25
26/** A raw token bucket, decoupled from its configuration and timestamp. */
27typedef struct token_bucket_raw_t {
28 int32_t bucket;
30
32 uint32_t rate,
33 uint32_t burst);
34
36 const token_bucket_cfg_t *cfg);
37
39 const token_bucket_cfg_t *cfg);
40
42 ssize_t n);
43
45 const token_bucket_cfg_t *cfg,
46 const uint32_t elapsed_steps);
47
48static inline size_t token_bucket_raw_get(const token_bucket_raw_t *bucket);
49/** Return the current number of bytes set in a token bucket. */
50static inline size_t
52{
53 return bucket->bucket >= 0 ? bucket->bucket : 0;
54}
55
56/** A convenience type containing all the pieces needed for a coupled
57 * read-bucket and write-bucket that have the same rate limit, and which use
58 * "timestamp units" (see compat_time.h) for their time. */
59typedef struct token_bucket_rw_t {
61 token_bucket_raw_t read_bucket;
62 token_bucket_raw_t write_bucket;
63 uint32_t last_refilled_at_timestamp;
65
67 uint32_t rate,
68 uint32_t burst,
69 uint32_t now_ts_stamp);
70
72 uint32_t rate, uint32_t burst);
73
75 uint32_t now_ts_stamp);
76
77#define TB_READ 1
78#define TB_WRITE 2
79
81 uint32_t now_ts_stamp);
82
84 ssize_t n);
86 ssize_t n);
87
89 ssize_t n_read, ssize_t n_written);
90
91static inline size_t token_bucket_rw_get_read(const token_bucket_rw_t *bucket);
92static inline size_t
93token_bucket_rw_get_read(const token_bucket_rw_t *bucket)
94{
95 return token_bucket_raw_get(&bucket->read_bucket);
96}
97
98static inline size_t token_bucket_rw_get_write(
99 const token_bucket_rw_t *bucket);
100static inline size_t
101token_bucket_rw_get_write(const token_bucket_rw_t *bucket)
102{
103 return token_bucket_raw_get(&bucket->write_bucket);
104}
105
106/**
107 * A specialized bucket containing a single counter.
108 */
109
110typedef struct token_bucket_ctr_t {
112 token_bucket_raw_t counter;
113 uint32_t last_refilled_at_timestamp;
115
116void token_bucket_ctr_init(token_bucket_ctr_t *bucket, uint32_t rate,
117 uint32_t burst, uint32_t now_ts_sec);
118void token_bucket_ctr_adjust(token_bucket_ctr_t *bucket, uint32_t rate,
119 uint32_t burst);
120void token_bucket_ctr_reset(token_bucket_ctr_t *bucket, uint32_t now_ts_sec);
121void token_bucket_ctr_refill(token_bucket_ctr_t *bucket, uint32_t now_ts_sec);
122
123static inline bool
124token_bucket_ctr_dec(token_bucket_ctr_t *bucket, ssize_t n)
125{
126 return token_bucket_raw_dec(&bucket->counter, n);
127}
128
129static inline size_t
130token_bucket_ctr_get(const token_bucket_ctr_t *bucket)
131{
132 return token_bucket_raw_get(&bucket->counter);
133}
134
135#ifdef TOKEN_BUCKET_PRIVATE
136
137/* To avoid making the rates too small, we consider units of "steps",
138 * where a "step" is defined as this many timestamp ticks. Keep this
139 * a power of two if you can. */
140#define TICKS_PER_STEP 16
141
142STATIC uint32_t rate_per_sec_to_rate_per_step(uint32_t rate);
143
144#endif /* defined(TOKEN_BUCKET_PRIVATE) */
145
146#endif /* !defined(TOR_TOKEN_BUCKET_H) */
Macros to implement mocking and selective exposure for the test code.
#define STATIC
Definition: testsupport.h:32
STATIC uint32_t rate_per_sec_to_rate_per_step(uint32_t rate)
Definition: token_bucket.c:118
int token_bucket_rw_dec(token_bucket_rw_t *bucket, ssize_t n_read, ssize_t n_written)
Definition: token_bucket.c:249
int token_bucket_rw_dec_read(token_bucket_rw_t *bucket, ssize_t n)
Definition: token_bucket.c:224
int token_bucket_raw_refill_steps(token_bucket_raw_t *bucket, const token_bucket_cfg_t *cfg, const uint32_t elapsed_steps)
Definition: token_bucket.c:77
int token_bucket_raw_dec(token_bucket_raw_t *bucket, ssize_t n)
Definition: token_bucket.c:104
int token_bucket_rw_refill(token_bucket_rw_t *bucket, uint32_t now_ts_stamp)
Definition: token_bucket.c:185
void token_bucket_raw_adjust(token_bucket_raw_t *bucket, const token_bucket_cfg_t *cfg)
Definition: token_bucket.c:64
void token_bucket_rw_adjust(token_bucket_rw_t *bucket, uint32_t rate, uint32_t burst)
Definition: token_bucket.c:154
void token_bucket_rw_reset(token_bucket_rw_t *bucket, uint32_t now_ts_stamp)
Definition: token_bucket.c:169
void token_bucket_cfg_init(token_bucket_cfg_t *cfg, uint32_t rate, uint32_t burst)
Definition: token_bucket.c:36
void token_bucket_ctr_init(token_bucket_ctr_t *bucket, uint32_t rate, uint32_t burst, uint32_t now_ts_sec)
Definition: token_bucket.c:267
void token_bucket_ctr_adjust(token_bucket_ctr_t *bucket, uint32_t rate, uint32_t burst)
Definition: token_bucket.c:278
int token_bucket_rw_dec_write(token_bucket_rw_t *bucket, ssize_t n)
Definition: token_bucket.c:237
static size_t token_bucket_raw_get(const token_bucket_raw_t *bucket)
Definition: token_bucket.h:51
void token_bucket_raw_reset(token_bucket_raw_t *bucket, const token_bucket_cfg_t *cfg)
Definition: token_bucket.c:54
void token_bucket_rw_init(token_bucket_rw_t *bucket, uint32_t rate, uint32_t burst, uint32_t now_ts_stamp)
Definition: token_bucket.c:139
void token_bucket_ctr_refill(token_bucket_ctr_t *bucket, uint32_t now_ts_sec)
Definition: token_bucket.c:296
void token_bucket_ctr_reset(token_bucket_ctr_t *bucket, uint32_t now_ts_sec)
Definition: token_bucket.c:287
Integer definitions used throughout Tor.