Tor  0.4.7.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") */
21 typedef 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. */
27 typedef 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 
48 static 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. */
50 static 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. */
59 typedef 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);
70 
72  uint32_t rate, uint32_t burst);
73 
75  uint32_t now_ts);
76 
77 #define TB_READ 1
78 #define TB_WRITE 2
79 
81  uint32_t now_ts);
82 
84  ssize_t n);
86  ssize_t n);
87 
89  ssize_t n_read, ssize_t n_written);
90 
91 static inline size_t token_bucket_rw_get_read(const token_bucket_rw_t *bucket);
92 static inline size_t
93 token_bucket_rw_get_read(const token_bucket_rw_t *bucket)
94 {
95  return token_bucket_raw_get(&bucket->read_bucket);
96 }
97 
98 static inline size_t token_bucket_rw_get_write(
99  const token_bucket_rw_t *bucket);
100 static inline size_t
101 token_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 
110 typedef struct token_bucket_ctr_t {
111  token_bucket_cfg_t cfg;
112  token_bucket_raw_t counter;
113  uint32_t last_refilled_at_timestamp;
115 
116 void token_bucket_ctr_init(token_bucket_ctr_t *bucket, uint32_t rate,
117  uint32_t burst, uint32_t now_ts);
118 void token_bucket_ctr_adjust(token_bucket_ctr_t *bucket, uint32_t rate,
119  uint32_t burst);
120 void token_bucket_ctr_reset(token_bucket_ctr_t *bucket, uint32_t now_ts);
121 void token_bucket_ctr_refill(token_bucket_ctr_t *bucket, uint32_t now_ts);
122 
123 static inline bool
124 token_bucket_ctr_dec(token_bucket_ctr_t *bucket, ssize_t n)
125 {
126  return token_bucket_raw_dec(&bucket->counter, n);
127 }
128 
129 static inline size_t
130 token_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 
142 STATIC 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:116
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
void token_bucket_ctr_init(token_bucket_ctr_t *bucket, uint32_t rate, uint32_t burst, uint32_t now_ts)
Definition: token_bucket.c:265
int token_bucket_raw_dec(token_bucket_raw_t *bucket, ssize_t n)
Definition: token_bucket.c:104
void token_bucket_rw_init(token_bucket_rw_t *bucket, uint32_t rate, uint32_t burst, uint32_t now_ts)
Definition: token_bucket.c:137
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:152
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_reset(token_bucket_ctr_t *bucket, uint32_t now_ts)
Definition: token_bucket.c:285
void token_bucket_ctr_refill(token_bucket_ctr_t *bucket, uint32_t now_ts)
Definition: token_bucket.c:294
void token_bucket_ctr_adjust(token_bucket_ctr_t *bucket, uint32_t rate, uint32_t burst)
Definition: token_bucket.c:276
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
int token_bucket_rw_refill(token_bucket_rw_t *bucket, uint32_t now_ts)
Definition: token_bucket.c:183
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_reset(token_bucket_rw_t *bucket, uint32_t now_ts)
Definition: token_bucket.c:167
Integer definitions used throughout Tor.