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 
public class SlidingLogRateLimiter {
 
    private final int maxRequests;
    private final long windowMillis;

How a sliding-log rate limiter works

rate-limiting concurrency sliding-window
Advanced 8 steps
go 
package theme
 
import (
	"fmt"

Per-tenant HTML templates with Gin's renderer

multi-tenancy concurrency html-templates
Advanced 8 steps
python 
import time
import threading
from enum import Enum
from functools import wraps

Building a circuit breaker in Python

circuit-breaker resilience decorators
Advanced 7 steps
java 
public final class Slugifier {
 
    private static final Pattern NON_LATIN = Pattern.compile("[^\\w-]");
    private static final Pattern WHITESPACE = Pattern.compile("[\\s]+");

Building a URL slugifier in Java

regex unicode-normalization string-processing
Intermediate 8 steps
typescript 
import { Injectable } from '@angular/core';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { BehaviorSubject, Observable, throwError } from 'rxjs';
import { catchError, filter, take, switchMap } from 'rxjs/operators';

Refreshing auth tokens in an Angular interceptor

http-interceptor token-refresh rxjs
Advanced 8 steps
php 
<?php
 
namespace App\Http\Middleware;
 

Idempotent requests with Laravel middleware

idempotency middleware caching
Advanced 8 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