java 48 lines · 8 steps

How a token bucket rate limiter works

A token bucket smooths bursts by refilling permits over time and only letting callers proceed when enough tokens exist.

Explained by highlit
Intermediate rate-limiting concurrency token-bucket thread-safety lazy-refill
1public final class TokenBucketRateLimiter {
2 
3 private final long capacity;
4 private final double refillTokensPerNano;
5 private double availableTokens;
6 private long lastRefillNanos;
7 
8 public TokenBucketRateLimiter(long capacity, long refillTokens, Duration refillPeriod) {
9 if (capacity <= 0 || refillTokens <= 0) {
10 throw new IllegalArgumentException("capacity and refill must be positive");
11 }
12 this.capacity = capacity;
13 this.refillTokensPerNano = (double) refillTokens / refillPeriod.toNanos();
14 this.availableTokens = capacity;
15 this.lastRefillNanos = System.nanoTime();
16 }
17 
18 public synchronized boolean tryAcquire(long permits) {
19 refill();
20 if (availableTokens >= permits) {
21 availableTokens -= permits;
22 return true;
23 }
24 return false;
25 }
26 
27 public synchronized void acquire(long permits) throws InterruptedException {
28 while (true) {
29 refill();
30 if (availableTokens >= permits) {
31 availableTokens -= permits;
32 return;
33 }
34 double deficit = permits - availableTokens;
35 long waitNanos = (long) Math.ceil(deficit / refillTokensPerNano);
36 TimeUnit.NANOSECONDS.sleep(waitNanos);
37 }
38 }
39 
40 private void refill() {
41 long now = System.nanoTime();
42 double refilled = (now - lastRefillNanos) * refillTokensPerNano;
43 if (refilled > 0) {
44 availableTokens = Math.min(capacity, availableTokens + refilled);
45 lastRefillNanos = now;
46 }
47 }
48}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1A token bucket allows short bursts up to its capacity while enforcing a steady average rate over time.
  2. 2Computing refill lazily from elapsed time avoids a background thread and keeps the state a single number.
  3. 3Deriving the exact wait from the token deficit and refill rate lets a blocking acquire sleep only as long as needed.

Related explainers

java 
@Component
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {
 

Transparent column encryption in Spring & JPA

encryption aes-gcm jpa-converter
Advanced 10 steps
java 
package com.acme.billing.config;
 
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.ConfigurationProperties;

Feature-flagged beans with Spring @ConditionalOnProperty

feature-flags conditional-beans strategy-pattern
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
java 
public static Map<String, String> parseCookieHeader(String header) {
    Map<String, String> cookies = new LinkedHashMap<>();
    if (header == null || header.isBlank()) {
        return cookies;

Parsing an HTTP Cookie header in Java

string-parsing http url-decoding
Intermediate 6 steps
python 
import secrets
 
from django.contrib.auth import authenticate, login
from django.core.cache import cache

Two-factor login with OTP in Django

two-factor-auth one-time-passwords caching
Intermediate 9 steps
rust 
use std::collections::VecDeque;
use std::sync::{Arc, Condvar, Mutex};
use std::time::{Duration, Instant};
 

Building a counting semaphore in Rust

concurrency synchronization condition-variable
Advanced 9 steps

Share this explainer

Here's the card — post it anywhere.

How a token bucket rate limiter works — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code