java 58 lines · 9 steps

A thread-safe round-robin load balancer in Java

How an atomic cursor and copy-on-write list rotate through healthy backends without locks.

Explained by highlit
Intermediate concurrency load-balancing round-robin atomics generics
1package com.example.lb;
2 
3import java.util.List;
4import java.util.concurrent.atomic.AtomicInteger;
5import java.util.concurrent.CopyOnWriteArrayList;
6 
7public final class RoundRobinBalancer<T> {
8 
9 private final CopyOnWriteArrayList<Backend<T>> backends = new CopyOnWriteArrayList<>();
10 private final AtomicInteger cursor = new AtomicInteger(0);
11 
12 public RoundRobinBalancer(List<T> targets) {
13 for (T target : targets) {
14 backends.add(new Backend<>(target));
15 }
16 }
17 
18 public T next() {
19 int size = backends.size();
20 if (size == 0) {
21 throw new IllegalStateException("no backends available");
22 }
23 for (int attempt = 0; attempt < size; attempt++) {
24 int index = Math.floorMod(cursor.getAndIncrement(), size);
25 Backend<T> candidate = backends.get(index);
26 if (candidate.healthy) {
27 return candidate.target;
28 }
29 }
30 throw new IllegalStateException("all backends are unhealthy");
31 }
32 
33 public void markDown(T target) {
34 setHealth(target, false);
35 }
36 
37 public void markUp(T target) {
38 setHealth(target, true);
39 }
40 
41 private void setHealth(T target, boolean healthy) {
42 for (Backend<T> backend : backends) {
43 if (backend.target.equals(target)) {
44 backend.healthy = healthy;
45 return;
46 }
47 }
48 }
49 
50 private static final class Backend<T> {
51 final T target;
52 volatile boolean healthy = true;
53 
54 Backend(T target) {
55 this.target = target;
56 }
57 }
58}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1An AtomicInteger cursor lets many threads pick the next target without explicit locking.
  2. 2Bounding the scan to the list size guarantees termination even when every backend is down.
  3. 3Marking a volatile flag instead of removing entries keeps selection and health updates safe under concurrency.

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
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
java 
public class TimedSocketReader {
 
    private static final int READ_TIMEOUT_MS = 5_000;
    private static final int CONNECT_TIMEOUT_MS = 3_000;

Reading a socket with connect and read timeouts

sockets timeouts io
Intermediate 8 steps

Share this explainer

Here's the card — post it anywhere.

A thread-safe round-robin load balancer in Java — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code