Java volatile Keyword Explained — Memory Visibility, Happens-Before, and When It's Not Enough

/**
 * Demonstrates the stale-read problem WITHOUT volatile,
 * then fixes it WITH volatile.
 *
 * Run with: java StaleReadDemo
 * JVM flag to make the bug more reproducible: -server
 */
public class StaleReadDemo {

    // ❌ Without volatile — the JIT may cache this in a register.
    // The worker thread might loop forever even after main sets it true.
    private static boolean shutdownRequestedUnsafe = false;

    // ✅ With volatile — every read goes to main memory. No caching allowed.
    private static volatile boolean shutdownRequested = false;

    public static void main(String[] args) throws InterruptedException {

        Thread worker = new Thread(() -> {
            long iterationCount = 0;

            // The JIT compiler, in server mode, may decide this value
            // never changes (from *this* thread's perspective) and hoist
            // the read outside the loop entirely — an infinite loop ensues.
            while (!shutdownRequested) {
                iterationCount++;

                // Intentionally empty loop body — we're testing visibility only.
                // Adding a System.out.println here would mask the bug because
                // println acquires a monitor lock, which flushes thread-local memory.
            }

            System.out.println("Worker stopped cleanly after " + iterationCount + " iterations.");
        }, "background-worker");

        worker.start();

        // Give the worker time to get fully JIT-compiled and into its hot loop.
        Thread.sleep(100);

        // Main thread updates the flag.
        shutdownRequested = true;
        System.out.println("Main thread set shutdownRequested = true");

        // Wait for the worker to notice. With volatile this completes quickly.
        // Without volatile (using shutdownRequestedUnsafe) this may hang forever.
        worker.join(2000);

        if (worker.isAlive()) {
            System.out.println("BUG: Worker is still running — it never saw the update!");
            worker.interrupt(); // clean up the demo
        }
    }
}

/**
 * Demonstrates the happens-before guarantee of volatile.
 * The volatile write acts as a full memory fence — all writes
 * before it become visible to any thread that sees the volatile write.
 *
 * This is the safe publication pattern used in production systems.
 */
public class VolatileHappensBefore {

    // The configuration object being published to worker threads.
    static class ServerConfig {
        final String hostName;        // final fields are safe, but
        final int    port;            // non-final fields also get
        String       environment;     // dragged across by the volatile fence.

        ServerConfig(String hostName, int port, String environment) {
            this.hostName    = hostName;
            this.port        = port;
            this.environment = environment;
        }
    }

    // ✅ volatile ensures: once a thread reads a non-null configRef,
    // it is guaranteed to see fully-initialized ServerConfig fields.
    private static volatile ServerConfig configRef = null;

    public static void main(String[] args) throws InterruptedException {

        Thread reader = new Thread(() -> {
            // Spin until the config is published (busy-wait for demo purposes only).
            while (configRef == null) {
                Thread.onSpinWait(); // hint to the CPU: we're in a spin loop
            }

            // Because configRef is volatile, the read of configRef happens-after
            // the write to configRef in the writer thread.
            // That means ALL writes the writer did BEFORE writing configRef
            // are also visible here — including the non-final 'environment' field.
            ServerConfig config = configRef;
            System.out.println("Reader sees host:        " + config.hostName);
            System.out.println("Reader sees port:        " + config.port);
            System.out.println("Reader sees environment: " + config.environment);
        }, "config-reader");

        reader.start();

        Thread.sleep(50); // let the reader get into its spin loop

        // Writer constructs the object fully BEFORE the volatile write.
        ServerConfig freshConfig = new ServerConfig("api.example.com", 8443, "production");

        // This single volatile write acts as a release fence.
        // Every write above this line is flushed to main memory before this store.
        configRef = freshConfig;
        System.out.println("Writer published config via volatile write.");

        reader.join();
    }
}

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * Proves that volatile does NOT prevent lost updates on compound operations.
 * Runs 10 threads each incrementing a counter 10,000 times.
 * Expected final value: 100,000
 *
 * Three counter implementations are compared:
 *   1. volatile int          — loses updates (race condition)
 *   2. synchronized int      — correct, but slower
 *   3. AtomicInteger         — correct and fast (preferred)
 */
public class VolatileCounterRaceCondition {

    // ❌ volatile does NOT make ++ atomic.
    private static volatile int volatileCounter = 0;

    // ✅ synchronized makes the entire read-modify-write atomic.
    private static int synchronizedCounter = 0;

    // ✅ AtomicInteger uses CAS — atomic AND lock-free.
    private static final AtomicInteger atomicCounter = new AtomicInteger(0);

    private static final int THREAD_COUNT      = 10;
    private static final int INCREMENTS_EACH   = 10_000;
    private static final int EXPECTED_TOTAL    = THREAD_COUNT * INCREMENTS_EACH;

    public static void main(String[] args) throws InterruptedException {
        CountDownLatch startGate = new CountDownLatch(1); // all threads start at once
        CountDownLatch doneGate  = new CountDownLatch(THREAD_COUNT);

        for (int threadIndex = 0; threadIndex < THREAD_COUNT; threadIndex++) {
            new Thread(() -> {
                try {
                    startGate.await(); // wait for the starting gun

                    for (int i = 0; i < INCREMENTS_EACH; i++) {
                        volatileCounter++;          // ❌ read-modify-write — NOT atomic

                        synchronized (VolatileCounterRaceCondition.class) {
                            synchronizedCounter++;  // ✅ entire operation is serialized
                        }

                        atomicCounter.incrementAndGet(); // ✅ single CAS instruction
                    }
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                } finally {
                    doneGate.countDown();
                }
            }).start();
        }

        startGate.countDown(); // fire the starting gun
        doneGate.await();      // wait for all threads to finish

        System.out.println("Expected total       : " + EXPECTED_TOTAL);
        System.out.println("volatile result      : " + volatileCounter      + (volatileCounter      == EXPECTED_TOTAL ? " ✅" : " ❌ LOST UPDATES!"));
        System.out.println("synchronized result  : " + synchronizedCounter  + (synchronizedCounter  == EXPECTED_TOTAL ? " ✅" : " ❌"));
        System.out.println("AtomicInteger result : " + atomicCounter.get()  + (atomicCounter.get()  == EXPECTED_TOTAL ? " ✅" : " ❌"));
    }
}

/**
 * Thread-safe lazy singleton using Double-Checked Locking (DCL).
 * This is the correct, production-safe pattern as of Java 5+.
 *
 * The volatile keyword on 'instance' is NOT optional.
 * Without it, instruction reordering can expose a partially
 * constructed object to threads that win the second null-check.
 */
public class SafeSingletonDCL {

    // ✅ volatile prevents the JIT from reordering the constructor
    // writes with the store to this reference field.
    // Without volatile, another thread could see non-null instance
    // but still read uninitialised field values from the object.
    private static volatile SafeSingletonDCL instance = null;

    private final String databaseUrl;
    private final int    maxConnections;

    // Private constructor simulates expensive initialisation.
    private SafeSingletonDCL() {
        // Pretend this takes 200ms to initialise a connection pool.
        this.databaseUrl    = "jdbc:postgresql://prod-db:5432/app";
        this.maxConnections = 20;
        System.out.println("[" + Thread.currentThread().getName() + "] Constructor running — expensive setup done.");
    }

    public static SafeSingletonDCL getInstance() {
        // First check — no lock. The vast majority of calls take this fast path
        // once the singleton is initialised. volatile ensures we see the true value.
        if (instance == null) {

            // Only one thread should run the constructor.
            synchronized (SafeSingletonDCL.class) {

                // Second check — we now hold the lock, but another thread
                // might have already initialised it while we were waiting.
                if (instance == null) {
                    instance = new SafeSingletonDCL(); // volatile write = release barrier
                }
            }
        }
        return instance; // volatile read = acquire barrier
    }

    public String getDatabaseUrl()    { return databaseUrl; }
    public int    getMaxConnections() { return maxConnections; }

    // ---- Demo main -------------------------------------------------------
    public static void main(String[] args) throws InterruptedException {
        int threadCount = 8;
        Thread[] threads = new Thread[threadCount];

        for (int i = 0; i < threadCount; i++) {
            threads[i] = new Thread(() -> {
                SafeSingletonDCL singleton = SafeSingletonDCL.getInstance();
                // Every thread must print the same object hash and URL.
                System.out.printf("[%-20s] instance@%d  url=%s  maxConn=%d%n",
                    Thread.currentThread().getName(),
                    System.identityHashCode(singleton),
                    singleton.getDatabaseUrl(),
                    singleton.getMaxConnections());
            }, "worker-" + i);
        }

        for (Thread t : threads) t.start();
        for (Thread t : threads) t.join();
    }
}