Thread Safety - Learning Module

Loading content...

0/246

Designing for Thread Safety

From Understanding to Engineering

Understanding thread safety is one thing. Engineering thread-safe systems is another entirely.

Up to this point, we've explored what thread safety means, how shared mutable state creates hazards, and how race conditions manifest. Now we transition from diagnosis to treatment—from understanding problems to systematically designing solutions.

Great concurrent code isn't the result of sprinkling locks everywhere until bugs disappear. It's the result of deliberate design: choosing the right architecture, applying proven patterns, documenting invariants, and building systems where thread safety is a natural consequence of the structure rather than a patched-on afterthought.

What You Will Learn

By the end of this page, you will understand the core principles of thread-safe design, when and how to apply different concurrency strategies, how to document thread safety contracts, and a systematic methodology for building reliable concurrent systems. You'll develop the engineering mindset needed to make sound concurrency decisions.

The Thread-Safe Design Mindset

Before diving into techniques, let's establish the mental framework that guides thread-safe design.

Principle 1: Thread Safety is a Design Property, Not a Patch

Thread safety should be considered from the very first design decisions—not added after the fact. Retrofitting thread safety onto a design that assumed single-threaded execution is expensive, error-prone, and often results in poor performance due to coarse-grained locking.

Principle 2: Simplicity is the Ultimate Sophistication

The best concurrent code is often the simplest. Complex synchronization schemes are hard to reason about, hard to test, and hard to maintain. Prefer:

Immutable objects over synchronized mutable objects
Thread confinement over shared state
Message passing over shared memory
Higher-level abstractions over low-level primitives

Core Design Principles

•Minimize mutable state — Every mutable variable is a potential concurrency hazard. Question each one.
•Minimize shared state — If state must exist, can it be thread-local? Request-scoped? Per-actor?
•Minimize the scope of synchronization — Lock only what needs locking, for only as long as necessary.
•Establish clear ownership — Every piece of mutable state should have exactly one owner at any time.
•Design for invariant preservation — Identify what must always be true; ensure atomicity around those invariants.
•Document thread safety contracts — Explicit documentation prevents assumptions that lead to bugs.

The 'What If' Question

For every piece of state and every operation, ask: "What if another thread is accessing this right now?" If the answer is "bad things happen" or "I'm not sure," you have a design problem to address.

Design Strategies in Depth

We introduced three fundamental strategies earlier: immutability, confinement, and synchronization. Let's explore each in depth, with practical guidance on when and how to apply them.

Immutability is the gold standard for thread safety. An immutable object cannot be corrupted by concurrent access because there's nothing to corrupt—no state changes after construction.

When to use immutability:

Value objects (dates, points, money, identifiers)
Configuration objects
Domain events
Transfer objects across thread boundaries
Whenever state conceptually represents a "snapshot"

How to implement immutability correctly:

Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
// COMPREHENSIVE IMMUTABLE CLASS
public final class ImmutableOrder {
    private final String orderId;
    private final String customerId;
    private final List<OrderItem> items;  // Must be immutable too!
    private final BigDecimal total;
    private final Instant createdAt;
    
    public ImmutableOrder(String orderId, String customerId, 
                          List<OrderItem> items, BigDecimal total) {
        // Validate invariants in constructor
        if (orderId == null || orderId.isEmpty()) {
            throw new IllegalArgumentException("orderId required");
        }
        
        this.orderId = orderId;
        this.customerId = customerId;
        // DEFENSIVE COPY: Don't let caller mutate our list
        this.items = List.copyOf(items);  // Immutable copy in Java 10+
        this.total = total;
        this.createdAt = Instant.now();
    }
    
    // GETTERS ONLY - no setters
    public String getOrderId() { return orderId; }
    public String getCustomerId() { return customerId; }
    
    // Return immutable view (List.copyOf already returns immutable)
    public List<OrderItem> getItems() { return items; }
    
    public BigDecimal getTotal() { return total; }
    public Instant getCreatedAt() { return createdAt; }
    
    // "MODIFICATION" creates new object
    public ImmutableOrder withItems(List<OrderItem> newItems) {
        BigDecimal newTotal = calculateTotal(newItems);
        return new ImmutableOrder(orderId, customerId, newItems, newTotal);
    }
    
    // Derived state computation (always consistent)
    public int getItemCount() {
        return items.size();
    }
    
    private static BigDecimal calculateTotal(List<OrderItem> items) {
        return items.stream()
            .map(OrderItem::getSubtotal)
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}
 
// OrderItem must also be immutable!
public final class OrderItem {
    private final String productId;
    private final int quantity;
    private final BigDecimal unitPrice;
    
    public OrderItem(String productId, int quantity, BigDecimal unitPrice) {
        this.productId = Objects.requireNonNull(productId);
        this.quantity = quantity;
        this.unitPrice = Objects.requireNonNull(unitPrice);
    }
    
    public BigDecimal getSubtotal() {
        return unitPrice.multiply(BigDecimal.valueOf(quantity));
    }
    
    // Getters only...
}

Critical requirements for immutability:

All fields are final (or never reassigned)
Class is final (or otherwise non-subclassable)
No mutating methods (setters, add, remove, etc.)
Defensive copies of mutable inputs and outputs
All nested objects are also immutable
Don't let this escape during construction

Designing Classes for Thread Safety

When designing a class that will be used in concurrent contexts, follow this systematic approach.

Thread-Safe Class Design Checklist

•Identify all state — List every field in the class, including inherited fields.
•Identify invariants — What must always be true about the relationships between fields?
•Determine thread safety level — Will this be immutable, unconditionally thread-safe, conditionally thread-safe, or thread-compatible?
•Choose your strategy — Immutability? Confinement? Synchronization?
•Design for atomicity — Which operations must be atomic? Which combinations of operations?
•Document the contract — What guarantees does your class provide? What requirements does it place on callers?

thread-safe-class-design.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
/**
 * A thread-safe bounded counter with minimum and maximum limits.
 * 
 * <h2>Thread Safety</h2>
 * This class is <b>unconditionally thread-safe</b>. All operations are atomic
 * and can be called from any thread without external synchronization.
 * 
 * <h3>Invariants</h3>
 * <ul>
 *   <li>min <= value <= max (always maintained)</li>
 *   <li>min < max (validated at construction)</li>
 * </ul>
 * 
 * <h3>Implementation Notes</h3>
 * Uses compare-and-swap for lock-free operation. Under contention,
 * operations may retry, but forward progress is guaranteed.
 * 
 * @ThreadSafe
 */
public final class BoundedCounter {
    
    // STATE: Single AtomicInteger is easiest to reason about
    // INVARIANT: value is always in [min, max]
    private final AtomicInteger value;
    private final int min;
    private final int max;
    
    /**
     * Creates a bounded counter.
     * 
     * @param initial initial value; must satisfy min <= initial <= max
     * @param min minimum value (inclusive)
     * @param max maximum value (inclusive); must be > min
     * @throws IllegalArgumentException if constraints are violated
     */
    public BoundedCounter(int initial, int min, int max) {
        // VALIDATE invariants at construction
        if (min >= max) {
            throw new IllegalArgumentException("min must be < max");
        }
        if (initial < min || initial > max) {
            throw new IllegalArgumentException("initial must be in [min, max]");
        }
        
        this.min = min;
        this.max = max;
        this.value = new AtomicInteger(initial);
    }
    
    /**
     * Returns the current value.
     * <p>
     * Note: In a concurrent environment, the value may change immediately
     * after this method returns.
     */
    public int get() {
        return value.get();
    }
    
    /**
     * Atomically increments if not at maximum.
     * 
     * @return true if incremented, false if already at max
     */
    public boolean tryIncrement() {
        while (true) {
            int current = value.get();
            if (current >= max) {
                return false;  // At limit
            }
            if (value.compareAndSet(current, current + 1)) {
                return true;  // Success
            }
            // CAS failed, retry
        }
    }
    
    /**
     * Atomically decrements if not at minimum.
     * 
     * @return true if decremented, false if already at min
     */
    public boolean tryDecrement() {
        while (true) {
            int current = value.get();
            if (current <= min) {
                return false;  // At limit
            }
            if (value.compareAndSet(current, current - 1)) {
                return true;  // Success
            }
            // CAS failed, retry
        }
    }
    
    /**
     * Atomically sets value if it doesn't violate bounds.
     * 
     * @param newValue desired value
     * @return true if set, false if newValue would violate bounds
     */
    public boolean trySet(int newValue) {
        if (newValue < min || newValue > max) {
            return false;
        }
        value.set(newValue);
        return true;
    }
    
    /**
     * Returns the percentage of capacity used.
     */
    public double getUtilization() {
        int current = value.get();
        return (double)(current - min) / (max - min);
    }
}

Design for the Common Case

If your class will mostly be used in single-threaded contexts, consider making it thread-compatible (not internally synchronized) with clear documentation. Users can add external synchronization if needed. Don't pay synchronization costs when they're not needed.

Composing Thread-Safe Components

One of the trickiest aspects of concurrent design is composition. Thread-safe components don't automatically compose into thread-safe systems.

The Composition Problem

If you have two thread-safe counters, counterA and counterB, incrementing both in sequence is NOT atomic. Between the increments, another thread could read an inconsistent state where one is incremented and the other isn't.

composition-challenges.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
// PROBLEM: Two thread-safe components don't compose
public class ShoppingCart {
    private final ConcurrentMap<String, Integer> items = new ConcurrentHashMap<>();
    private final AtomicInteger totalItems = new AtomicInteger(0);
    
    // BUG: These two updates aren't atomic together!
    public void addItem(String productId, int quantity) {
        items.merge(productId, quantity, Integer::sum);  // Atomic
        // << READER THREAD SEES INCONSISTENT STATE >>
        totalItems.addAndGet(quantity);  // Atomic, but not with above!
    }
    
    // Reader might see items.values().sum() != totalItems.get()
}
 
// SOLUTION 1: External locking for compound operations
public class ShoppingCartSync {
    private final Map<String, Integer> items = new HashMap<>();
    private int totalItems = 0;
    private final Object lock = new Object();
    
    public void addItem(String productId, int quantity) {
        synchronized (lock) {
            items.merge(productId, quantity, Integer::sum);
            totalItems += quantity;  // Both update atomically
        }
    }
    
    public int getTotalItems() {
        synchronized (lock) {
            return totalItems;
        }
    }
}
 
// SOLUTION 2: Immutable snapshots
public class ShoppingCartImmutable {
    private final AtomicReference<CartState> state = 
        new AtomicReference<>(CartState.EMPTY);
    
    public void addItem(String productId, int quantity) {
        while (true) {
            CartState current = state.get();
            CartState next = current.withItem(productId, quantity);
            if (state.compareAndSet(current, next)) {
                return;  // Atomically swapped to new state
            }
            // CAS failed, retry with latest state
        }
    }
    
    public CartState getSnapshot() {
        return state.get();  // Immutable, safe to use
    }
}
 
// SOLUTION 3: Delegate to single thread-safe object
public class ShoppingCartDelegated {
    private final ConcurrentMap<String, Integer> items = new ConcurrentHashMap<>();
    
    public void addItem(String productId, int quantity) {
        items.merge(productId, quantity, Integer::sum);
    }
    
    // Compute totalItems from source of truth (items map)
    public int getTotalItems() {
        return items.values().stream().mapToInt(Integer::intValue).sum();
    }
}

Guidelines for composing thread-safe systems:

Single source of truth — Derive all state from one authoritative source rather than maintaining synchronized duplicates.
Immutable composition — Compose immutable objects; swap entire state atomically using AtomicReference.
Same-lock composition — When multiple variables must be consistent, protect them with the same lock.
Transaction boundaries — Define clear transaction boundaries that encompass all related operations.
Avoid splitting invariants — If an invariant spans multiple objects, they must share synchronization.

Documenting Thread Safety

Thread safety documentation is not optional—it's essential for maintainability and correctness. Undocumented thread safety assumptions lead to bugs when other developers (including future you) make incorrect assumptions.

What to Document

•Thread safety level — Is the class immutable, unconditionally thread-safe, conditionally thread-safe, or thread-compatible?
•Thread safety contract — What guarantees does it provide? What does it require from callers?
•Which lock protects what — For synchronized classes, document which lock protects which state.
•External synchronization requirements — For conditionally thread-safe classes, exactly what must callers synchronize?
•Non-obvious safety boundaries — Compound operations that aren't atomic, iteration caveats, etc.
•Mutability of returned objects — Are returned collections modifiable? Are they views or copies?

documentation-examples.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
/**
 * Thread-safe cache with automatic expiration.
 * 
 * <h2>Thread Safety</h2>
 * This class is <b>unconditionally thread-safe</b>. Concurrent calls to
 * {@link #get}, {@link #put}, and {@link #remove} are safe without external
 * synchronization.
 * 
 * <h3>Atomicity Guarantees</h3>
 * <ul>
 *   <li>{@link #put} is atomic: the value is immediately visible to readers</li>
 *   <li>{@link #computeIfAbsent} is atomic: factory is called at most once per key</li>
 *   <li>{@link #getAll()} returns a <b>snapshot</b>; modifications to the cache
 *       after the call are not visible in the returned map</li>
 * </ul>
 * 
 * <h3>Caveats</h3>
 * The values stored in the cache are not copied. If you store mutable objects,
 * you are responsible for their thread safety. Consider storing immutable values.
 * 
 * <h3>Locking Details (Implementation Note)</h3>
 * This class uses a striped lock approach with 16 segments. High concurrency
 * on different keys should not cause contention. Segment lock is the key's
 * hash modulo number of segments.
 * 
 * @param <K> key type
 * @param <V> value type
 * 
 * @ThreadSafe
 */
public class ExpiringCache<K, V> {
    // ...
}
 
/**
 * Mutable user session data.
 * 
 * <h2>Thread Safety</h2>
 * This class is <b>thread-compatible</b>. Instances are designed to be confined
 * to a single request thread. If you must share a session across threads,
 * external synchronization is required for all access.
 * 
 * <h3>Typical Usage</h3>
 * <pre>
 * // In request handler (single-threaded context)
 * UserSession session = sessionStore.get(sessionId);
 * session.setAttribute("cart", cart);  // Safe: single thread
 * </pre>
 * 
 * <h3>Multi-threaded Usage (if required)</h3>
 * <pre>
 * synchronized (session) {
 *     session.setAttribute("key", value);
 *     doSomething(session.getAttribute("key"));
 * }
 * </pre>
 * 
 * @NotThreadSafe  // Using custom or standard annotations
 */
public class UserSession {
    // ...
}

Use Annotations

Consider using thread safety annotations from JCIP (Java Concurrency in Practice): @ThreadSafe, @NotThreadSafe, @Immutable, @GuardedBy. These serve as documentation and can be checked by static analysis tools.

Practical Design Patterns

Here are battle-tested patterns for common thread-safe design challenges.

Safe Lazy Initialization

•Use static initializer (JVM guarantees thread safety)
•Use enum singleton pattern
•Use Lazy Holder idiom for on-demand initialization
•Use AtomicReference with CAS for mutable singletons

Safe Publication

•Initialize in static initializer
•Store reference in volatile field
•Store reference in AtomicReference
•Store in final field of properly constructed object
•Store in field guarded by lock

design-patterns.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
// PATTERN 1: Lazy Holder Idiom (best for lazy singletons)
public class ExpensiveService {
    // Lazy initialization without synchronization overhead
    private static class Holder {
        static final ExpensiveService INSTANCE = new ExpensiveService();
    }
    
    private ExpensiveService() {
        // Expensive initialization
    }
    
    public static ExpensiveService getInstance() {
        return Holder.INSTANCE;  // Class initialization is thread-safe
    }
}
 
// PATTERN 2: Immutable Holder for atomic multi-field update
public class ServerConfig {
    // Multiple related fields that must update atomically
    private static final class ConfigHolder {
        final String host;
        final int port;
        final Duration timeout;
        
        ConfigHolder(String host, int port, Duration timeout) {
            this.host = host;
            this.port = port;
            this.timeout = timeout;
        }
    }
    
    private final AtomicReference<ConfigHolder> config = new AtomicReference<>();
    
    public void updateConfig(String host, int port, Duration timeout) {
        config.set(new ConfigHolder(host, port, timeout));  // Atomic!
    }
    
    public String getHost() { return config.get().host; }
    public int getPort() { return config.get().port; }
}
 
// PATTERN 3: Copy-on-Write for rarely-updated, frequently-read
public class ListenerRegistry {
    // Volatile ensures visibility of the immutable list reference
    private volatile List<Listener> listeners = List.of();
    
    public void addListener(Listener listener) {
        synchronized (this) {
            List<Listener> newList = new ArrayList<>(listeners);
            newList.add(listener);
            listeners = List.copyOf(newList);  // Publish immutable copy
        }
    }
    
    public void notifyAll(Event event) {
        // No synchronization needed - list is immutable
        for (Listener listener : listeners) {
            listener.onEvent(event);
        }
    }
}
 
// PATTERN 4: Read-Write separation with snapshots
public class MetricsRegistry {
    private final ConcurrentMap<String, AtomicLong> counters = new ConcurrentHashMap<>();
    
    // Hot path - high-frequency writes
    public void increment(String metric) {
        counters.computeIfAbsent(metric, k -> new AtomicLong()).incrementAndGet();
    }
    
    // Cold path - occasional reads for reporting
    public Map<String, Long> getSnapshot() {
        return counters.entrySet().stream()
            .collect(Collectors.toUnmodifiableMap(
                Map.Entry::getKey,
                e -> e.getValue().get()
            ));
    }
}

Summary: Engineering Thread-Safe Systems

We've covered the principles and practices of designing thread-safe systems. Let's consolidate the key takeaways:

Key Takeaways

•Thread safety is a design property — It must be built in from the start, not patched on later. Simplicity is the best guide.
•Prefer immutability, then confinement, then synchronization — Each step down this hierarchy adds complexity and room for error.
•Design classes systematically — Identify state, identify invariants, choose strategy, document contract.
•Thread-safe components don't compose automatically — Compound operations across components need additional synchronization or design patterns.
•Documentation is essential — Thread safety contracts, lock documentation, and usage guidelines prevent future bugs.
•Apply proven patterns — Lazy holder, copy-on-write, immutable holder, and snapshot patterns solve common problems safely.

Module Complete:

You've now completed the Thread Safety module. You understand:

What thread safety means and its levels
Why shared mutable state is dangerous
How race conditions manifest and how to prevent them
How to design thread-safe classes and systems

The next module will explore Synchronization Primitives in depth—the specific tools (mutexes, semaphores, monitors) you'll use when synchronization is necessary.

Module Complete

Congratulations! You've mastered the fundamentals of thread safety. You can now identify thread safety issues, choose appropriate strategies, design thread-safe classes, and document thread safety contracts. These skills form the foundation for all concurrent programming.