ThreadLocal & Synchronization Aids

"Shared mutable state is the root of all evil in concurrent programming. ThreadLocal eliminates sharing; synchronization aids coordinate it."

Overview: The Synchronization Toolkit

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    subgraph Isolation["Thread Isolation"]
        TL["ThreadLocal<br/>Per-thread store"]
        ITL["Inheritable TL<br/>Parent to child"]
        SV["ScopedValue<br/>VThread safe"]
    end

    subgraph Coordination["Coordination Aids"]
        CDL["CountDownLatch<br/>Wait for N"]
        CB["CyclicBarrier<br/>Meet then go"]
        SEM["Semaphore<br/>N permits"]
        PH["Phaser<br/>Multi-phase"]
        EX["Exchanger<br/>Pair swap"]
    end

    TL --- ITL --- SV
    CDL --- CB --- SEM --- PH --- EX

    style TL fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style ITL fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style SV fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style CDL fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style CB fill:#ECFDF5,stroke:#6EE7B7,color:#065F46
    style SEM fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style PH fill:#FFFBEB,stroke:#FCD34D,color:#92400E
    style EX fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B

ThreadLocal — Per-Thread Isolated Storage

What Is It?

ThreadLocal<T> gives each thread its own independent copy of a variable. No synchronization needed because there is no sharing.

// Each thread gets its own SimpleDateFormat -- no sharing, no race condition
private static final ThreadLocal<SimpleDateFormat> formatter =
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

// Usage in any thread:
String date = formatter.get().format(new Date()); // thread-safe!

Internal Mechanism: How ThreadLocal Actually Works

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    subgraph Thread1["Thread-1"]
        T1["Thread obj"]
        TLM1["ThreadLocalMap"]
        E1A["WeakRef:TL1<br/>val=userCtx"]
        E1B["WeakRef:TL2<br/>val=dateFmt"]
    end

    subgraph Thread2["Thread-2"]
        T2["Thread obj"]
        TLM2["ThreadLocalMap"]
        E2A["WeakRef:TL1<br/>val=userCtx"]
        E2B["WeakRef:TL2<br/>val=dateFmt"]
    end

    subgraph Heap["Heap (shared)"]
        TL1(("TL UserCtx"))
        TL2(("TL DateFmt"))
    end

    T1 --> TLM1
    TLM1 --> E1A
    TLM1 --> E1B
    E1A -.->|"weak"| TL1
    E1B -.->|"weak"| TL2

    T2 --> TLM2
    TLM2 --> E2A
    TLM2 --> E2B
    E2A -.->|"weak"| TL1
    E2B -.->|"weak"| TL2

    style T1 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T2 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style TLM1 fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style TLM2 fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style TL1 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style TL2 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style E1A fill:#EFF6FF,stroke:#BFDBFE,color:#1E40AF
    style E1B fill:#EFF6FF,stroke:#BFDBFE,color:#1E40AF
    style E2A fill:#EFF6FF,stroke:#BFDBFE,color:#1E40AF
    style E2B fill:#EFF6FF,stroke:#BFDBFE,color:#1E40AF

Key insight: The ThreadLocalMap is stored inside each Thread object. When you call threadLocal.get(), Java does:

// Simplified pseudocode of ThreadLocal.get()
public T get() {
    Thread t = Thread.currentThread();
    ThreadLocalMap map = t.threadLocals;       // each thread has its own map
    Entry e = map.getEntry(this);              // 'this' = the ThreadLocal key
    return (T) e.value;
}

Common Use Cases

The Memory Leak Problem

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    subgraph Problem["Memory Leak"]
        direction TB
        Step1["1. TL.set(bigObj)"]
        Step2["2. TL ref = null"]
        Step3["3. GC collects TL key"]
        Step4["4. Entry: key=null<br/>value=bigObj ALIVE"]
        Step5["5. Pool thread lives<br/>bigObj never freed"]
    end

    Step1 ==> Step2
    Step2 ==> Step3
    Step3 ==> Step4
    Step4 ==> Step5

    style Step1 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style Step2 fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style Step3 fill:#FFFBEB,stroke:#FCD34D,color:#92400E
    style Step4 fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B
    style Step5 fill:#FEF2F2,stroke:#FCA5A5,color:#991B1B

Why does this happen?

• ThreadLocalMap.Entry extends WeakReference<ThreadLocal<?>> -- so the key is weak
• But the value is a strong reference!
• When the ThreadLocal object is GC'd, the key becomes null, but the value remains
• The Entry is never removed because nothing triggers cleanup
• In a thread pool, the thread (and its ThreadLocalMap) lives indefinitely

The Fix: Always Call remove()

// CORRECT pattern -- always clean up
private static final ThreadLocal<UserContext> userContext = new ThreadLocal<>();

public void handleRequest(HttpServletRequest request) {
    try {
        userContext.set(extractUser(request));
        // ... process request ...
        processBusinessLogic();
    } finally {
        userContext.remove();  // CRITICAL: prevents memory leak
    }
}

InheritableThreadLocal

When a parent thread spawns a child thread, InheritableThreadLocal copies the parent's value to the child.

private static final InheritableThreadLocal<String> requestId =
    new InheritableThreadLocal<>();

public void parentMethod() {
    requestId.set("REQ-12345");

    new Thread(() -> {
        System.out.println(requestId.get()); // "REQ-12345" -- inherited!
    }).start();
}

Limitation: Only works at child thread creation time. If the parent changes the value later, the child won't see the update.

ThreadLocal vs Virtual Threads (Project Loom)

ScopedValue (Java 21+ Preview)

ScopedValue is the replacement for ThreadLocal in virtual thread contexts:

// Java 21+ (Preview)
private static final ScopedValue<UserContext> CURRENT_USER = ScopedValue.newInstance();

public void handleRequest(HttpServletRequest request) {
    UserContext user = extractUser(request);

    ScopedValue.runWhere(CURRENT_USER, user, () -> {
        // Any code here (and its callees) can read CURRENT_USER.get()
        processBusinessLogic();
        // Automatically unbound when lambda completes -- no leak possible!
    });
}

Advantages over ThreadLocal:

• Immutable within scope (cannot be changed by callees)
• Automatically cleaned up (no .remove() needed)
• Efficient with virtual threads (inherited via structured concurrency)
• No memory leak possible by design

CountDownLatch — Wait for N Events

Concept

A one-shot gate: one or more threads wait until a counter reaches zero. Other threads count down.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    participant M as Main
    participant S1 as Svc1
    participant S2 as Svc2
    participant S3 as Svc3

    rect rgba(219, 234, 254, 0.3)
        Note over M,S3: Init Phase
        M->>S1: start()
        M->>S2: start()
        M->>S3: start()
        M->>M: await() BLOCKED
    end

    rect rgba(209, 250, 229, 0.3)
        Note over M,S3: Services Ready
        S1->>M: countDown() [2]
        S3->>M: countDown() [1]
        S2->>M: countDown() [0]
    end

    rect rgba(254, 243, 199, 0.3)
        Note over M: Gate opens
        M->>M: All ready, accept traffic
    end

Code Example

public class ServiceInitializer {

    public static void main(String[] args) throws InterruptedException {
        int serviceCount = 3;
        CountDownLatch latch = new CountDownLatch(serviceCount);

        // Start services in parallel
        for (String svc : List.of("Database", "Cache", "MessageQueue")) {
            new Thread(() -> {
                try {
                    initializeService(svc);
                    System.out.println(svc + " ready!");
                } finally {
                    latch.countDown();  // signal completion
                }
            }).start();
        }

        latch.await();  // blocks until count == 0
        System.out.println("All services ready. Starting application...");
    }
}

CyclicBarrier — All Meet, Then Go

Concept

N threads arrive at a barrier point and all wait until the last one arrives. Then all are released simultaneously. Unlike CountDownLatch, it is reusable.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    participant T1 as T1
    participant T2 as T2
    participant T3 as T3
    participant B as Barrier

    rect rgba(219, 234, 254, 0.3)
        Note over T1,B: Phase 1: Arrive
        T1->>B: await() [1/3] BLOCKED
        T3->>B: await() [2/3] BLOCKED
        T2->>B: await() [3/3] TRIPPED
    end

    rect rgba(209, 250, 229, 0.3)
        Note over T1,B: Barrier action runs
        B->>B: action.run()
    end

    rect rgba(254, 243, 199, 0.3)
        Note over T1,B: All released
        B-->>T1: proceed
        B-->>T2: proceed
        B-->>T3: proceed
    end

    rect rgba(254, 226, 226, 0.3)
        Note over T1,B: Phase 2: Reuse
        T1->>B: await() [1/3]
        T2->>B: await() [2/3]
        T3->>B: await() [3/3] TRIPPED
    end

Code Example

public class ParallelMatrixMultiply {

    public static void main(String[] args) {
        int workers = 4;
        CyclicBarrier barrier = new CyclicBarrier(workers, () -> {
            // This runs after ALL threads arrive (barrier action)
            System.out.println("--- Phase complete. Merging results. ---");
        });

        for (int i = 0; i < workers; i++) {
            final int workerId = i;
            new Thread(() -> {
                try {
                    // Phase 1: compute partial result
                    computePartialResult(workerId);
                    barrier.await();  // wait for all workers

                    // Phase 2: read merged results, compute next phase
                    computeNextPhase(workerId);
                    barrier.await();  // barrier reused!

                } catch (InterruptedException | BrokenBarrierException e) {
                    Thread.currentThread().interrupt();
                }
            }).start();
        }
    }
}

CountDownLatch vs CyclicBarrier

Semaphore — Permit Pool

Concept

A semaphore maintains a set of permits. Threads acquire() a permit before accessing a resource, and release() it when done. If no permits are available, acquire() blocks.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    subgraph Pool["Semaphore permits=3"]
        P1["Permit 1"]
        P2["Permit 2"]
        P3["Permit 3"]
    end

    subgraph Active["Holding Permit"]
        T1["T1 acquired"]
        T2["T2 acquired"]
        T3["T3 acquired"]
    end

    subgraph Waiting["Blocked"]
        T4["T4 waiting"]
        T5["T5 waiting"]
    end

    P1 ==> T1
    P2 ==> T2
    P3 ==> T3
    T4 -.->|"blocks"| Pool
    T5 -.->|"blocks"| Pool

    style P1 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style P2 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style P3 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style T1 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T2 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T3 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T4 fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B
    style T5 fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B

Code Example

public class ConnectionPool {
    private final Semaphore semaphore;
    private final BlockingQueue<Connection> pool;

    public ConnectionPool(int maxConnections) {
        this.semaphore = new Semaphore(maxConnections, true); // fair=true
        this.pool = new LinkedBlockingQueue<>();
        for (int i = 0; i < maxConnections; i++) {
            pool.add(createConnection());
        }
    }

    public Connection acquire() throws InterruptedException {
        semaphore.acquire();        // blocks if no permits available
        return pool.poll();         // safe -- permit guarantees availability
    }

    public void release(Connection conn) {
        pool.offer(conn);
        semaphore.release();        // return permit
    }
}

Use Cases

Binary Semaphore vs Mutex (Lock)

Phaser — Dynamic Multi-Phase Synchronization

Concept

A Phaser is like a CyclicBarrier on steroids:

• Supports dynamic registration/deregistration of parties
• Supports multiple phases (numbered 0, 1, 2, ...)
• Parties can arrive and choose to advance or deregister

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    subgraph Phase0["Phase 0: Load"]
        T1P0["T1 arrive"]
        T2P0["T2 arrive"]
        T3P0["T3 arrive"]
    end

    subgraph Phase1["Phase 1: Process"]
        T1P1["T1 arrive"]
        T2P1["T2 arrive"]
        T3P1["T3 deregisters"]
    end

    subgraph Phase2["Phase 2: Aggregate"]
        T1P2["T1 arrive"]
        T2P2["T2 arrive"]
        T4P2["T4 new, registers"]
    end

    Phase0 ==> Phase1
    Phase1 ==> Phase2

    style T1P0 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T2P0 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T3P0 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style T1P1 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style T2P1 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style T3P1 fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B
    style T1P2 fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style T2P2 fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style T4P2 fill:#ECFDF5,stroke:#6EE7B7,color:#065F46

Code Example

public class PhasedComputation {

    public static void main(String[] args) {
        Phaser phaser = new Phaser(1); // register self (main thread)

        for (int i = 0; i < 3; i++) {
            phaser.register();  // dynamically add party
            final int id = i;
            new Thread(() -> {
                // Phase 0
                System.out.println("Worker-" + id + " loading data");
                phaser.arriveAndAwaitAdvance(); // wait for all

                // Phase 1
                System.out.println("Worker-" + id + " processing");
                phaser.arriveAndAwaitAdvance();

                // Phase 2 -- Worker-2 drops out
                if (id == 2) {
                    phaser.arriveAndDeregister(); // leave gracefully
                    return;
                }
                System.out.println("Worker-" + id + " aggregating");
                phaser.arriveAndAwaitAdvance();
            }).start();
        }

        // Main thread coordinates
        phaser.arriveAndAwaitAdvance(); // Phase 0
        phaser.arriveAndAwaitAdvance(); // Phase 1
        phaser.arriveAndDeregister();   // Main leaves
    }
}

Phaser vs CyclicBarrier

Exchanger — Two-Thread Rendezvous

Concept

An Exchanger allows exactly two threads to swap objects at a synchronization point. Each thread presents an object and receives the other thread's object.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    participant P as Prod
    participant E as Exch
    participant C as Cons

    rect rgba(219, 234, 254, 0.3)
        Note over P,C: Both arrive
        P->>E: exchange(fullBuf)
        Note over P: BLOCKED
        C->>E: exchange(emptyBuf)
    end

    rect rgba(209, 250, 229, 0.3)
        Note over P,C: Atomic swap
        E-->>P: gets emptyBuf
        E-->>C: gets fullBuf
    end

    rect rgba(254, 243, 199, 0.3)
        Note over P,C: Proceed
        P->>P: Fill buffer
        C->>C: Process buffer
    end

Code Example

public class PipelineWithExchanger {

    public static void main(String[] args) {
        Exchanger<List<String>> exchanger = new Exchanger<>();

        // Producer: fills buffer, swaps for empty one
        new Thread(() -> {
            List<String> buffer = new ArrayList<>();
            while (true) {
                buffer.add(generateData());
                if (buffer.size() == 100) {
                    try {
                        buffer = exchanger.exchange(buffer); // swap full for empty
                        buffer.clear(); // reuse received empty buffer
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        break;
                    }
                }
            }
        }).start();

        // Consumer: processes buffer, swaps empty one back
        new Thread(() -> {
            List<String> buffer = new ArrayList<>();
            while (true) {
                try {
                    buffer = exchanger.exchange(buffer); // swap empty for full
                    buffer.forEach(PipelineWithExchanger::process);
                    buffer.clear();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    break;
                }
            }
        }).start();
    }
}

Comparison Table: All Synchronization Aids

Quick Recall Table

Interview Answer Template

Common Interview Questions