ruby 48 lines · 8 steps

A thread-safe token bucket rate limiter in Ruby

A token bucket smooths bursts and enforces a steady rate, kept correct across threads with a monitor.

Explained by highlit
Intermediate rate-limiting concurrency thread-safety monotonic-clock algorithms
1require 'monitor'
2 
3class TokenBucket
4 include MonitorMixin
5 
6 def initialize(capacity:, refill_rate:)
7 super()
8 @capacity = capacity.to_f
9 @refill_rate = refill_rate.to_f
10 @tokens = @capacity
11 @last_refill = monotonic_now
12 end
13 
14 def allow?(cost = 1)
15 synchronize do
16 refill
17 if @tokens >= cost
18 @tokens -= cost
19 true
20 else
21 false
22 end
23 end
24 end
25 
26 def wait_time(cost = 1)
27 synchronize do
28 refill
29 return 0.0 if @tokens >= cost
30 (cost - @tokens) / @refill_rate
31 end
32 end
33 
34 private
35 
36 def refill
37 now = monotonic_now
38 elapsed = now - @last_refill
39 return if elapsed <= 0
40 
41 @tokens = [@capacity, @tokens + elapsed * @refill_rate].min
42 @last_refill = now
43 end
44 
45 def monotonic_now
46 Process.clock_gettime(Process::CLOCK_MONOTONIC)
47 end
48end
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1A token bucket permits short bursts up to its capacity while enforcing a long-run average rate.
  2. 2Lazy refill on each check avoids background timers by computing tokens from elapsed time.
  3. 3A monotonic clock keeps interval math immune to system clock adjustments.

Related explainers

ruby 
require "shellwords"
require "open3"
 
module Backup

Building safe shell commands in Ruby

shell-out subprocess command-injection
Intermediate 7 steps
ruby 
class UserAgentParser
  BROWSERS = [
    [/Edg\/([\d.]+)/, "Edge"],
    [/OPR\/([\d.]+)/, "Opera"],

Parsing user-agent strings in Ruby

regex pattern-matching lookup-tables
Intermediate 8 steps
ruby 
class LogAggregator
  BUCKET_FORMAT = "%Y-%m-%dT%H:%M"
 
  def initialize(entries)

Bucketing log entries by the minute in Ruby

aggregation hashing enumerable
Intermediate 5 steps
go 
func (w *Watcher) resetDebounce(d time.Duration) {
	if !w.timer.Stop() {
		select {
		case <-w.timer.C:

Debouncing a stream of events in Go

debounce timers channels
Advanced 7 steps
ruby 
class WeeklySignupsReport
  DEFAULT_WEEKS = 12
 
  def initialize(weeks: DEFAULT_WEEKS, source: User.all)

Building a weekly signups report in Rails

service object aggregation group by
Intermediate 7 steps
ruby 
class ApplicationController < ActionController::Base
  EXPERIMENTS = {
    checkout_button_color: %w[control blue green],
    onboarding_flow: %w[control streamlined]

How A/B test cohorts are assigned in Rails

a-b-testing cookies hashing
Intermediate 8 steps

Share this explainer

Here's the card — post it anywhere.

A thread-safe token bucket rate limiter in Ruby — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code