How to Use ConcurrentHashMap in Java: A Stock Service

I wrote a counter on a ConcurrentHashMap, ran it from four threads at 250,000 increments each, and got this:

CHM getOrDefault + put             total=691,927 (should be 1,000,000)

Nearly a third of the updates vanished, on a class whose name says concurrent. Nothing threw. Nothing logged. The map was perfectly healthy; my code was the problem. That gap is what this tutorial is about: how to use ConcurrentHashMap in Java so that your code is correct, not only the map.

You'll build a small stock service for a web shop: deliveries add stock, checkout threads reserve it, and no unit is ever sold twice. It's about 60 lines of service code, a handful of demos that show each mistake failing on purpose, and 17 checks that pass. If you've used HashMap and know what a thread is, you have everything you need. The map's internals (bins, CAS, resizing) live in the ConcurrentHashMap vs synchronizedMap deep dive; here we only build.

Here's the finished service under load, six checkout threads, 120 orders against 70 units of stock:

orders accepted: 60, rejected: 60
stock left:      {CAP-RED=0, MUG-BLUE=10, TEE-L=0}
CAP-RED orders:  5 (stock was 5)
MUG-BLUE lookups: 40

Sixty accepted, sixty rejected, CAP-RED sold exactly the five it had. That's what "correct" looks like.

What's installed and what I ran it on

There are no dependencies, so Maven or Gradle only get in the way. Any JDK from 21 up compiles this as written, because Thread.ofPlatform() in Main arrived in Java 21. On older JDKs, swap it for new Thread(...) and everything else works unchanged.

Two honest limits. I couldn't reach Maven Central from my build environment, so the tests are plain Java with a main method rather than JUnit; the logic carries straight over to JUnit 5 and I'll point at it in the going-further section. And I didn't open IntelliJ IDEA or Eclipse for this one, so the IDE steps below come from the vendors' documentation, not from a run. I've said which is which.

Create the inventory project

I'm using the command line as the primary path this time, because there's nothing to configure.

mkdir -p inventory/src/main/java/com/example/inventory
cd inventory

The project tree when you're finished:

inventory/
└── src/main/java/com/example/inventory/
    ├── InventoryService.java
    ├── Main.java
    ├── Races.java
    ├── Traps.java
    └── Checks.java

Compile everything into an out folder with warnings switched on:

javac -Xlint:all -d out $(find src -name '*.java')

Silence means success. Run any class with java -cp out com.example.inventory.Main.

In IntelliJ IDEA

Verified from the docs, not executed. Choose File → New → Project…, pick Java on the left, set the build system to IntelliJ, and choose a JDK 21 (the dropdown can download one). Name it inventory, create the package com.example.inventory under src, and paste each file in. To run a class, click the green arrow beside its main method.

In Eclipse

Verified from the docs, not executed. Choose File → New → Java Project, name it inventory, and on the JRE page select a Java 21 runtime. Right-click src and make a package com.example.inventory. Run with Run As → Java Application.

With Maven or Gradle

Nothing here needs a dependency, so the build file is only a compiler setting: Java release 21 and the source folder src/main/java, which both tools use by default. I didn't run this under either tool.

Podman and Docker

Not needed. No database, no broker, no container.

Write the service one map operation at a time

Step 1: The three maps and the merge call

Goal: a service that takes deliveries from many threads without losing a unit.

src/main/java/com/example/inventory/InventoryService.java is the one file you'll keep. I'll show it whole here, then walk through the pieces:

package com.example.inventory;

import java.util.List;
import java.util.Map;
import java.util.Queue;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.atomic.LongAdder;

/** Stock levels, per-SKU order logs and lookup counters, all safe to call from many threads. */
public final class InventoryService {

    private final ConcurrentHashMap<String, Integer> stock = new ConcurrentHashMap<>();
    private final ConcurrentHashMap<String, Queue<String>> orders = new ConcurrentHashMap<>();
    private final ConcurrentHashMap<String, LongAdder> lookups = new ConcurrentHashMap<>();

    /** Adds stock. merge() is one atomic step: insert if absent, add if present. */
    public void receive(String sku, int qty) {
        if (qty <= 0) throw new IllegalArgumentException("qty must be positive: " + qty);
        stock.merge(sku, qty, Integer::sum);
    }

    /** Takes qty units if (and only if) enough are there. Returns true when the order got its stock. */
    public boolean reserve(String sku, String orderId, int qty) {
        boolean[] reserved = new boolean[1];          // the lambda runs once, inside the map's lock
        stock.computeIfPresent(sku, (key, have) -> {
            if (have < qty) return have;              // not enough: leave the value alone
            reserved[0] = true;
            return have - qty;
        });
        if (reserved[0]) {
            orders.computeIfAbsent(sku, key -> new ConcurrentLinkedQueue<>()).add(orderId);
        }
        return reserved[0];
    }

    public int available(String sku) {
        lookups.computeIfAbsent(sku, key -> new LongAdder()).increment();
        return stock.getOrDefault(sku, 0);
    }

    public long lookupCount(String sku) {
        LongAdder adder = lookups.get(sku);
        return adder == null ? 0 : adder.sum();
    }

    public List<String> ordersFor(String sku) {
        Queue<String> q = orders.get(sku);
        return q == null ? List.of() : List.copyOf(q);
    }

    /** A point-in-time copy for reports. The live map can keep changing underneath. */
    public Map<String, Integer> snapshot() {
        return Map.copyOf(stock);
    }

    /** Removes a SKU only if nothing is left of it. remove(key, value) is atomic too. */
    public boolean discontinue(String sku) {
        return stock.remove(sku, 0);
    }
}

Start with receive. stock.merge(sku, qty, Integer::sum) means: if the SKU has no entry, store qty; if it does, replace the value with Integer.sum(old, qty). All of that happens as one step that other threads can't slip into. The if (!containsKey) put else put version you'd write by hand can't promise that.

Checkpoint: compile with the command above. No output means it compiled cleanly with -Xlint:all.

Step 2: Reserve stock with computeIfPresent

Goal: decide and decrement in one atomic step, so two checkouts can't both take the last mug.

Look at reserve. The lambda gets the current value for the key and returns the new one. It runs while the map holds the key's slot, so no other thread can change that key between "do we have enough?" and "take it". Returning the old value unchanged is how you say "no change". Returning null is a different instruction: it deletes the entry. I checked that on purpose:

m.put("MUG", 3);
m.computeIfPresent("MUG", (k, v) -> v >= 5 ? v - 5 : null);
System.out.println("after: " + m);

after: {}

A reservation that comes up short must return have;, not return null;. Otherwise one oversized order wipes the SKU.

The boolean[] reserved is there because a lambda can't assign to a local variable, and computeIfPresent hands back the new value, not "did I change it". A one-element array is the plainest way to carry the answer out. The lambda runs once per call, so the flag is reliable.

Checkpoint: nothing to run yet. Step 5 exercises this method with eight racing threads.

Step 3: Create-on-first-use with computeIfAbsent

Goal: an order log per SKU, created the first time it's needed, even when ten threads need it at the same moment.

orders.computeIfAbsent(sku, key -> new ConcurrentLinkedQueue<>()) returns the existing queue, or builds and stores one. Every caller gets the same queue back, which is the whole point. The containsKey-then-put version can hand two threads two different queues, and one of them is quietly thrown away along with whatever got added to it.

The same call powers the lookup counter in available: one LongAdder per SKU, created on demand, incremented without a lock. The atomic classes tutorial covers why LongAdder beats AtomicLong when many threads hit one counter.

Step 4: Read side: snapshots and conditional removal

Goal: reports that don't fall over while checkouts keep running, and a delete that can't remove a SKU someone just restocked.

snapshot() returns Map.copyOf(stock), a frozen copy. discontinue uses the two-argument remove(key, value), which deletes only if the current value is still 0. If a delivery lands between your check and your delete, the call returns false and the stock survives.

Step 5: A driver to see it work

Goal: run the service under real contention.

src/main/java/com/example/inventory/Main.java:

package com.example.inventory;

import java.util.ArrayList;
import java.util.List;
import java.util.TreeMap;
import java.util.concurrent.atomic.AtomicInteger;

public class Main {
    public static void main(String[] args) throws Exception {
        InventoryService inv = new InventoryService();
        inv.receive("MUG-BLUE", 40);
        inv.receive("MUG-BLUE", 10);          // second delivery, merged into the same key
        inv.receive("TEE-L", 15);
        inv.receive("CAP-RED", 5);

        AtomicInteger accepted = new AtomicInteger();
        AtomicInteger rejected = new AtomicInteger();
        List<Thread> threads = new ArrayList<>();
        for (int t = 0; t < 6; t++) {
            int id = t;
            threads.add(Thread.ofPlatform().name("checkout-" + t).start(() -> {
                String[] skus = {"MUG-BLUE", "TEE-L", "CAP-RED"};
                for (int i = 0; i < 20; i++) {
                    String sku = skus[(id + i) % skus.length];
                    inv.available(sku);
                    boolean ok = inv.reserve(sku, "o-" + id + "-" + i, 1);
                    (ok ? accepted : rejected).incrementAndGet();
                }
            }));
        }
        for (Thread t : threads) t.join();

        System.out.println("orders accepted: " + accepted + ", rejected: " + rejected);
        System.out.println("stock left:      " + new TreeMap<>(inv.snapshot()));
        System.out.println("CAP-RED orders:  " + inv.ordersFor("CAP-RED").size() + " (stock was 5)");
        System.out.println("MUG-BLUE lookups: " + inv.lookupCount("MUG-BLUE"));
    }
}

Checkpoint: java -cp out com.example.inventory.Main prints the block you saw at the top. Your numbers should match mine exactly, and the reason is arithmetic: each SKU gets 40 attempts however the threads interleave. MUG-BLUE (50 in stock) accepts all 40 and keeps 10, TEE-L accepts its 15, CAP-RED its 5. That's 60 accepted and 60 rejected every time. If CAP-RED orders ever prints anything but 5, the reservation isn't atomic.

Watch eight threads fight over one mug

This is the part I'd run before trusting anything above. Races.java pits four ways of reserving one unit against each other: 8 threads, 1,000 attempts each, 5,000 units in stock.

src/main/java/com/example/inventory/Races.java:

package com.example.inventory;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.LongAdder;
import java.util.function.BiFunction;

/** Four ways to "reserve one unit", and three ways to count. Only some of them are right. */
public class Races {
    static final int STOCK = 5_000, THREADS = 8, ATTEMPTS = 1_000;   // demand 8,000 > stock 5,000

    interface Reserver { boolean reserve(String sku); int left(String sku); }

    static Reserver checkThenAct(Map<String, Integer> map) {
        return new Reserver() {
            public boolean reserve(String sku) {
                Integer have = map.get(sku);                 // read
                if (have != null && have >= 1) {             // decide
                    map.put(sku, have - 1);                  // write: someone else may have written in between
                    return true;
                }
                return false;
            }
            public int left(String sku) { return map.get(sku); }
        };
    }

    static Reserver computeBased(ConcurrentHashMap<String, Integer> map) {
        return new Reserver() {
            public boolean reserve(String sku) {
                boolean[] ok = new boolean[1];
                map.computeIfPresent(sku, (k, have) -> { if (have < 1) return have; ok[0] = true; return have - 1; });
                return ok[0];
            }
            public int left(String sku) { return map.get(sku); }
        };
    }

    static void run(String label, Reserver r) throws Exception {
        AtomicInteger sold = new AtomicInteger();
        Thread[] ts = new Thread[THREADS];
        try {
            for (int t = 0; t < THREADS; t++) {
                ts[t] = new Thread(() -> {
                    for (int i = 0; i < ATTEMPTS; i++) if (r.reserve("MUG")) sold.incrementAndGet();
                });
                ts[t].start();
            }
            for (Thread t : ts) t.join();
            int left = r.left("MUG");
            System.out.printf("%-28s sold=%5d left=%5d sold+left=%5d (should be %d)%n",
                    label, sold.get(), left, sold.get() + left, STOCK);
        } catch (Exception e) {
            System.out.printf("%-28s threw %s%n", label, e);
        }
    }

    static long count(String label, int variant) throws Exception {
        int threads = 4, perThread = 250_000;
        String[] keys = {"mug", "tee", "cap"};
        Map<String, Integer> plain = new ConcurrentHashMap<>();
        ConcurrentHashMap<String, Integer> merged = new ConcurrentHashMap<>();
        ConcurrentHashMap<String, LongAdder> adders = new ConcurrentHashMap<>();
        Thread[] ts = new Thread[threads];
        for (int t = 0; t < threads; t++) {
            ts[t] = new Thread(() -> {
                for (int i = 0; i < perThread; i++) {
                    String k = keys[i % 3];
                    switch (variant) {
                        case 0 -> plain.put(k, plain.getOrDefault(k, 0) + 1);        // two calls, not one
                        case 1 -> merged.merge(k, 1, Integer::sum);                  // one atomic call
                        default -> adders.computeIfAbsent(k, x -> new LongAdder()).increment();
                    }
                }
            });
            ts[t].start();
        }
        for (Thread t : ts) t.join();
        long total = switch (variant) {
            case 0 -> plain.values().stream().mapToLong(Integer::longValue).sum();
            case 1 -> merged.values().stream().mapToLong(Integer::longValue).sum();
            default -> adders.values().stream().mapToLong(LongAdder::sum).sum();
        };
        System.out.printf("%-34s total=%,d (should be %,d)%n", label, total, (long) threads * perThread);
        return total;
    }

    public static void main(String[] args) throws Exception {
        System.out.println("-- reserving one unit at a time, 8 threads x 1,000 attempts, stock 5,000 --");
        run("HashMap, get-then-put", checkThenAct(new HashMap<>(Map.of("MUG", STOCK))));
        run("synchronizedMap, get-then-put", checkThenAct(Collections.synchronizedMap(new HashMap<>(Map.of("MUG", STOCK)))));
        run("ConcurrentHashMap, get-then-put", checkThenAct(new ConcurrentHashMap<>(Map.of("MUG", STOCK))));
        run("ConcurrentHashMap, compute", computeBased(new ConcurrentHashMap<>(Map.of("MUG", STOCK))));
        System.out.println("-- counting, 4 threads x 250,000 increments over 3 keys --");
        count("CHM getOrDefault + put", 0);
        count("CHM merge", 1);
        count("CHM computeIfAbsent + LongAdder", 2);
    }
}

Run it:

java -cp out com.example.inventory.Races

-- reserving one unit at a time, 8 threads x 1,000 attempts, stock 5,000 --
HashMap, get-then-put        sold= 5442 left=    0 sold+left= 5442 (should be 5000)
synchronizedMap, get-then-put sold= 6479 left=    0 sold+left= 6479 (should be 5000)
ConcurrentHashMap, get-then-put sold= 7607 left=    0 sold+left= 7607 (should be 5000)
ConcurrentHashMap, compute   sold= 5000 left=    0 sold+left= 5000 (should be 5000)
-- counting, 4 threads x 250,000 increments over 3 keys --
CHM getOrDefault + put             total=699,115 (should be 1,000,000)
CHM merge                          total=1,000,000 (should be 1,000,000)
CHM computeIfAbsent + LongAdder    total=1,000,000 (should be 1,000,000)

The number to read is sold+left. Every sale takes one unit off the shelf, so it must equal 5,000. When it doesn't, units were sold that the map never recorded.

I ran the whole thing three times. This is what sold+left came to:

Two things stand out. First, the wrapped synchronizedMap fails too. Each call locks, but the pair of calls doesn't, and I wrote about that gap in the race condition article. Second, ConcurrentHashMap with get-then-put came out right three times out of three, and I'd be lying if I said I had made it fail. The window between get and put is a few nanoseconds on a 2-core machine. That code is still wrong; it's wrong the way a missing seat belt is wrong. The counting test in the same program shows the same mistake with the window wide open, because each of the 1,000,000 increments gives it another chance:

Memorise one rule from this section: ConcurrentHashMap makes each call safe. A decision that takes two calls is yours to protect, and the way to protect it is to turn it into one call.

Seventeen checks, eight racing threads

No JUnit here (see the versions section), so Checks.java is a small harness: each check prints PASS or FAIL and the program exits with code 1 on any failure. Eight-thread checks line up behind a CountDownLatch so they start together.

src/main/java/com/example/inventory/Checks.java:

package com.example.inventory;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CountDownLatch;

/** Plain checks: no framework, exit code 1 on any failure. */
public class Checks {
    static int passed, failed;

    static void check(String name, boolean ok) {
        if (ok) passed++; else failed++;
        System.out.println((ok ? "PASS  " : "FAIL  ") + name);
    }

    static void parallel(int threads, Runnable body) throws Exception {
        CountDownLatch go = new CountDownLatch(1);
        List<Thread> ts = new ArrayList<>();
        for (int i = 0; i < threads; i++) {
            Thread t = new Thread(() -> { try { go.await(); } catch (InterruptedException e) { return; } body.run(); });
            t.start(); ts.add(t);
        }
        go.countDown();
        for (Thread t : ts) t.join();
    }

    public static void main(String[] args) throws Exception {
        InventoryService inv = new InventoryService();
        inv.receive("MUG", 10);
        inv.receive("MUG", 5);
        check("receive merges deliveries", inv.available("MUG") == 15);
        check("unknown sku has 0 available", inv.available("NOPE") == 0);
        check("reserve fails for unknown sku", !inv.reserve("NOPE", "o1", 1));
        check("reserve fails when short, stock untouched", !inv.reserve("MUG", "o2", 16) && inv.available("MUG") == 15);
        check("reserve succeeds and logs the order", inv.reserve("MUG", "o3", 15) && inv.ordersFor("MUG").equals(List.of("o3")));
        check("discontinue works at zero", inv.discontinue("MUG"));
        check("discontinue refuses when stock remains", rec(inv));
        try { inv.receive("MUG", 0); check("receive rejects 0", false); }
        catch (IllegalArgumentException e) { check("receive rejects 0", true); }

        InventoryService big = new InventoryService();
        big.receive("TEE", 5_000);
        int[] sold = new int[8];
        parallel(8, () -> {
            for (int i = 0; i < 1_000; i++) if (big.reserve("TEE", "x", 1)) synchronized (sold) { sold[0]++; }
        });
        check("8 threads never oversell (sold == 5000)", sold[0] == 5_000);
        check("stock ends at exactly 0", big.available("TEE") == 0);
        check("order log has 5000 entries", big.ordersFor("TEE").size() == 5_000);

        InventoryService counted = new InventoryService();
        parallel(8, () -> { for (int i = 0; i < 50_000; i++) counted.available("CAP"); });
        check("lookup counter is exact (400000)", counted.lookupCount("CAP") == 400_000);

        InventoryService deliveries = new InventoryService();
        parallel(8, () -> { for (int i = 0; i < 10_000; i++) deliveries.receive("BOX", 1); });
        check("concurrent receive loses nothing (80000)", deliveries.available("BOX") == 80_000);

        Map<String, Integer> snap = deliveries.snapshot();
        deliveries.receive("BOX", 1);
        check("snapshot is a frozen copy", snap.get("BOX") == 80_000);
        try { snap.put("X", 1); check("snapshot is read-only", false); }
        catch (UnsupportedOperationException e) { check("snapshot is read-only", true); }

        ConcurrentHashMap<String, Integer> m = new ConcurrentHashMap<>(Map.of("a", 1, "b", 2));
        boolean noCme = true;
        try { for (String k : m.keySet()) m.put(k + "!", 0); } catch (RuntimeException e) { noCme = false; }
        check("iterating while writing never throws CME", noCme);

        Set<String> seen = ConcurrentHashMap.newKeySet();
        int[] firsts = new int[1];
        parallel(8, () -> { for (int i = 0; i < 1000; i++) if (seen.add("k" + i)) synchronized (firsts) { firsts[0]++; } });
        check("newKeySet: add() returns true once per key (1000)", firsts[0] == 1000 && seen.size() == 1000);

        System.out.println(passed + " passed, " + failed + " failed");
        if (failed > 0) System.exit(1);
    }

    static boolean rec(InventoryService inv) {
        inv.receive("TEE", 2);
        return !inv.discontinue("TEE");
    }
}

java -cp out com.example.inventory.Checks

PASS  receive merges deliveries
PASS  unknown sku has 0 available
PASS  reserve fails for unknown sku
PASS  reserve fails when short, stock untouched
PASS  reserve succeeds and logs the order
PASS  discontinue works at zero
PASS  discontinue refuses when stock remains
PASS  receive rejects 0
PASS  8 threads never oversell (sold == 5000)
PASS  stock ends at exactly 0
PASS  order log has 5000 entries
PASS  lookup counter is exact (400000)
PASS  concurrent receive loses nothing (80000)
PASS  snapshot is a frozen copy
PASS  snapshot is read-only
PASS  iterating while writing never throws CME
PASS  newKeySet: add() returns true once per key (1000)
17 passed, 0 failed

In JUnit 5 each check(...) line becomes an @Test with an AssertJ or assertEquals assertion. The thread-heavy ones are worth repeating in a loop, say 50 times, because a race that fails one run in twenty will pass your single run. I didn't loop these; I ran the file twice and it passed both times.

What the map does that a lock around a HashMap doesn't

A plain HashMap has no protection at all. Collections.synchronizedMap wraps every method in one lock, so threads queue up and each call is safe. ConcurrentHashMap lets reads run without waiting and locks only the part of the table a write touches, which is why eight checkout threads on different SKUs don't block each other. The deep dive covers that machinery; you don't need it to use the class well.

What you do need is the contract. The single-key methods putIfAbsent, compute, computeIfAbsent, computeIfPresent, merge, remove(key, value) and replace(key, old, new) each run as one step for their key. That's the toolbox for check-then-act logic. If you find yourself writing get, an if, then put, reach for one of them.

Four rules fall out of that, and Traps.java demonstrates each:

src/main/java/com/example/inventory/Traps.java:

package com.example.inventory;

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/** Small, single-threaded demos of the rules that surprise people. */
public class Traps {
    static final ConcurrentHashMap<Integer, Long> memo = new ConcurrentHashMap<>();

    static long fib(int n) {
        if (n < 2) return n;
        return memo.computeIfAbsent(n, k -> fib(k - 1) + fib(k - 2));   // updates the map from inside the lambda
    }

    public static void main(String[] args) {
        ConcurrentHashMap<String, Integer> chm = new ConcurrentHashMap<>();
        try { chm.put("MUG", null); } catch (NullPointerException e) { System.out.println("null value -> NPE"); }
        try { chm.get(null); } catch (NullPointerException e) { System.out.println("null key   -> NPE"); }
        System.out.println("getOrDefault on missing: " + chm.getOrDefault("MUG", 0));

        Map<String, Integer> hm = new HashMap<>(Map.of("A", 1, "B", 2, "C", 3));
        try {
            for (String k : hm.keySet()) if (k.equals("A")) hm.remove("B");
            System.out.println("HashMap loop finished (removal of a later key can slip through): " + hm);
        } catch (Exception e) { System.out.println("HashMap -> " + e.getClass().getSimpleName()); }
        Map<String, Integer> hm2 = new HashMap<>(Map.of("A", 1, "B", 2, "C", 3));
        try {
            for (String k : hm2.keySet()) hm2.put(k + "x", 9);
        } catch (Exception e) { System.out.println("HashMap add during loop -> " + e.getClass().getSimpleName()); }

        ConcurrentHashMap<String, Integer> c2 = new ConcurrentHashMap<>(Map.of("A", 1, "B", 2, "C", 3));
        int seen = 0;
        for (String k : c2.keySet()) { c2.put(k + "x", 9); seen++; }
        System.out.println("CHM add during loop -> no exception, loop saw " + seen + " keys, map now has " + c2.size());

        try {
            System.out.println(fib(30));
        } catch (Exception e) {
            System.out.println("recursive computeIfAbsent -> " + e.getClass().getSimpleName() + ": " + e.getMessage());
        }
        System.out.println("fib(30) with a plain get/put memo: " + fibSafe(30, new ConcurrentHashMap<>()));
        System.out.println("size=" + c2.size() + " mappingCount=" + c2.mappingCount());
    }

    static long fibSafe(int n, ConcurrentHashMap<Integer, Long> m) {
        if (n < 2) return n;
        Long hit = m.get(n);
        if (hit != null) return hit;
        long v = fibSafe(n - 1, m) + fibSafe(n - 2, m);   // compute outside the map, then store
        m.putIfAbsent(n, v);
        return v;
    }
}

null value -> NPE
null key   -> NPE
getOrDefault on missing: 0
HashMap -> ConcurrentModificationException
HashMap add during loop -> ConcurrentModificationException
CHM add during loop -> no exception, loop saw 5 keys, map now has 8
recursive computeIfAbsent -> IllegalStateException: Recursive update
fib(30) with a plain get/put memo: 832040
size=8 mappingCount=8

No nulls. put("MUG", null) and get(null) both throw NullPointerException. That's deliberate: in a map shared between threads, a null from get has to mean "absent", with no second meaning. Use getOrDefault or Optional where you'd have stored a null.

Iteration is forgiving. The HashMap loops threw ConcurrentModificationException (my CME article has the causes). The ConcurrentHashMap loop kept going while I added keys: it saw 5 of the eventual 8. The iterator reflects the map at some point at or since its creation, and never throws CME. Don't count on seeing the new keys, and don't share one iterator between threads.

Don't touch the map from inside its own lambda. fib calls computeIfAbsent recursively and the JDK 21 map answers with IllegalStateException: Recursive update. Compute the value first, then store it with putIfAbsent, as fibSafe does. I only ran this on Java 21. I've read that older JDKs could spin forever in cases like this, but I haven't tested one.

Counts are estimates while writers are active. size() and mappingCount() agree here because the map is quiet. Under load, the Javadoc's class description says the aggregate methods are for monitoring and estimation, not for program control. So never write if (map.size() < LIMIT) map.put(...) and expect the limit to hold. mappingCount() returns a long, which matters past two billion entries.

What went wrong on my machine

incompatible types: int cannot be converted to String. I declared ConcurrentHashMap<String, String> and called merge("MUG", 1, Integer::sum). The compiler is right: merge takes the map's value type. Fix the declaration to <String, Integer>.

forced/a/Bad.java:5: error: incompatible types: int cannot be converted to String
        m.merge("MUG", 1, Integer::sum);
                       ^

A SKU disappeared after one big order. My first reserve returned null from the lambda when stock ran short. That removes the mapping. The fix is return have; (shown in Step 2, with the output).

The race I couldn't reproduce. ConcurrentHashMap get-then-put passed three runs. I stopped trying to force it and moved on, because the counting demo proves the point with far less luck required.

HashMap results that look fine. Run 1 of the HashMap row gave sold+left=5000. A race that happens to pass once isn't a pass. Don't use a single green run as evidence of thread safety.

If you hit ConcurrentModificationException in code you thought was safe, it's nearly always a plain HashMap or ArrayList somewhere in the path. The CME article above walks through finding it.

Before this goes near production

The build took seconds to compile and run; the time went on trying to make the get-then-put version fail on a two-core machine. Run your own races on the hardware you deploy on, because more cores widen every window.

• Keep lambdas short. compute and its relatives hold part of the map while your function runs, so a slow function can stall other writers. I didn't measure the stall. The method details section of the JDK 21 Javadoc has the official guidance; read the compute entry. Do the slow work (a database call, an HTTP request) before or after, not inside.
• Size it up front when you know the volume: new ConcurrentHashMap<>(10_000) avoids early resizing.
• Use ConcurrentHashMap.newKeySet() when you only need a thread-safe set. The check proves add() returns true exactly once per key across eight threads.
• Multi-key rules are still yours. Moving stock from one SKU to another touches two keys, and no single map call covers that. You'll need a lock, or a different design. See ReentrantLock vs synchronized.
• A map is the wrong tool when a queue is the real shape. Work handed from one thread to another belongs in a BlockingQueue.
• Version note. The compute family arrived in Java 8 with the rewritten map. Everything in this article runs on 21; only Thread.ofPlatform() needs a swap on older JDKs. I didn't run it on anything earlier than 21.

Next in this series: thread pools with ExecutorService for running the checkout threads properly, and unit tests with JUnit 5 to move the checks into your build.

Checklist

• Every check-then-act on a shared map becomes one call: merge, compute, computeIfAbsent, computeIfPresent, putIfAbsent, or remove(key, value).
• Return the old value from a compute lambda to leave an entry alone; returning null deletes it.
• No nulls in, no map updates from inside the lambda, and treat size() as an estimate.
• One green run proves nothing about threads. Repeat, and put a counter test next to every race you fear.

ConcurrentHashMap questions people search

Is ConcurrentHashMap thread-safe for get-then-put? Each call is thread-safe; the pair isn't. In my counting test, getOrDefault plus put produced 691,927 instead of 1,000,000. Use merge or compute so the read and write are one operation.

What's the difference between ConcurrentHashMap and synchronizedMap? synchronizedMap locks the whole map for every call, so access is serialized. ConcurrentHashMap allows concurrent reads and finer-grained writes, and adds the atomic compute family. Both still need you to avoid two-step logic. The comparison article goes into the design.

Why does ConcurrentHashMap not allow null keys or values? So that a null from get can only mean "no mapping". With nulls allowed you couldn't tell "absent" from "present with null" without a second call, and that second call is another race. Both put("MUG", null) and get(null) threw NullPointerException in my run.

Can I modify a ConcurrentHashMap while iterating? Yes. No ConcurrentModificationException, as the demo showed, but the iterator may or may not see entries added after it was created, and one iterator shouldn't be shared across threads.

References

• ConcurrentHashMap, Java SE 21 API (the method-detail text for compute and merge did not load, so those behaviours come from my own runs above)