Immutability, Thread Confinement & ThreadLocal

#Introduction

The most reliable way to avoid concurrency bugs is to not share mutable state at all. There are two ways to do that: make shared data immutable, or keep mutable data confined to one thread. This chapter covers both — and ThreadLocal, Java's built-in tool for per-thread state.

#Immutability and Multithreading

Java uses immutability to guarantee that certain objects, once created, can't be changed. That's critical for safe, efficient multithreading: if data can't change, multiple threads can't corrupt it or read it in an inconsistent state.

How Java Supports Immutability

• Built-in immutable classes — String, the wrapper types (Integer, Long…), BigDecimal, BigInteger and the java.time classes (LocalDate, Instant, Duration). Their state is set at creation and never changes.
• Records — previewed in Java 14 and final in Java 16. A record's fields are private final, set once in the constructor, with no setters.
• Unmodifiable collections — List.of(), Set.of(), Map.of() (Java 9) and List.copyOf() (Java 10).
• Custom immutable classes — make the class final, all fields private final, provide no setters, and defensively copy mutable inputs and outputs.

public final class Money {
    private final BigDecimal amount;
    private final Currency currency;
    private final List<String> tags;

    public Money(BigDecimal amount, Currency currency, List<String> tags) {
        this.amount = amount;
        this.currency = currency;
        this.tags = List.copyOf(tags);           // defensive copy — caller can't mutate it later
    }

    public Money add(Money other) {              // "modification" returns a new object
        return new Money(amount.add(other.amount), currency, tags);
    }

    public BigDecimal amount() { return amount; }
    public List<String> tags() { return tags; }  // already unmodifiable
}

Why Immutability Matters for Concurrency

• Thread safety — immutable objects are inherently thread-safe; any number of threads can read them simultaneously without locks, which reduces complexity and improves performance.
• No race conditions — nothing can be written after construction, so there are no conflicting writes.
• Visibility guarantees — the Java Memory Model guarantees that final fields are fully visible to all threads once the constructor finishes (provided this didn't escape during construction), so no thread sees stale or half-built state.
• Easier reasoning — no need to track who might change an object, or when.
• Safe hash keys — objects whose state never changes keep a stable hashCode(), so they're safe as HashMap keys.
• Free sharing and caching — Integer.valueOf() caches small values and string literals are interned precisely because they're immutable.

String is the textbook example: methods that seem to modify it (concat(), toUpperCase(), replace()) return new strings. Many threads can share the same string safely, and its hash code is computed once and cached.

#Thread Confinement

If only one thread ever accesses an object, it needs no synchronization even if it's mutable:

public String format(List<Order> orders) {
    StringBuilder sb = new StringBuilder();   // confined to this call — no sharing, no locking
    for (Order o : orders) sb.append(o.id()).append(',');
    return sb.toString();
}

#ThreadLocal

ThreadLocal<T> gives each thread its own independent copy of a variable:

public final class RequestContext {

    private static final ThreadLocal<String> CORRELATION_ID = new ThreadLocal<>();

    public static void set(String id) { CORRELATION_ID.set(id); }
    public static String get()        { return CORRELATION_ID.get(); }
    public static void clear()        { CORRELATION_ID.remove(); }
}

// Each thread holds a different value under the same ThreadLocal
Thread a = new Thread(() -> { RequestContext.set("req-A"); System.out.println(RequestContext.get()); });
Thread b = new Thread(() -> { RequestContext.set("req-B"); System.out.println(RequestContext.get()); });

req-A
req-B

How It Works

Each Thread object has its own ThreadLocalMap. The ThreadLocal instance is only the key; get() looks the value up in the current thread's map.

Common Uses

private static final ThreadLocal<SimpleDateFormat> FORMAT =
        ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

#InheritableThreadLocal

InheritableThreadLocal copies the parent thread's value into a child thread when the child is created:

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

It doesn't work as expected with thread pools: pool threads are created once, so they inherit whatever value existed then — not the value of the thread submitting each task. Prefer explicit propagation.

#Scoped Values (Java 25)

Scoped values (ScopedValue, finalized in Java 25 after several previews) are a modern alternative for passing immutable context down a call chain:

private static final ScopedValue<String> TENANT = ScopedValue.newInstance();

ScopedValue.where(TENANT, "acme").run(() -> {
    handleRequest();           // TENANT.get() returns "acme" anywhere inside this call
});
// outside the run() block TENANT is unbound again — nothing to clean up

#Key Takeaways

• Immutable objects are inherently thread-safe and need no locks.
• final fields of properly constructed objects are visible to every thread.
• Thread confinement — locals, single-owner threads, ThreadLocal — avoids sharing entirely.
• ThreadLocal gives each thread its own value; with pools, always remove() it.
• Context in ThreadLocals doesn't cross into other threads automatically.
• Scoped Values (Java 25) are a leak-free, immutable alternative.