Java Concurrency & Multithreading — Complete Notes

// 1. Extend Thread — DON'T. Burns your single inheritance slot, couples task to mechanism.
class MyThread extends Thread {
    public void run() { System.out.println("running"); }
}
new MyThread().start();

// 2. Implement Runnable — the task is a separate thing from the thread running it
class MyTask implements Runnable {
    public void run() { System.out.println("running"); }
}
new Thread(new MyTask()).start();

// 3. A lambda + an executor — what you should actually write (see section 08)
executor.submit(() -> System.out.println("running"));

Runnable task = () -> System.out.println(Thread.currentThread().getName());

new Thread(task).start();   // prints "Thread-0"  — a real new thread
new Thread(task).run();     // prints "main"      — no thread was created!

     NEW                          created, start() not yet called
      |  start()
      v
   RUNNABLE  <-------------+     runnable or running (Java doesn't distinguish)
      |                    |
      |  wants a lock      | lock acquired
      v                    |
   BLOCKED  --------------+      waiting to enter a synchronized block
      |
      |  wait() / join() / park()
      v
   WAITING  ---------------+     waiting indefinitely for another thread
      |  notify()/notifyAll()/interrupt()
      |
      |  wait(t) / sleep(t) / join(t)
      v
 TIMED_WAITING ----------+       same, but with a deadline
      |
      v
  TERMINATED                     run() finished (or threw)

Thread.sleep(1000);            // pause THIS thread ~1s. Holds any locks it owns! (see gotchas)
t.join();                      // block until t finishes
t.join(500);                   // ...or 500ms, whichever comes first
t.interrupt();                 // politely ASK t to stop — see below
Thread.currentThread();        // who am I
t.setDaemon(true);             // JVM won't wait for this thread to exit (MUST be before start())
t.setName("worker-1");         // do this — it makes thread dumps readable
Thread.yield();                // "I'd share the CPU" — a hint, usually useless

// Option A — let it propagate (best, if your signature allows it)
void work() throws InterruptedException {
    Thread.sleep(1000);
}

// Option B — you can't rethrow (e.g. inside Runnable.run) -> RESTORE THE FLAG
public void run() {
    try {
        Thread.sleep(1000);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();   // put the flag back!
        return;                               // and actually stop
    }
}

// WRONG — swallows the request. Your app now won't shut down.
try { Thread.sleep(1000); } catch (InterruptedException e) { }   // never do this

public void run() {
    while (!Thread.currentThread().isInterrupted()) {
        doChunkOfWork();
    }
    cleanup();
}

count++;

// is really:
//   1. READ  count from memory        (getfield)
//   2. ADD   1 to the value           (iadd)
//   3. WRITE the result back          (putfield)
//
// Another thread can interleave at ANY point between them.

// count = 0

// Thread A            | Thread B
// read count  -> 0    |
//                     | read count  -> 0      <- B reads before A wrote
// add 1       -> 1    |
//                     | add 1       -> 1
// write 1             |
//                     | write 1               <- overwrites A's work
//
// count == 1. Two increments happened. One vanished.

class Counter {
    private int count = 0;
    public void increment() { count++; }
    public int get() { return count; }
}

Counter c = new Counter();
Thread t1 = new Thread(() -> { for (int i = 0; i < 100_000; i++) c.increment(); });
Thread t2 = new Thread(() -> { for (int i = 0; i < 100_000; i++) c.increment(); });
t1.start(); t2.start();
t1.join();  t2.join();

System.out.println(c.get());   // Expected 200000. Actual: 137482. Or 189301. Never the same twice.

class Task {
    private boolean running = true;      // no volatile!

    public void stop() { running = false; }

    public void run() {
        while (running) { }              // may spin FOREVER, even after stop() is called
        System.out.println("stopped");
    }
}
// Main thread calls stop(). The worker thread may never notice — and often doesn't
// once the JIT warms up. Adding `volatile` to `running` fixes it completely.

// You wrote:              // Another thread might observe:
a = 1;                     //   flag = true;     <- reordered ahead!
flag = true;               //   a = 1;

// So a reader that sees flag == true can still read a == 0.
// Single-threaded semantics are preserved; cross-thread ones are not.

class Counter {
    private int count = 0;
    public synchronized void increment() { count++; }   // one thread at a time
    public synchronized int get() { return count; }     // MUST also be synchronized — see below
}
// Now always prints exactly 200000.

class Example {

    public synchronized void a() { }        // locks `this`

    public static synchronized void b() { } // locks Example.class — a DIFFERENT lock from `this`!

    public void c() {
        synchronized (this) { }             // identical to a()
    }

    private final Object lock = new Object();
    public void d() {
        synchronized (lock) { }             // locks a private object — usually the best choice
    }
}

// Risky: `this` is public, so ANY outside code can lock your object and stall you
class Bad {
    public synchronized void work() { }
}
Bad b = new Bad();
synchronized (b) { Thread.sleep(60_000); }   // outsider just froze every call to work()

// Safe: nobody outside can reach the lock
class Good {
    private final Object lock = new Object();   // final! reassigning a lock breaks everything
    public void work() { synchronized (lock) { } }
}

class Reentrant {
    public synchronized void outer() {
        inner();          // already hold the lock — walk straight in. No deadlock.
    }
    public synchronized void inner() { }
}
// The JVM keeps a hold COUNT: +1 on entry, -1 on exit. Released at zero.
// Without reentrancy, any object calling its own synchronized method would deadlock with itself.

// BAD — the network call holds the lock for 200ms
public synchronized void update(String id) {
    Data d = httpClient.fetch(id);       // slow! Everyone else is blocked.
    cache.put(id, d);
}

// GOOD — do the slow part outside, lock only the shared bit
public void update(String id) {
    Data d = httpClient.fetch(id);       // no lock held
    synchronized (lock) {
        cache.put(id, d);                // microseconds
    }
}

class Worker implements Runnable {
    private volatile boolean running = true;   // now the write is guaranteed to be seen

    public void stop() { running = false; }

    public void run() {
        while (running) { doWork(); }          // terminates promptly. Guaranteed.
    }
}

private volatile int count = 0;
public void increment() { count++; }   // STILL BROKEN. Still loses updates.

// Because it's read, add, write — and volatile only makes each STEP visible,
// not the three of them indivisible.

// Fixes: synchronized, or AtomicInteger:
private final AtomicInteger count = new AtomicInteger();
public void increment() { count.incrementAndGet(); }   // correct

class Publisher {
    private int data;                 // plain field — NOT volatile
    private volatile boolean ready;   // volatile flag

    void writer() {
        data = 42;              // (1)
        ready = true;           // (2) volatile WRITE
    }

    void reader() {
        if (ready) {            // (3) volatile READ
            System.out.println(data);   // (4) GUARANTEED to print 42 — never 0
        }
    }
}
// Why: (1) happens-before (2) by program order.
//      (2) happens-before (3) by the volatile rule.
//      (3) happens-before (4) by program order.
//      Transitivity => (1) happens-before (4). `data` is visible even though it's not volatile.
// This is the "volatile piggyback": the barrier flushes EVERYTHING written before it.

int x = 10;                              // written before start()
Thread t = new Thread(() -> System.out.println(x));   // sees 10, guaranteed
t.start();

// --- and the other direction ---
Thread t2 = new Thread(() -> result = compute());
t2.start();
t2.join();                 // everything t2 did happens-before here
System.out.println(result);   // guaranteed to see it

class Safe {
    private final int x;
    Safe(int x) { this.x = x; }
}
// The JMM guarantees: any thread that sees a Safe reference sees a fully-constructed
// object with x already set. No synchronisation needed. This is why immutable objects
// are automatically thread-safe.

class Unsafe {
    private int x;             // NOT final
    Unsafe(int x) { this.x = x; }
}
// Another thread can see a non-null Unsafe reference but still read x == 0,
// because the constructor's write can be reordered with the reference publication.

AtomicInteger count = new AtomicInteger(0);

count.incrementAndGet();         // ++count  -> returns the NEW value
count.getAndIncrement();         // count++  -> returns the OLD value
count.addAndGet(5);
count.get();
count.set(10);
count.compareAndSet(10, 20);     // if it's 10, make it 20. Returns whether it worked.
count.updateAndGet(x -> x * 2);  // arbitrary function, applied atomically
count.accumulateAndGet(5, Integer::sum);

// CAS(memoryLocation, expectedValue, newValue):
//   atomically, in ONE uninterruptible CPU instruction:
//   "if the value here is still `expected`, replace it with `new` and report success;
//    otherwise change nothing and report failure."

// incrementAndGet() is essentially:
int current;
do {
    current = get();                              // read
} while (!compareAndSet(current, current + 1));   // try to swap; if someone beat us, LOOP and retry
return current + 1;

AtomicInteger / AtomicLong / AtomicBoolean
AtomicReference<T>                     // CAS on an object reference
AtomicIntegerArray / AtomicLongArray    // per-element atomicity
LongAdder / LongAccumulator             // high-contention counters — much faster
AtomicStampedReference<T>              // reference + version stamp -> defeats the ABA problem

// AtomicReference: swap an immutable object atomically
AtomicReference<Config> cfg = new AtomicReference<>(initial);
cfg.updateAndGet(c -> c.withTimeout(30));

private final ReentrantLock lock = new ReentrantLock();

public void work() {
    lock.lock();
    try {
        // critical section
    } finally {
        lock.unlock();     // MUST be in finally — an exception would leak the lock forever
    }
}

// 1. Try, and give up immediately rather than blocking
if (lock.tryLock()) {
    try { work(); } finally { lock.unlock(); }
} else {
    doSomethingElse();          // no waiting around
}

// 2. Try with a timeout — the single best deadlock defence there is
if (lock.tryLock(500, TimeUnit.MILLISECONDS)) {
    try { work(); } finally { lock.unlock(); }
} else {
    log.warn("could not acquire lock in 500ms — backing off");
}

// 3. Interruptible acquisition (synchronized blocks are NOT interruptible)
lock.lockInterruptibly();

// 4. Fairness — longest waiter goes first (slower, but no starvation)
ReentrantLock fair = new ReentrantLock(true);

private final ReadWriteLock rw = new ReentrantReadWriteLock();
private final Map<String,String> cache = new HashMap<>();

public String get(String k) {
    rw.readLock().lock();          // MANY threads can hold this at once
    try { return cache.get(k); }
    finally { rw.readLock().unlock(); }
}

public void put(String k, String v) {
    rw.writeLock().lock();         // EXCLUSIVE — blocks all readers and writers
    try { cache.put(k, v); }
    finally { rw.writeLock().unlock(); }
}

private final ReentrantLock lock = new ReentrantLock();
private final Condition notFull  = lock.newCondition();   // separate queues — this is the win
private final Condition notEmpty = lock.newCondition();
private final Queue<T> q = new ArrayDeque<>();
private final int cap = 10;

public void put(T item) throws InterruptedException {
    lock.lock();
    try {
        while (q.size() == cap) notFull.await();   // ALWAYS in a while, never an if
        q.add(item);
        notEmpty.signal();                          // wake only a consumer
    } finally { lock.unlock(); }
}

public T take() throws InterruptedException {
    lock.lock();
    try {
        while (q.isEmpty()) notEmpty.await();
        T item = q.poll();
        notFull.signal();                           // wake only a producer
        return item;
    } finally { lock.unlock(); }
}

synchronized (lock) {
    while (!condition) {
        lock.wait();          // releases the monitor and waits. MUST hold it to call this.
    }
    // ... use the resource
    lock.notifyAll();         // prefer notifyAll: notify() wakes ONE arbitrary thread,
}                             // which may be the wrong one -> lost signal -> hang.

// CountDownLatch — wait for N things to finish. ONE SHOT, cannot be reset. (Go: WaitGroup)
CountDownLatch latch = new CountDownLatch(3);
for (int i = 0; i < 3; i++) {
    executor.submit(() -> { try { work(); } finally { latch.countDown(); } });
}
latch.await();                     // blocks until the count hits 0

// CyclicBarrier — N threads wait for EACH OTHER, then all proceed. Reusable.
CyclicBarrier barrier = new CyclicBarrier(3, () -> System.out.println("all arrived"));
barrier.await();                   // each thread blocks here until the 3rd arrives

// Semaphore — limit concurrent access to N permits
Semaphore sem = new Semaphore(5);  // at most 5 at a time
sem.acquire();
try { useResource(); } finally { sem.release(); }   // release in finally!

// Phaser — like a reusable barrier with a dynamic party count (rarely needed)

ExecutorService pool = Executors.newFixedThreadPool(4);

pool.execute(() -> System.out.println("fire and forget"));   // Runnable, returns nothing
Future<String> f = pool.submit(() -> "I return a value");    // Callable, returns a Future

pool.shutdown();                                    // no new tasks; finish what's queued
if (!pool.awaitTermination(30, TimeUnit.SECONDS)) { // wait for them
    pool.shutdownNow();                             // interrupt the stragglers
}

ThreadPoolExecutor pool = new ThreadPoolExecutor(
    4,                                    // corePoolSize — kept alive even when idle
    8,                                    // maximumPoolSize — only grown when the QUEUE IS FULL
    60, TimeUnit.SECONDS,                 // keepAliveTime — how long extra (non-core) threads linger
    new ArrayBlockingQueue<>(100),        // BOUNDED work queue — this is the important bit
    new ThreadFactoryBuilder().setNameFormat("worker-%d").build(),   // named threads = readable dumps
    new ThreadPoolExecutor.CallerRunsPolicy()   // what to do when full (see below)
);

new ThreadPoolExecutor.AbortPolicy()          // default: throw RejectedExecutionException
new ThreadPoolExecutor.CallerRunsPolicy()     // the SUBMITTING thread runs it -> natural backpressure
new ThreadPoolExecutor.DiscardPolicy()        // silently drop it (dangerous)
new ThreadPoolExecutor.DiscardOldestPolicy()  // drop the oldest queued task, then retry

int cores = Runtime.getRuntime().availableProcessors();

// CPU-bound work: more threads than cores just adds context switching
int cpuBound = cores;         // (or cores + 1 to cover the odd page fault)

// I/O-bound work: threads are mostly parked waiting, so you want many more
int ioBound = cores * (1 + waitTime / computeTime);
// e.g. 8 cores, 100ms waiting per 5ms computing  ->  8 * (1 + 20) = 168 threads

// This formula is exactly why virtual threads exist — see section 12.

Runnable r = () -> System.out.println("hi");         // void, cannot throw checked exceptions
Callable<String> c = () -> { return "result"; };     // returns a value, CAN throw checked

Future<String> f = pool.submit(c);
f.get();                        // BLOCKS until done. Throws ExecutionException wrapping any failure.
f.get(1, TimeUnit.SECONDS);     // ...or gives up. TimeoutException.
f.isDone();
f.cancel(true);                 // true = interrupt it if it's already running

// async + returns a value
CompletableFuture<String> f = CompletableFuture.supplyAsync(() -> fetchUser());

// async + returns nothing
CompletableFuture<Void> g = CompletableFuture.runAsync(() -> log());

// already-finished
CompletableFuture<String> done = CompletableFuture.completedFuture("value");

// with your own pool — ALWAYS do this in production (the default is the common FJ pool)
CompletableFuture.supplyAsync(() -> fetchUser(), myExecutor);

CompletableFuture.supplyAsync(() -> fetchUserId())
    .thenApply(id -> loadUser(id))          // map:     T -> U        (sync-ish, same thread)
    .thenCompose(user -> loadOrdersAsync(user))  // flatMap: T -> CompletableFuture<U>
    .thenAccept(orders -> render(orders))   // consume: T -> void
    .thenRun(() -> log.info("done"));       // ignore the value entirely

// WRONG — a future inside a future
CompletableFuture<CompletableFuture<User>> bad =
    CompletableFuture.supplyAsync(() -> id).thenApply(id -> loadUserAsync(id));

// RIGHT — flattened
CompletableFuture<User> good =
    CompletableFuture.supplyAsync(() -> id).thenCompose(id -> loadUserAsync(id));

CompletableFuture<String> user  = CompletableFuture.supplyAsync(() -> fetchUser());
CompletableFuture<String> prefs = CompletableFuture.supplyAsync(() -> fetchPrefs());

// both run CONCURRENTLY; combine when both finish
CompletableFuture<String> page = user.thenCombine(prefs, (u, p) -> render(u, p));

// wait for many
CompletableFuture.allOf(f1, f2, f3).join();     // Void — collect results from each yourself
CompletableFuture.anyOf(f1, f2, f3).join();     // the FIRST one to finish wins

// A useful idiom: allOf + collect
List<CompletableFuture<String>> futures = ids.stream()
    .map(id -> CompletableFuture.supplyAsync(() -> load(id), pool))
    .toList();
List<String> results = CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new))
    .thenApply(v -> futures.stream().map(CompletableFuture::join).toList())
    .join();

cf.exceptionally(ex -> "fallback")            // only on failure -> supply a default
  .handle((result, ex) -> ex != null ? "fallback" : result)   // ALWAYS runs; sees both
  .whenComplete((result, ex) -> log(result, ex));             // ALWAYS runs; changes nothing

// Timeouts (Java 9+)
cf.orTimeout(2, TimeUnit.SECONDS);                       // fail with TimeoutException
cf.completeOnTimeout("default", 2, TimeUnit.SECONDS);    // ...or quietly substitute a value

ConcurrentHashMap<String,Integer> map = new ConcurrentHashMap<>();

// BROKEN — two atomic calls are not one atomic operation
if (!map.containsKey(k)) map.put(k, 1);       // another thread can slip in between

// CORRECT — single atomic operations
map.putIfAbsent(k, 1);
map.computeIfAbsent(k, key -> expensiveLoad(key));   // computed at most once per key
map.compute(k, (key, v) -> v == null ? 1 : v + 1);
map.merge(k, 1, Integer::sum);                        // the cleanest counter you'll write
map.getOrDefault(k, 0);

BlockingQueue<Task> queue = new ArrayBlockingQueue<>(100);   // BOUNDED = backpressure

// Producer — blocks when full, which throttles it naturally
queue.put(task);

// Consumer — blocks when empty, no busy-waiting
Task t = queue.take();

// The full method set — four behaviours for each operation:
//            Throws           Returns special   Blocks     Times out
// insert     add(e)           offer(e)          put(e)     offer(e, t, unit)
// remove     remove()         poll()            take()     poll(t, unit)
// examine    element()        peek()            —          —

// SynchronousQueue — capacity ZERO: a direct handoff, each put waits for a take.
// This is the closest thing Java has to an unbuffered Go channel.

final Object lockA = new Object();
final Object lockB = new Object();

Thread t1 = new Thread(() -> {
    synchronized (lockA) {              // gets A
        Thread.sleep(50);
        synchronized (lockB) { }        // wants B — held by t2. Waits forever.
    }
});

Thread t2 = new Thread(() -> {
    synchronized (lockB) {              // gets B
        Thread.sleep(50);
        synchronized (lockA) { }        // wants A — held by t1. Waits forever.
    }
});
// Both threads BLOCKED. No exception, no log, no CPU usage. The app just hangs.

// Rule: EVERY thread acquires locks in the same defined order. No cycle can form.
void transfer(Account from, Account to, int amount) {
    Account first  = from.id < to.id ? from : to;    // order by a stable, unique key
    Account second = from.id < to.id ? to : from;

    synchronized (first) {
        synchronized (second) {
            from.debit(amount);
            to.credit(amount);
        }
    }
}
// Now transfer(A,B) and transfer(B,A) both lock A then B. Circular wait is impossible.

boolean transfer(Account from, Account to, int amount) throws InterruptedException {
    if (from.lock.tryLock(1, TimeUnit.SECONDS)) {
        try {
            if (to.lock.tryLock(1, TimeUnit.SECONDS)) {
                try {
                    from.debit(amount);
                    to.credit(amount);
                    return true;
                } finally { to.lock.unlock(); }
            }
        } finally { from.lock.unlock(); }   // couldn't get the second -> RELEASE the first and retry
    }
    return false;
}

jps                    # find the pid
jstack <pid>           # dump every thread's stack

# jstack DETECTS deadlocks for you and prints:
#
# Found one Java-level deadlock:
# =============================
# "Thread-1":
#   waiting to lock monitor 0x00007f... (object 0x000000076ab, a java.lang.Object),
#   which is held by "Thread-0"
# "Thread-0":
#   waiting to lock monitor 0x00007f... (object 0x000000076ac, a java.lang.Object),
#   which is held by "Thread-1"

# This is why naming your threads matters — "pool-1-thread-7" tells you nothing.

// One-off
Thread.startVirtualThread(() -> System.out.println("hi"));

Thread t = Thread.ofVirtual().name("worker").start(runnable);
t.join();

// The real way — an executor that makes a NEW virtual thread per task
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 1_000_000; i++) {
        executor.submit(() -> {
            Thread.sleep(1000);      // blocks the VIRTUAL thread — the carrier is freed!
            return fetchSomething();
        });
    }
}   // close() waits for all of them

// A million concurrent tasks. With platform threads this would OOM instantly.

// Virtual threads run on a small pool of PLATFORM threads called "carriers"
// (a ForkJoinPool sized to your core count).
//
//   1. Virtual thread MOUNTS onto a carrier and runs.
//   2. It hits a blocking call (I/O, sleep, lock).
//   3. The JVM UNMOUNTS it: its stack is copied to the heap, the carrier is released.
//   4. The carrier immediately runs another virtual thread.
//   5. When the I/O completes, the virtual thread is remounted (on any carrier) and continues.
//
// Blocking a virtual thread costs a heap copy, not an OS context switch.