common/cpp/token_bucket_rate_limiter.cpp

Source
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

#include "token_bucket_rate_limiter.h"

#include <bthread/bthread.h>
#include <glog/logging.h> // IWYU pragma: export

#include <atomic>
#include <chrono>
#include <mutex>
#include <thread>

#if defined(__APPLE__)
#include <ctime>
#endif

namespace doris {
// Just 10^6.
static constexpr auto NS = 1000000000UL;

bvar::Adder<int64_t> s3_get_rate_limit_sleep_ns("s3_get_rate_limit_sleep_ns");
bvar::Adder<int64_t> s3_get_rate_limit_sleep_count("s3_get_rate_limit_sleep_count");
bvar::Adder<int64_t> s3_get_rate_limit_rejected_count("s3_get_rate_limit_rejected_count");
bvar::Adder<int64_t> s3_put_rate_limit_sleep_ns("s3_put_rate_limit_sleep_ns");
bvar::Adder<int64_t> s3_put_rate_limit_sleep_count("s3_put_rate_limit_sleep_count");
bvar::Adder<int64_t> s3_put_rate_limit_rejected_count("s3_put_rate_limit_rejected_count");

static std::atomic<int64_t> s3_get_rate_limit_sleep_log_count {0};
static std::atomic<int64_t> s3_get_rate_limit_rejected_log_count {0};
static std::atomic<int64_t> s3_put_rate_limit_sleep_log_count {0};
static std::atomic<int64_t> s3_put_rate_limit_rejected_log_count {0};

class TokenBucketRateLimiter::SimpleSpinLock {
public:
    SimpleSpinLock() = default;
    ~SimpleSpinLock() = default;

    void lock() {
        int spin_count = 0;
        static constexpr int MAX_SPIN_COUNT = 50;
        while (_flag.test_and_set(std::memory_order_acq_rel)) {
            spin_count++;
            if (spin_count >= MAX_SPIN_COUNT) {
                LOG(WARNING) << "Warning: Excessive spinning detected while acquiring lock. Spin "
                                "count: "
                             << spin_count;
                spin_count = 0;
            }
            // Spin until we acquire the lock
        }
    }

    void unlock() { _flag.clear(std::memory_order_release); }

private:
    std::atomic_flag _flag = ATOMIC_FLAG_INIT;
};

TokenBucketRateLimiter::TokenBucketRateLimiter(size_t max_speed, size_t max_burst, size_t limit)
        : _max_speed(max_speed),
          _max_burst(max_burst),
          _limit(limit),
          _mutex(std::make_unique<TokenBucketRateLimiter::SimpleSpinLock>()),
          _remain_tokens(max_burst) {}

TokenBucketRateLimiter::~TokenBucketRateLimiter() = default;

TokenBucketRateLimiterHolder::~TokenBucketRateLimiterHolder() = default;

std::pair<size_t, double> TokenBucketRateLimiter::_update_remain_token(long now, size_t amount) {
    // Values obtained under lock to be checked after release
    size_t count_value;
    double tokens_value;
    {
        std::lock_guard<SimpleSpinLock> lock(*_mutex);
        now = (now < _prev_ns_count) ? _prev_ns_count : now;
        if (_max_speed) {
            double delta_seconds =
                    _prev_ns_count ? static_cast<double>(now - _prev_ns_count) / NS : 0;
            _remain_tokens = std::min<double>(_remain_tokens + _max_speed * delta_seconds - amount,
                                              _max_burst);
        }
        _count += amount;
        count_value = _count;
        if (_limit && count_value > _limit) {
            // Keep rejection side-effect free. Roll back before releasing the lock so
            // concurrent callers cannot observe debt from a request that will not run.
            _count -= amount;
            if (_max_speed) {
                _remain_tokens = std::min<double>(_remain_tokens + amount, _max_burst);
            }
        }
        tokens_value = _remain_tokens;
        _prev_ns_count = now;
    }
    return {count_value, tokens_value};
}

int64_t TokenBucketRateLimiter::add(size_t amount) {
    // Values obtained under lock to be checked after release
    auto duration = std::chrono::steady_clock::now().time_since_epoch();
    auto time_nano_count = std::chrono::duration_cast<std::chrono::nanoseconds>(duration).count();
    auto [count_value, tokens_value] = _update_remain_token(time_nano_count, amount);

    if (_limit && count_value > _limit) {
        // CK would throw exception
        return -1;
    }

    // Wait unless there is positive amount of remain_tokens - throttling
    int64_t sleep_time_ns = 0;
    if (_max_speed && tokens_value < 0) {
        sleep_time_ns = static_cast<int64_t>(-tokens_value / _max_speed * NS);
        bthread_usleep(sleep_time_ns / 1000);
    }

    return sleep_time_ns;
}

void TokenBucketRateLimiter::refund(size_t amount) {
    std::lock_guard<SimpleSpinLock> lock(*_mutex);
    if (_max_speed) {
        _remain_tokens = std::min<double>(_remain_tokens + amount, _max_burst);
    }
    _count = (_count >= amount) ? _count - amount : 0;
}

TokenBucketRateLimiterHolder::TokenBucketRateLimiterHolder(size_t max_speed, size_t max_burst,
                                                           size_t limit,
                                                           std::function<void(int64_t)> metric_func)
        : rate_limiter(std::make_shared<TokenBucketRateLimiter>(max_speed, max_burst, limit)),
          _enabled(max_speed > 0 || limit > 0),
          metric_func(std::move(metric_func)) {}

int64_t TokenBucketRateLimiterHolder::add(size_t amount) {
    return add_with_config(amount).sleep_duration;
}

TokenBucketRateLimiterResult TokenBucketRateLimiterHolder::add_with_config(size_t amount) {
    // Snapshot the current limiter and call add() outside the read lock: add() may
    // sleep for a long time when throttled, and holding the read lock across the
    // sleep would block reset() (dynamic config update) for the whole duration.
    std::shared_ptr<TokenBucketRateLimiter> limiter;
    {
        std::shared_lock read {rate_limiter_rw_lock};
        limiter = rate_limiter;
    }
    TokenBucketRateLimiterResult result = {.sleep_duration = limiter->add(amount),
                                           .max_speed = limiter->get_max_speed(),
                                           .max_burst = limiter->get_max_burst(),
                                           .limit = limiter->get_limit()};
    metric_func(result.sleep_duration);
    return result;
}

std::shared_ptr<TokenBucketRateLimiter> TokenBucketRateLimiterHolder::charge(size_t amount) {
    std::shared_ptr<TokenBucketRateLimiter> limiter;
    {
        std::shared_lock read {rate_limiter_rw_lock};
        limiter = rate_limiter;
    }
    int64_t sleep_duration = limiter->add(amount);
    metric_func(sleep_duration);
    return sleep_duration < 0 ? nullptr : limiter;
}

int TokenBucketRateLimiterHolder::reset(size_t max_speed, size_t max_burst, size_t limit) {
    auto new_rate_limiter = std::make_shared<TokenBucketRateLimiter>(max_speed, max_burst, limit);
    {
        std::unique_lock write {rate_limiter_rw_lock};
        rate_limiter = std::move(new_rate_limiter);
        _enabled.store(max_speed > 0 || limit > 0, std::memory_order_release);
    }
    return 0;
}

size_t TokenBucketRateLimiterHolder::get_max_speed() const {
    std::shared_lock read {rate_limiter_rw_lock};
    return rate_limiter->get_max_speed();
}

size_t TokenBucketRateLimiterHolder::get_max_burst() const {
    std::shared_lock read {rate_limiter_rw_lock};
    return rate_limiter->get_max_burst();
}

size_t TokenBucketRateLimiterHolder::get_limit() const {
    std::shared_lock read {rate_limiter_rw_lock};
    return rate_limiter->get_limit();
}

std::string to_string(S3RateLimitType type) {
    switch (type) {
    case S3RateLimitType::GET:
        return "get";
    case S3RateLimitType::PUT:
        return "put";
    default:
        return std::to_string(static_cast<size_t>(type));
    }
}

S3RateLimitType string_to_s3_rate_limit_type(std::string_view value) {
    if (value == "get") {
        return S3RateLimitType::GET;
    } else if (value == "put") {
        return S3RateLimitType::PUT;
    }
    return S3RateLimitType::UNKNOWN;
}

std::function<void(int64_t)> s3_rate_limiter_metric_func(S3RateLimitType type) {
    switch (type) {
    case S3RateLimitType::GET:
        return metric_func_factory(s3_get_rate_limit_sleep_ns, s3_get_rate_limit_sleep_count,
                                   &s3_get_rate_limit_rejected_count);
    case S3RateLimitType::PUT:
        return metric_func_factory(s3_put_rate_limit_sleep_ns, s3_put_rate_limit_sleep_count,
                                   &s3_put_rate_limit_rejected_count);
    default:
        return [](int64_t) {};
    }
}

int64_t apply_s3_rate_limit(S3RateLimitType type, S3RateLimiterHolder* rate_limiter,
                            int64_t log_interval) {
    auto result = rate_limiter->add_with_config(1);
    auto sleep_duration = result.sleep_duration;
    if (log_interval <= 0 || sleep_duration == 0) {
        return sleep_duration;
    }

    auto is_get = type == S3RateLimitType::GET;
    auto* sleep_log_count =
            is_get ? &s3_get_rate_limit_sleep_log_count : &s3_put_rate_limit_sleep_log_count;
    auto* rejected_log_count =
            is_get ? &s3_get_rate_limit_rejected_log_count : &s3_put_rate_limit_rejected_log_count;

    if (sleep_duration > 0) {
        int64_t count = sleep_log_count->fetch_add(1, std::memory_order_relaxed) + 1;
        if (count == 1 || count % log_interval == 0) {
            LOG(INFO) << "S3 " << to_string(type) << " request is throttled by local rate limiter"
                      << ", sleep_ms=" << sleep_duration / 1000000 << ", sleep_count=" << count
                      << ", token_per_second=" << result.max_speed
                      << ", bucket_tokens=" << result.max_burst << ", token_limit=" << result.limit;
        }
    } else {
        int64_t count = rejected_log_count->fetch_add(1, std::memory_order_relaxed) + 1;
        if (count == 1 || count % log_interval == 0) {
            LOG(WARNING) << "S3 " << to_string(type) << " request is rejected by local rate limiter"
                         << ", rejected_count=" << count
                         << ", token_per_second=" << result.max_speed
                         << ", bucket_tokens=" << result.max_burst
                         << ", token_limit=" << result.limit;
        }
    }
    return sleep_duration;
}
} // namespace doris

Coverage Report

Created: 2026-08-06 20:25

Line	Count	Source
1		// Licensed to the Apache Software Foundation (ASF) under one
2		// or more contributor license agreements. See the NOTICE file
3		// distributed with this work for additional information
4		// regarding copyright ownership. The ASF licenses this file
5		// to you under the Apache License, Version 2.0 (the
6		// "License"); you may not use this file except in compliance
7		// with the License. You may obtain a copy of the License at
8		//
9		// http://www.apache.org/licenses/LICENSE-2.0
10		//
11		// Unless required by applicable law or agreed to in writing,
12		// software distributed under the License is distributed on an
13		// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14		// KIND, either express or implied. See the License for the
15		// specific language governing permissions and limitations
16		// under the License.
17
18		#include "token_bucket_rate_limiter.h"
19
20		#include <bthread/bthread.h>
21		#include <glog/logging.h> // IWYU pragma: export
22
23		#include <atomic>
24		#include <chrono>
25		#include <mutex>
26		#include <thread>
27
28		#if defined(__APPLE__)
29		#include <ctime>
30		#endif
31
32		namespace doris {
33		// Just 10^6.
34		static constexpr auto NS = 1000000000UL;
35
36		bvar::Adder<int64_t> s3_get_rate_limit_sleep_ns("s3_get_rate_limit_sleep_ns");
37		bvar::Adder<int64_t> s3_get_rate_limit_sleep_count("s3_get_rate_limit_sleep_count");
38		bvar::Adder<int64_t> s3_get_rate_limit_rejected_count("s3_get_rate_limit_rejected_count");
39		bvar::Adder<int64_t> s3_put_rate_limit_sleep_ns("s3_put_rate_limit_sleep_ns");
40		bvar::Adder<int64_t> s3_put_rate_limit_sleep_count("s3_put_rate_limit_sleep_count");
41		bvar::Adder<int64_t> s3_put_rate_limit_rejected_count("s3_put_rate_limit_rejected_count");
42
43		static std::atomic<int64_t> s3_get_rate_limit_sleep_log_count {0};
44		static std::atomic<int64_t> s3_get_rate_limit_rejected_log_count {0};
45		static std::atomic<int64_t> s3_put_rate_limit_sleep_log_count {0};
46		static std::atomic<int64_t> s3_put_rate_limit_rejected_log_count {0};
47
48		class TokenBucketRateLimiter::SimpleSpinLock {
49		public:
50	1.71k	SimpleSpinLock() = default;
51		~SimpleSpinLock() = default;
52
53	633	void lock() {
54	633	int spin_count = 0;
55	633	static constexpr int MAX_SPIN_COUNT = 50;
56	638	while (_flag.test_and_set(std::memory_order_acq_rel)) {
57	5	spin_count++;
58	5	if (spin_count >= MAX_SPIN_COUNT) {
59	0	LOG(WARNING) << "Warning: Excessive spinning detected while acquiring lock. Spin "
60	0	"count: "
61	0	<< spin_count;
62	0	spin_count = 0;
63	0	}
64		// Spin until we acquire the lock
65	5	}
66	633	}
67
68	633	void unlock() { _flag.clear(std::memory_order_release); }
69
70		private:
71		std::atomic_flag _flag = ATOMIC_FLAG_INIT;
72		};
73
74		TokenBucketRateLimiter::TokenBucketRateLimiter(size_t max_speed, size_t max_burst, size_t limit)
75	1.71k	: _max_speed(max_speed),
76	1.71k	_max_burst(max_burst),
77	1.71k	_limit(limit),
78	1.71k	_mutex(std::make_unique<TokenBucketRateLimiter::SimpleSpinLock>()),
79	1.71k	_remain_tokens(max_burst) {}
80
81	1.71k	TokenBucketRateLimiter::~TokenBucketRateLimiter() = default;
82
83	1.56k	TokenBucketRateLimiterHolder::~TokenBucketRateLimiterHolder() = default;
84
85	629	std::pair<size_t, double> TokenBucketRateLimiter::_update_remain_token(long now, size_t amount) {
86		// Values obtained under lock to be checked after release
87	629	size_t count_value;
88	629	double tokens_value;
89	629	{
90	629	std::lock_guard<SimpleSpinLock> lock(*_mutex);
91	629	now = (now < _prev_ns_count) ? _prev_ns_count : now;
92	629	if (_max_speed) {
93	605	double delta_seconds =
94	605	_prev_ns_count ? static_cast<double>(now - _prev_ns_count) / NS : 0;
95	605	_remain_tokens = std::min<double>(_remain_tokens + _max_speed * delta_seconds - amount,
96	605	_max_burst);
97	605	}
98	629	_count += amount;
99	629	count_value = _count;
100	629	if (_limit && count_value > _limit) {
101		// Keep rejection side-effect free. Roll back before releasing the lock so
102		// concurrent callers cannot observe debt from a request that will not run.
103	40	_count -= amount;
104	40	if (_max_speed) {
105	30	_remain_tokens = std::min<double>(_remain_tokens + amount, _max_burst);
106	30	}
107	40	}
108	629	tokens_value = _remain_tokens;
109	629	_prev_ns_count = now;
110	629	}
111	629	return {count_value, tokens_value};
112	629	}
113
114	629	int64_t TokenBucketRateLimiter::add(size_t amount) {
115		// Values obtained under lock to be checked after release
116	629	auto duration = std::chrono::steady_clock::now().time_since_epoch();
117	629	auto time_nano_count = std::chrono::duration_cast<std::chrono::nanoseconds>(duration).count();
118	629	auto [count_value, tokens_value] = _update_remain_token(time_nano_count, amount);
119
120	629	if (_limit && count_value > _limit) {
121		// CK would throw exception
122	40	return -1;
123	40	}
124
125		// Wait unless there is positive amount of remain_tokens - throttling
126	589	int64_t sleep_time_ns = 0;
127	589	if (_max_speed && tokens_value < 0) {
128	287	sleep_time_ns = static_cast<int64_t>(-tokens_value / _max_speed * NS);
129	287	bthread_usleep(sleep_time_ns / 1000);
130	287	}
131
132	589	return sleep_time_ns;
133	629	}
134
135	4	void TokenBucketRateLimiter::refund(size_t amount) {
136	4	std::lock_guard<SimpleSpinLock> lock(*_mutex);
137	4	if (_max_speed) {
138	4	_remain_tokens = std::min<double>(_remain_tokens + amount, _max_burst);
139	4	}
140	4	_count = (_count >= amount) ? _count - amount : 0;
141	4	}
142
143		TokenBucketRateLimiterHolder::TokenBucketRateLimiterHolder(size_t max_speed, size_t max_burst,
144		size_t limit,
145		std::function<void(int64_t)> metric_func)
146	1.56k	: rate_limiter(std::make_shared<TokenBucketRateLimiter>(max_speed, max_burst, limit)),
147	1.56k	_enabled(max_speed > 0 \|\| limit > 0),
148	1.56k	metric_func(std::move(metric_func)) {}
149
150	582	int64_t TokenBucketRateLimiterHolder::add(size_t amount) {
151	582	return add_with_config(amount).sleep_duration;
152	582	}
153
154	613	TokenBucketRateLimiterResult TokenBucketRateLimiterHolder::add_with_config(size_t amount) {
155		// Snapshot the current limiter and call add() outside the read lock: add() may
156		// sleep for a long time when throttled, and holding the read lock across the
157		// sleep would block reset() (dynamic config update) for the whole duration.
158	613	std::shared_ptr<TokenBucketRateLimiter> limiter;
159	613	{
160	613	std::shared_lock read {rate_limiter_rw_lock};
161	613	limiter = rate_limiter;
162	613	}
163	613	TokenBucketRateLimiterResult result = {.sleep_duration = limiter->add(amount),
164	613	.max_speed = limiter->get_max_speed(),
165	613	.max_burst = limiter->get_max_burst(),
166	613	.limit = limiter->get_limit()};
167	613	metric_func(result.sleep_duration);
168	613	return result;
169	613	}
170
171	13	std::shared_ptr<TokenBucketRateLimiter> TokenBucketRateLimiterHolder::charge(size_t amount) {
172	13	std::shared_ptr<TokenBucketRateLimiter> limiter;
173	13	{
174	13	std::shared_lock read {rate_limiter_rw_lock};
175	13	limiter = rate_limiter;
176	13	}
177	13	int64_t sleep_duration = limiter->add(amount);
178	13	metric_func(sleep_duration);
179	13	return sleep_duration < 0 ? nullptr : limiter;
180	13	}
181
182	143	int TokenBucketRateLimiterHolder::reset(size_t max_speed, size_t max_burst, size_t limit) {
183	143	auto new_rate_limiter = std::make_shared<TokenBucketRateLimiter>(max_speed, max_burst, limit);
184	143	{
185	143	std::unique_lock write {rate_limiter_rw_lock};
186	143	rate_limiter = std::move(new_rate_limiter);
187	143	_enabled.store(max_speed > 0 \|\| limit > 0, std::memory_order_release);
188	143	}
189	143	return 0;
190	143	}
191
192	299	size_t TokenBucketRateLimiterHolder::get_max_speed() const {
193	299	std::shared_lock read {rate_limiter_rw_lock};
194	299	return rate_limiter->get_max_speed();
195	299	}
196
197	77	size_t TokenBucketRateLimiterHolder::get_max_burst() const {
198	77	std::shared_lock read {rate_limiter_rw_lock};
199	77	return rate_limiter->get_max_burst();
200	77	}
201
202	69	size_t TokenBucketRateLimiterHolder::get_limit() const {
203	69	std::shared_lock read {rate_limiter_rw_lock};
204	69	return rate_limiter->get_limit();
205	69	}
206
207	95	std::string to_string(S3RateLimitType type) {
208	95	switch (type) {
209	54	case S3RateLimitType::GET:
210	54	return "get";
211	41	case S3RateLimitType::PUT:
212	41	return "put";
213	0	default:
214	0	return std::to_string(static_cast<size_t>(type));
215	95	}
216	95	}
217
218	0	S3RateLimitType string_to_s3_rate_limit_type(std::string_view value) {
219	0	if (value == "get") {
220	0	return S3RateLimitType::GET;
221	0	} else if (value == "put") {
222	0	return S3RateLimitType::PUT;
223	0	}
224	0	return S3RateLimitType::UNKNOWN;
225	0	}
226
227	2	std::function<void(int64_t)> s3_rate_limiter_metric_func(S3RateLimitType type) {
228	2	switch (type) {
229	1	case S3RateLimitType::GET:
230	1	return metric_func_factory(s3_get_rate_limit_sleep_ns, s3_get_rate_limit_sleep_count,
231	1	&s3_get_rate_limit_rejected_count);
232	1	case S3RateLimitType::PUT:
233	1	return metric_func_factory(s3_put_rate_limit_sleep_ns, s3_put_rate_limit_sleep_count,
234	1	&s3_put_rate_limit_rejected_count);
235	0	default:
236	0	return [](int64_t) {};
237	2	}
238	2	}
239
240		int64_t apply_s3_rate_limit(S3RateLimitType type, S3RateLimiterHolder* rate_limiter,
241	31	int64_t log_interval) {
242	31	auto result = rate_limiter->add_with_config(1);
243	31	auto sleep_duration = result.sleep_duration;
244	31	if (log_interval <= 0 \|\| sleep_duration == 0) {
245	19	return sleep_duration;
246	19	}
247
248	12	auto is_get = type == S3RateLimitType::GET;
249	12	auto* sleep_log_count =
250	12	is_get ? &s3_get_rate_limit_sleep_log_count : &s3_put_rate_limit_sleep_log_count;
251	12	auto* rejected_log_count =
252	12	is_get ? &s3_get_rate_limit_rejected_log_count : &s3_put_rate_limit_rejected_log_count;
253
254	12	if (sleep_duration > 0) {
255	0	int64_t count = sleep_log_count->fetch_add(1, std::memory_order_relaxed) + 1;
256	0	if (count == 1 \|\| count % log_interval == 0) {
257	0	LOG(INFO) << "S3 " << to_string(type) << " request is throttled by local rate limiter"
258	0	<< ", sleep_ms=" << sleep_duration / 1000000 << ", sleep_count=" << count
259	0	<< ", token_per_second=" << result.max_speed
260	0	<< ", bucket_tokens=" << result.max_burst << ", token_limit=" << result.limit;
261	0	}
262	12	} else {
263	12	int64_t count = rejected_log_count->fetch_add(1, std::memory_order_relaxed) + 1;
264	12	if (count == 1 \|\| count % log_interval == 0) {
265		LOG(WARNING) << "S3 " << to_string(type) << " request is rejected by local rate limiter"
266	2	<< ", rejected_count=" << count
267	2	<< ", token_per_second=" << result.max_speed
268	2	<< ", bucket_tokens=" << result.max_burst
269	2	<< ", token_limit=" << result.limit;
270	2	}
271	12	}
272	12	return sleep_duration;
273	31	}
274		} // namespace doris