Skip to content

Path 4 · lesson 3 of 5

Intermediate28 minJava 21 (OpenJDK 21) · Spring Boot 3.5

Concurrent collections and ConcurrentHashMap

How ConcurrentHashMap lets many threads work at once, which of its operations are atomic, why check-then-act on it is still a race, and what the other concurrent collections are for.

What you will learn

  • Explain how ConcurrentHashMap in OpenJDK 21 lets writers of different bins proceed in parallel and why get never waits
  • Replace a check-then-act sequence with the atomic operation that does the same job: putIfAbsent, computeIfAbsent, compute, merge or replace
  • State what may and may not happen inside a compute function and recognise the thread dump of one that takes too long
  • Say what a weakly consistent iterator and mappingCount do and do not promise
  • Choose between ConcurrentHashMap, CopyOnWriteArrayList, ConcurrentLinkedQueue and the BlockingQueue implementations for a given job
  • Find a contended lock on a shared map with jcmd Thread.print and JFR

Before you start

The concept

A plain HashMap or ArrayList shared between threads is broken: updates are lost, iteration fails with ConcurrentModificationException, and readers can see half-finished state. There are two ways to make a collection safe. A synchronized collection, such as Collections.synchronizedMap(new HashMap<>()), puts one lock around every operation, so one thread at a time uses it. A concurrent collection is thread-safe without one lock for the whole structure, so threads that touch different parts of it do not wait for each other.

CollectionHow it stays safeUse it for
ConcurrentHashMapA lock per bin for writes, no lock for readsShared maps: caches, registries, counters, in-flight sets
CopyOnWriteArrayListEvery write copies the whole array; readers use the old arrayLists read constantly and changed rarely: listeners, routing tables
ConcurrentLinkedQueueA non-blocking linked queue; poll returns null when emptyUnbounded handoff where no thread should ever wait
ArrayBlockingQueue, LinkedBlockingQueueLocks and conditions; put waits when full, take waits when emptyProducer and consumer threads with backpressure; the work queue of a thread pool
ConcurrentSkipListMapA concurrent skip listA shared map that must stay sorted by key

Eight threads, two CPUs, one lock

Simulation · not a real JVM

All threads update one synchronized map. Watch how many are running and how many are blocked, then switch the lock to striped.

Why it exists

A service has shared in-memory state whether it plans to or not: a cache of exchange rates, a registry of open sessions, counters per endpoint, a set of payment ids in progress. Request threads read and write it all the time. The collection in the middle decides two things: whether the data stays correct, and whether the threads can proceed or have to queue.

One lock around a HashMap

  • Correct for single calls and, if you hold the lock yourself, for sequences
  • One thread at a time, readers included
  • Throughput stops at what one lock can pass, however many CPUs there are
  • Anything slow done while holding the lock stops every other user of the map

ConcurrentHashMap

  • Correct for single calls and for its atomic compound methods
  • Readers never wait; writers wait only for writers of the same bin
  • Throughput scales with CPUs until something else is the limit
  • No way to lock the whole map, so multi-key invariants need another design

The lab measured both. Eight threads on 2 CPUs counted page views per URL for 5 seconds. With one synchronized block around a HashMap they managed 563,433 updates per second and a thread dump caught 7 of the 8 threads BLOCKED. With a ConcurrentHashMap of LongAdder values the same threads managed 1,132,185 per second, limited by the two CPUs and no longer by a lock.

How it works inside

How ConcurrentHashMap is built in OpenJDK 21

The map is an array of bins. A key's hash selects a bin, and a bin holds the entries whose hashes fall there, as a short linked list or, when a bin grows long, a balanced tree. What follows is the implementation described in the class's source comments. The Javadoc promises the behaviour, not these details.

  • Insert into an empty bin: a single compare-and-set (CAS) on the array slot. No lock is taken. With a sensibly sized table most inserts take this path.
  • Update a bin that has entries: synchronized on the first node of that bin. Two writers block each other only when their keys fall into the same bin. There is no lock for the map as a whole.
  • Read: get takes no lock at all. It reads the array slot and walks the bin through volatile fields. It never waits for a writer, and it returns the result of the most recently completed update for that key.
  • Long bins: when one bin collects more than 8 entries and the table has at least 64 slots, the bin is converted to a red-black tree, so many colliding keys cost a tree lookup and not a long list walk.
  • Resize: a thread that finds the table too full starts moving bins to a table twice the size, and other writers that arrive help move bins. Readers keep working throughout.
  • Counting: the number of entries is kept in a set of counter cells like a LongAdder, so that inserts in different bins do not fight over one counter.

The atomic compound operations

Instead ofUseWhat is atomic
if (!containsKey(k)) put(k, v)putIfAbsent(k, v)The test and the insert. Returns the existing value, or null if this call inserted.
v = get(k); if (v == null) { v = create(); put(k, v); }computeIfAbsent(k, key -> create())The test, the creation and the insert. The function runs at most once per absent key.
v = get(k); put(k, f(v))compute(k, (key, v) -> f(v)) or merge(k, 1, Integer::sum)Read, calculate and write for that key.
if (get(k).equals(old)) put(k, next)replace(k, old, next)The comparison and the write. Returns false if another thread changed the value first.
if (get(k).equals(v)) remove(k)remove(k, v)The comparison and the removal.

compute, computeIfAbsent, computeIfPresent and merge run your function while the bin is locked. That is what makes them atomic, and it is also their contract. The Javadoc puts it in two sentences: some attempted update operations on the map by other threads may be blocked while the computation is in progress, "so the computation should be short and simple", and the function "must not modify this map during computation".

Program outputA slow mapping function and three other threads (java ConcurrentCollections.java slow-compute)

Real JVM output
put(2), a different bin:         returned after 204 ms
get(17), same bin as key 1:      returned null after 204 ms
put(17), same bin as key 1:      returned after 8,003 ms
computeIfAbsent(1, slow load):   returned after 8,004 ms
One thread called computeIfAbsent(1, ...) with a function that takes 8 seconds. Keys 1 and 17 share a bin. put(2) in another bin returned at once. get(17) in the locked bin also returned at once: reads do not wait. put(17) waited 8,003 ms for a key that has nothing to do with key 1 except its bin. In a service that is a request that hangs for the length of somebody else's remote call.

Thread dumpjcmd <pid> Thread.print during the slow computeIfAbsent

Real JVM output
674793:
2026-11-15 21:57:01
Full thread dump OpenJDK 64-Bit Server VM (21.0.13+9-LTS mixed mode, sharing)
...
"rate-loader" #18 [674812] prio=5 os_prio=0 cpu=0.43ms elapsed=3.21s tid=0x00007a1920128ee0 nid=674812 waiting on condition  [0x00007a19241a7000]
   java.lang.Thread.State: TIMED_WAITING (sleeping)
	at java.lang.Thread.sleep0(java.base@21.0.13/Native Method)
	at java.lang.Thread.sleep(java.base@21.0.13/Thread.java:509)
	at ConcurrentCollections.slowRemoteLoad(ConcurrentCollections.java:139)
	at ConcurrentCollections.lambda$slowCompute$12(ConcurrentCollections.java:118)
	at ConcurrentCollections$Lambda/0x00007a18b4000c30.apply(Unknown Source)
	at java.util.concurrent.ConcurrentHashMap.computeIfAbsent(java.base@21.0.13/ConcurrentHashMap.java:1708)
	- locked <0x00000000ffbdaa90> (a java.util.concurrent.ConcurrentHashMap$ReservationNode)
	at ConcurrentCollections.lambda$slowCompute$13(ConcurrentCollections.java:118)
	at ConcurrentCollections$Lambda/0x00007a18b4000a08.run(Unknown Source)
	at java.lang.Thread.runWith(java.base@21.0.13/Thread.java:1596)
	at java.lang.Thread.run(java.base@21.0.13/Thread.java:1583)
...
"writer-same-bin" #19 [674813] prio=5 os_prio=0 cpu=0.33ms elapsed=3.01s tid=0x00007a192012c150 nid=674813 waiting for monitor entry  [0x00007a19087fe000]
   java.lang.Thread.State: BLOCKED (on object monitor)
	at java.util.concurrent.ConcurrentHashMap.putVal(java.base@21.0.13/ConcurrentHashMap.java:1032)
	- waiting to lock <0x00000000ffbdaa90> (a java.util.concurrent.ConcurrentHashMap$ReservationNode)
	at java.util.concurrent.ConcurrentHashMap.put(java.base@21.0.13/ConcurrentHashMap.java:1006)
	at ConcurrentCollections.lambda$slowCompute$14(ConcurrentCollections.java:122)
	at ConcurrentCollections$Lambda/0x00007a18b4003c00.run(Unknown Source)
	at java.lang.Thread.runWith(java.base@21.0.13/Thread.java:1596)
	at java.lang.Thread.run(java.base@21.0.13/Thread.java:1583)
rate-loader is inside ConcurrentHashMap.computeIfAbsent and holds locked <0x00000000ffbdaa90> (a java.util.concurrent.ConcurrentHashMap$ReservationNode): the placeholder node the map puts into an empty bin while the function runs. Above it are the application frames of the slow load. writer-same-bin is BLOCKED in ConcurrentHashMap.putVal, waiting to lock the same address. When you see threads blocked inside ConcurrentHashMap itself, find the thread that holds that address: its stack shows the mapping function that is taking too long.

Program outputA mapping function that updates the same map (java ConcurrentCollections.java recursive)

Real JVM output
computeIfAbsent inside computeIfAbsent, same key:
  java.lang.IllegalStateException: Recursive update
    at java.base/java.util.concurrent.ConcurrentHashMap.computeIfAbsent(ConcurrentHashMap.java:1763)
    at ConcurrentCollections.lambda$recursive$9(ConcurrentCollections.java:94)
    at java.base/java.util.concurrent.ConcurrentHashMap.computeIfAbsent(ConcurrentHashMap.java:1708)
    at ConcurrentCollections.recursive(ConcurrentCollections.java:94)
the same on a HashMap, two keys:
  java.util.ConcurrentModificationException
The function passed to computeIfAbsent called computeIfAbsent for the same key. The map detected it and threw IllegalStateException: Recursive update; the trace shows the two nested computeIfAbsent frames. The Javadoc only promises the exception when the recursion is detectable, so treat any update of the same map from inside a compute function as forbidden, whether or not it throws. This happens in practice with recursive caches, where computing one value needs another cached value.

Iteration, size and null

  • Iterators are weakly consistent. They never throw ConcurrentModificationException, they visit each entry that existed when the iterator was created exactly once, and they may or may not show entries added or removed since. An iteration is not a snapshot.
  • size(), isEmpty() and containsValue() describe a moment that may already be over when the call returns. The Javadoc calls them adequate for monitoring or estimation, "but not for program control". if (map.size() < limit) map.put(...) is another check-then-act.
  • mappingCount() returns a long and is the method the Javadoc recommends over size(), because the map can hold more entries than an int can express. It is an estimate under concurrent updates, like size().
  • No nulls. Neither keys nor values may be null. A null from get therefore always means that the key is absent.

Program outputThree kinds of iterator (java ConcurrentCollections.java iteration)

Real JVM output
HashMap, put during iteration:              java.util.ConcurrentModificationException
ConcurrentHashMap, writer adds 199,000 keys during iteration: no exception, iterator saw 4,037 keys, 1,000 of the 1,000 original keys, final mappingCount=200,000
CopyOnWriteArrayList, add after iterator():  iterator saw [audit metrics], list is now [audit, metrics, email]
CopyOnWriteArrayList, iterator.remove():     java.lang.UnsupportedOperationException
The HashMap iterator is fail-fast: one put during iteration and it throws. The ConcurrentHashMap iterator ran while another thread added 199,000 keys, threw nothing and saw 4,037 keys: all 1,000 that existed at the start and an arbitrary part of the new ones. The CopyOnWriteArrayList iterator is a true snapshot: it saw the two elements present when it was created and not the third, and it refuses remove().

The other collections, and what each is for

ClassBoundedWhen a thread waitsTypical job
CopyOnWriteArrayListNoNever for reads. A write copies the whole array.Listener lists and configuration read on every request and changed a few times a day
ConcurrentLinkedQueueNoNever. poll() returns null when empty.Handing work between threads that must not block. Its size() walks the queue and is not constant time.
ArrayBlockingQueueYes, fixed at constructionput when full, take when emptyA buffer between producers and consumers that must push back on producers
LinkedBlockingQueueOptionally; Integer.MAX_VALUE without a capacitytake when empty; put only if a capacity was givenThe default pool work queue. Give it a capacity.
SynchronousQueueHolds nothingEach put waits for a take and the reverseDirect handoff between two threads, as in a cached thread pool
PriorityBlockingQueueNotake when emptyWork taken by priority and not by arrival order
DelayQueueNotake until the head's delay has expiredRetries and expiries scheduled for a later time

A BlockingQueue offers each operation in four forms, and choosing the form is choosing the overload behaviour. For inserting: add throws when the queue is full, offer returns false, put waits, and offer(e, time, unit) waits up to a limit. For removing: remove throws when empty, poll returns null, take waits, and poll(time, unit) waits up to a limit.

Architecture

Drawing diagram…

Flowchart. Thread A inserts into empty bin 0 with a compare-and-set and no lock. Thread B merges a key in bin 3 and locks that bin's first node. Thread C wants to compute another key in bin 3 and waits for B. Thread D reads from bin 3 without waiting. Thread E writes to bin 7 under that bin's own lock in parallel. All bins belong to one table with no lock for the whole map.

flowchart LR
  A["Thread A puts into an empty bin"] -->|"CAS, no lock"| B0["Bin 0"]
  B["Thread B merges a key in bin 3"] -->|"locks the first node of bin 3"| B3["Bin 3"]
  C["Thread C computes another key in bin 3"] -->|"waits for thread B"| B3
  D["Thread D gets a key in bin 3"] -->|"volatile reads, never waits"| B3
  E["Thread E puts into bin 7"] -->|"its own lock, runs in parallel"| B7["Bin 7"]
  B0 --- T["One table, a lock per occupied bin, no lock for the whole map"]
  B3 --- T
  B7 --- T
Five threads on one ConcurrentHashMap: only two writers of the same bin wait for each other.
  • Contention is per bin, not per map. With a table that is large enough for its entries, two random keys rarely share a bin, so writers rarely meet.
  • Thread C shows the cost of a slow compute function: C's key is a different key, but it lives in the same bin, so C waits for as long as B's function runs.
  • Thread D shows why reads scale: a reader takes no lock even while a writer holds the bin.
  • Nothing in the picture can lock all bins at once. An operation that must see several keys in one consistent state cannot be built from this map alone.

Step by step

Drawing diagram…

Sequence diagram with two listener threads and one ConcurrentHashMap. For payment 42 both threads call containsKey, both receive false, both put the key, and both charge the card. For payment 43 both call putIfAbsent: thread A receives null and owns the payment, thread B receives the existing value and skips it, so the card is charged once.

sequenceDiagram
  participant A as Listener thread A
  participant M as ConcurrentHashMap
  participant B as Listener thread B
  A->>M: containsKey pay-42
  M-->>A: false
  B->>M: containsKey pay-42
  M-->>B: false
  A->>M: put pay-42
  B->>M: put pay-42
  Note over A,B: Both threads charge the card for pay-42
  A->>M: putIfAbsent pay-43
  M-->>A: null, so A owns pay-43
  B->>M: putIfAbsent pay-43
  M-->>B: existing value, so B skips pay-43
  Note over A: Only thread A charges the card for pay-43
The same duplicate delivery handled with check-then-act and with putIfAbsent.
  1. Every individual call in the first half is thread-safe and returns a correct answer for the moment it ran. The bug is the gap between the answer and the action taken on it.
  2. putIfAbsent closes the gap by making the map decide: exactly one caller gets null back, and that return value is the permission to proceed.
  3. The pattern generalises. Whenever code reads the map and then writes based on what it read, ask which single method performs both steps.

In a real system

A contended lock on a shared map

The lab counts page views per URL from 8 threads on 2 CPUs. The first variant does the update, and a little extra work such as formatting a log line, inside synchronized (globalMap) on a plain HashMap. The second uses striped.computeIfAbsent(url, k -> new LongAdder()).increment() and does the extra work outside any shared lock.

Program outputjava LockContention.java global, then striped

Real JVM output
pid 4547, mode global, 8 threads, 2 CPUs
global: 2,817,166 updates in 5 s = 563,433 updates/s
...
pid 4575, mode striped, 8 threads, 2 CPUs
striped: 5,660,929 updates in 5 s = 1,132,185 updates/s
563,433 against 1,132,185 updates per second: twice the throughput from the same threads and CPUs. Be precise about why. The striped variant removed the single lock and moved the extra work out of it, so the two CPUs can both do useful work all the time. With more CPUs the gap would be wider, because the global variant cannot use them.

Thread dumpjcmd 4603 Thread.print during the global run: a waiter and the owner

Real JVM output
4603:
2026-11-15 21:26:38
Full thread dump OpenJDK 64-Bit Server VM (21.0.13+9-LTS mixed mode, sharing)
...
"view-counter-0" #23 [4626] prio=5 os_prio=0 cpu=830.58ms elapsed=3.65s tid=0x00007e8754631690 nid=4626 waiting for monitor entry  [0x00007e872dbfc000]
   java.lang.Thread.State: BLOCKED (on object monitor)
	at LockContention.recordGlobal(LockContention.java:23)
	- waiting to lock <0x00000000f3500540> (a java.util.HashMap)
	at LockContention.lambda$main$1(LockContention.java:58)
	at LockContention$Lambda/0x00007e86e01c4208.run(Unknown Source)
	at java.lang.Thread.runWith(java.base@21.0.13/Thread.java:1596)
	at java.lang.Thread.run(java.base@21.0.13/Thread.java:1583)
...
"view-counter-5" #28 [4631] prio=5 os_prio=0 cpu=890.45ms elapsed=3.65s tid=0x00007e87546375f0 nid=4631 runnable  [0x00007e872d6fb000]
   java.lang.Thread.State: RUNNABLE
	at LockContention.spin(LockContention.java:37)
	at LockContention.recordGlobal(LockContention.java:25)
	- locked <0x00000000f3500540> (a java.util.HashMap)
	at LockContention.lambda$main$1(LockContention.java:58)
	at LockContention$Lambda/0x00007e86e01c4208.run(Unknown Source)
	at java.lang.Thread.runWith(java.base@21.0.13/Thread.java:1596)
	at java.lang.Thread.run(java.base@21.0.13/Thread.java:1583)
view-counter-0 is BLOCKED (on object monitor), waiting to lock <0x00000000f3500540> (a java.util.HashMap). view-counter-5 is RUNNABLE and shows locked <0x00000000f3500540>: the same address, so it is the owner, and the frame above the lock line (LockContention.spin) is what it does while holding it. In the full dump the other six view-counter- threads are blocked on that address too. Seven of eight threads waiting for one object is a contended lock; the owner's stack tells you what to move out of it.

JFRjfr view contention-by-site /tmp/contention.jfr

Real JVM output
                               Contention by Site

StackTrace                                                Count    Avg.    Max.
--------------------------------------------------------- ----- ------- -------
LockContention.recordGlobal(String)                         894 22.7 ms 58.7 ms
A thread dump is one instant; JFR measures the waiting over time. In a 6 second recording, 894 waits to enter a monitor were recorded at one site, LockContention.recordGlobal, with an average of 22.7 ms and a maximum of 58.7 ms. For an operation that needs microseconds, threads spent tens of milliseconds queuing.

JFRjfr print --events jdk.JavaMonitorEnter /tmp/contention.jfr (first event)

Real JVM output
jdk.JavaMonitorEnter {
  startTime = 21:26:35.120 (2026-11-15)
  duration = 12.9 ms
  monitorClass = java.util.HashMap (classLoader = bootstrap)
  previousOwner = "view-counter-1" (javaThreadId = 24)
  address = 0x7E86CC004D10
  eventThread = "view-counter-7" (javaThreadId = 30)
  stackTrace = [
    LockContention.recordGlobal(String) line: 24
    LockContention.lambda$main$1(CountDownLatch, long, int, String, LongAdder) line: 58
    java.lang.Thread.run() line: 1583
    ...
  ]
}
One event per wait that exceeded the recording's threshold. monitorClass = java.util.HashMap names the lock, duration = 12.9 ms the wait, previousOwner the thread that held it, and the stack trace the line that asked for it. The recording was made with settings=profile, where the threshold for this event is 10 ms; with the default settings it is 20 ms, so shorter waits are not recorded at all.

The classic bug: check-then-act

Switching to ConcurrentHashMap fixes contention and data corruption inside the map. It does not make your sequences atomic. The next program lets 8 threads claim the same 100,000 payment ids, where each id must be processed once, and then lets them add to 16 shared counters.

Program outputjava ConcurrentCollections.java check-then-act

Real JVM output
8 threads each try to claim the same 100,000 payment ids; an id must be processed once
containsKey() then put()  map size=100,000  processed=100,360  processed twice or more=360
putIfAbsent()             map size=100,000  processed=100,000  processed twice or more=0

8 threads each add 1 to the same 16 counters 100,000 times; the total must be 800,000
get() then put()         total=698,700  lost=101,300
merge(k, 1L, Long::sum)  total=800,000  lost=0
computeIfAbsent + LongAdder total=800,000  lost=0
With containsKey then put, the map ended with the right 100,000 entries and 360 ids were processed twice: the map is consistent and the business result is wrong. With putIfAbsent, zero. With get then put on counters, 101,300 of 800,000 increments were lost; merge and computeIfAbsent with a LongAdder lost none. 360 in 100,000 is under half a percent, which is why this passes tests and code review and shows up as a few duplicate charges a week.
  • Duplicate work: two threads both find the key absent and both load, send or charge. Look for containsKey or get(...) == null followed by put.
  • Lost updates: counters and balances that drift low under load. Look for get followed by put of a value derived from it.
  • Limits that are exceeded: a cache capped with if (map.size() < max) grows past the cap when many threads pass the test together.
  • Corrupted values: a ConcurrentHashMap<String, List<Order>> whose lists are plain ArrayList. The map is safe, the lists are not, and map.get(k).add(o) from two threads loses elements.

Java and Spring Boot

Four small Spring Boot components, each using the collection that fits its job. They are plain Java apart from the stereotype annotations and were compiled with javac 21 against stand-in annotations; they were not run inside Spring.

src/main/java/com/example/shop/EndpointCounters.javaJava
package com.example.shop;import java.util.Map;import java.util.TreeMap;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.atomic.LongAdder;import org.springframework.stereotype.Component;/** Requests per endpoint, updated on every request and read by a reporter once a minute. */@Componentpublic class EndpointCounters {    private final ConcurrentHashMap<String, LongAdder> counts = new ConcurrentHashMap<>();    public void record(String endpoint) {        counts.computeIfAbsent(endpoint, key -> new LongAdder()).increment();    }    /** A report, not a snapshot: counts keep changing while it is built. */    public Map<String, Long> report() {        Map<String, Long> report = new TreeMap<>();        counts.forEach((endpoint, adder) -> report.put(endpoint, adder.sum()));        return report;    }}

Why it is written this way

  • This is the frequency map from the LongAdder Javadoc. computeIfAbsent creates the adder once per key; the function only allocates an object, so it is short.
  • increment() happens outside the map operation, on the adder. Threads that count the same endpoint contend on the adder's cells, not on the bin lock.
  • merge(endpoint, 1L, Long::sum) would also be correct. It takes the bin lock on every update, so under heavy updates of the same keys the adder version scales better.
  • report() iterates a live map. Each value is right for its own moment; the report as a whole is not one instant. For metrics that is fine.

Wrong, then right

A stock service keeps available quantities and a product cache in memory. The author knew that a HashMap is unsafe and used ConcurrentHashMap for both. Under load the warehouse reports orders for items that were not in stock, and the catalog service sees bursts of identical requests.

Incorrect implementation

src/main/java/com/example/stock/StockLevels.javaJava
package com.example.stock;import java.util.Map;import java.util.concurrent.ConcurrentHashMap;import org.springframework.stereotype.Service;@Servicepublic class StockLevels {    private final Map<String, Integer> available = new ConcurrentHashMap<>();    private final Map<String, Product> products = new ConcurrentHashMap<>();    private final CatalogClient catalog;    public StockLevels(CatalogClient catalog) {        this.catalog = catalog;    }    public boolean reserve(String sku, int quantity) {        Integer current = available.get(sku);        if (current == null || current < quantity) {     // check            return false;        }        available.put(sku, current - quantity);          // act on a value that may be stale        return true;    }    public void restock(String sku, int quantity) {        Integer current = available.get(sku);        available.put(sku, current == null ? quantity : current + quantity);    }    public Product product(String sku) {        if (!products.containsKey(sku)) {                // check            products.put(sku, catalog.load(sku));        // act: a remote call of about 80 ms        }        return products.get(sku);    }}

Why it is written this way

  • Every single call here is thread-safe. None of the three methods is.
  • reserve reads the quantity, decides, and writes a value calculated from what it read. Between the read and the write another thread can do the same.
  • restock has the same shape: get, add, put.
  • product tests for the key and loads if it is absent. Every thread that arrives during the 80 ms load also finds it absent.

Why it fails

  • Two requests reserve the last unit of a SKU at the same time. Both read 1, both pass the check, both write 0 and both return true. Two orders are confirmed for one item. Nothing throws and the map is internally consistent; the quantity is simply wrong.
  • A restock that runs between a reservation's read and write is overwritten: the reservation writes its stale value minus one and the delivered goods disappear from the count. Stock levels drift, and the direction depends on timing.
  • The real run above shows the rate you should expect from this shape: get then put on shared counters lost 101,300 of 800,000 updates, and containsKey then put let 360 of 100,000 keys through twice. On a real service the window is narrower, so it shows as a few bad orders a day, only at busy times.
  • When a popular product is not cached yet, for example after a deploy, every request that arrives during the first 80 ms load starts its own load. Fifty concurrent requests make fifty identical catalog calls: a cache stampede at exactly the moment the cache is cold.
  • None of this is visible in a thread dump or in JFR, because nothing waits. You find it by reconciling counts (reserved against shipped), by duplicate-call metrics on the catalog client, and by reading the code for a read followed by a write.

Corrected implementation

src/main/java/com/example/stock/StockLevels.javaJava
package com.example.stock;import java.util.concurrent.CompletableFuture;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.Executor;import org.springframework.beans.factory.annotation.Qualifier;import org.springframework.stereotype.Service;@Servicepublic class StockLevels {    private final ConcurrentHashMap<String, Integer> available = new ConcurrentHashMap<>();    private final ConcurrentHashMap<String, CompletableFuture<Product>> products = new ConcurrentHashMap<>();    private final CatalogClient catalog;    private final Executor catalogExecutor;    public StockLevels(CatalogClient catalog, @Qualifier("catalogExecutor") Executor catalogExecutor) {        this.catalog = catalog;        this.catalogExecutor = catalogExecutor;    }    public boolean reserve(String sku, int quantity) {        while (true) {            Integer current = available.get(sku);            if (current == null || current < quantity) {                return false;            }            if (available.replace(sku, current, current - quantity)) {   // only if still equal to current                return true;            }            // another thread changed the quantity in between: read again and retry        }    }    public void restock(String sku, int quantity) {        available.merge(sku, quantity, Integer::sum);    }    public CompletableFuture<Product> product(String sku) {        CompletableFuture<Product> cached = products.computeIfAbsent(sku,                key -> CompletableFuture.supplyAsync(() -> catalog.load(key), catalogExecutor));        cached.whenComplete((product, failure) -> {            if (failure != null) {                products.remove(sku, cached);            // do not cache a failed load            }        });        return cached;    }}

Why it is written this way

  • replace(sku, current, next) writes only if the value is still the one this thread read. If another thread got in first it returns false and the loop reads the new value. Exactly one of two competing reservations for the last unit succeeds.
  • merge(sku, quantity, Integer::sum) is the atomic form of get, add, put. The function is a single addition, so holding the bin lock for it costs nothing.
  • The cache stores a future, not the product. The mapping function only creates the future, which takes microseconds, so the bin is locked briefly. The 80 ms load runs on catalogExecutor, outside the map.
  • computeIfAbsent runs its function at most once per absent key, so fifty concurrent requests share one future and cause one catalog call.
  • remove(sku, cached) removes the entry only if it still holds this exact future, so a failed load is retried by the next caller and a newer entry is never removed by mistake. It runs outside the mapping function, where modifying the map is allowed.

Trade-offs

  • The retry loop in reserve can spin under heavy contention on one SKU. Each retry is cheap, but a flash sale on a single item makes many threads retry; a compute on that key or a per-SKU queue serialises them instead.
  • product now returns a CompletableFuture, so callers must compose or wait with a timeout. That change spreads through every caller.
  • The product cache never evicts and never refreshes. A real cache needs a size limit and expiry, which is the point at which a cache library is a better choice than a hand-built map.
  • Per-key atomicity is all this gives. Reserving two SKUs together, both or neither, cannot be done with two independent map operations. That needs a transaction in a database or a lock that covers both keys, taken in a fixed order.
  • The state lives in one JVM. With two instances each has its own counts, so the authoritative stock level has to be in a shared store, and this map is at most a fast local view of it.

Configuration

The concurrent collections have no JVM flags. Their settings are constructor arguments, listed with the defaults from the Java SE 21 API documentation, plus the JFR setting that decides whether lock waits are recorded.

new ConcurrentHashMap<>(initialCapacity)Default 16 (the default initial table size)
What it does
A sizing hint. The table is created large enough for about that many entries and grows by resizing when it fills.
When to change it
Pass an estimate when you know the map will hold many entries. It avoids repeated resizes while the map fills, for example when warming a cache at start-up.
new ConcurrentHashMap<>(initialCapacity, loadFactor, concurrencyLevel)Default loadFactor 0.75 as the resize threshold; concurrencyLevel has no default
What it does
loadFactor adjusts the initial sizing only. concurrencyLevel is kept for compatibility with previous versions and is used as an additional sizing hint.
When to change it
Do not tune these to fix contention. In Java 8 and later they do not change how the map locks.
new ArrayBlockingQueue<>(capacity, fair)Default capacity is required; fair is false
What it does
A fixed capacity, and whether waiting producers and consumers are served in arrival order.
When to change it
Size the capacity from the memory and the delay you accept. Leave fairness off unless starvation of a waiting thread is a real problem; fairness lowers throughput.
new LinkedBlockingQueue<>(capacity)Default Integer.MAX_VALUE when no capacity is given
What it does
The maximum number of queued elements. Without the argument the queue is unbounded in practice.
When to change it
Always pass a capacity for a queue between threads in a service. An unbounded buffer turns a slow consumer into an OutOfMemoryError.
jdk.JavaMonitorEnter#threshold (JFR)Default 20 ms in default.jfc, 10 ms in profile.jfc
What it does
A wait to enter a synchronized block is recorded as an event only if it lasts at least this long.
When to change it
Use settings=profile for a short diagnostic recording. Many waits below the threshold add up to real contention that the recording does not show, so read the thread dump as well.

Hands-on exercise

Find the limit a single lock sets

See how one lock caps throughput regardless of threads and CPUs, find the two things that raise the cap, and compare the result with the real lab run.

Steps · 0 of 6 done

Threads, CPUs and the time spent inside the lock

Simulation · not a real JVM

Change the thread count, the CPU count, the share of work done inside the lock and the kind of lock. Watch throughput, running threads and blocked threads.

Take it further in the simulation: Lock contention: eight threads, the throughput of one

What can go wrong

Check-then-act on a concurrent map
Symptom
Occasional duplicates or counts that drift under load: an item sold twice, a payment processed twice, a counter lower than the number of events. No exception.
Cause
containsKey then put, or get then put, are two atomic calls with a gap. Another thread runs between them.
Fix
Use the single method that does both: putIfAbsent, computeIfAbsent, compute, merge, replace(k, old, new) or remove(k, v).
A slow or blocking function inside compute
Symptom
Requests for unrelated keys hang for the length of a remote call. The dump shows threads BLOCKED in ConcurrentHashMap.putVal or computeIfAbsent, waiting to lock a ConcurrentHashMap$Node or $ReservationNode.
Cause
The function runs while the bin is locked. Every writer whose key falls into that bin waits until it returns.
Fix
Keep the function to allocation and arithmetic. For slow loads store a CompletableFuture in the map and run the load on an executor.
Updating the same map from inside a compute function
Symptom
java.lang.IllegalStateException: Recursive update, or in cases the map cannot detect, a thread that never returns.
Cause
The function passed to compute, computeIfAbsent or merge called back into the same map, typically a recursive cache.
Fix
Compute dependent values before the call, or restructure so that the function does not touch the map.
Thread-safe map, unsafe values
Symptom
Elements missing from a list stored in the map, or ConcurrentModificationException and ArrayIndexOutOfBoundsException from ArrayList.
Cause
map.get(k).add(x) mutates a plain ArrayList from several threads. The map protects the mapping, not the object it maps to.
Fix
Mutate inside compute so that the bin lock covers it, or store immutable values and replace them, or use a concurrent value type.
Using size() or an iteration as a consistent view
Symptom
A cache with a size limit grows past it. A report built by iterating the map does not add up.
Cause
size() and mappingCount() are estimates under concurrent updates and iterators are weakly consistent, not snapshots.
Fix
Do not make decisions on size(). For a consistent copy, stop the writers or keep an immutable snapshot that writers replace as a whole.
CopyOnWriteArrayList for data that changes often
Symptom
High allocation rate and GC pressure, with CPU time in Arrays.copyOf under CopyOnWriteArrayList.add.
Cause
Every write copies the entire array. A list of 10,000 elements written 1,000 times a second copies 10 million references a second.
Fix
Keep it for small, read-mostly lists. For frequent writes use a concurrent queue or map, or a lock around an ArrayList.
Null keys or values
Symptom
NullPointerException from ConcurrentHashMap.put, computeIfAbsent or get after replacing a HashMap.
Cause
ConcurrentHashMap does not allow null as a key or a value, unlike HashMap.
Fix
Do not store null. Leave the key out, or store an explicit marker such as Optional.empty().

How to troubleshoot

Throughput stops rising with more threads or CPUs

Check

jcmd <pid> Thread.print > dump.txt, then grep -c 'java.lang.Thread.State: BLOCKED' dump.txt and grep 'waiting to lock' dump.txt | sort | uniq -c | sort -rn
How to read it
Many threads waiting to lock the same address is one hot lock. Search the dump for locked <that address> to find the owner and see what it does while holding it.
Need to know how much time is lost waiting for locks

Check

jcmd <pid> JFR.start duration=30s settings=profile filename=/tmp/contention.jfr, then jfr view contention-by-site /tmp/contention.jfr
How to read it
The view lists each site with the number of waits and their average and maximum duration. jfr print --events jdk.JavaMonitorEnter /tmp/contention.jfr shows single events with the lock's class and the previous owner.
Threads blocked inside ConcurrentHashMap itself

Check

grep -B 3 -A 8 'ConcurrentHashMap\$ReservationNode\|ConcurrentHashMap\$Node' dump.txt
How to read it
A thread that shows locked on such a node inside compute or computeIfAbsent is running a mapping function. If its stack continues into I/O or other slow code, that function is holding up the bin.
Duplicates or drifting counts with no errors

Check

grep -rn -B 4 '\.put(' src/main/java | grep -E 'containsKey|\.get\('
How to read it
Each hit is a containsKey or get within four lines above a put. If the put depends on what was read from a shared map, it is a check-then-act. Thread dumps and JFR show nothing for this bug, because no thread waits.
java.lang.IllegalStateException: Recursive update

Check

Read the stack trace for two frames of ConcurrentHashMap.computeIfAbsent or compute
How to read it
The function passed to the outer call reached the same map again. The frames between the two show the path.
java.util.ConcurrentModificationException in a multi-threaded path

Check

Read the top frames: java.util.HashMap$HashIterator.nextNode or java.util.ArrayList$Itr.checkForComodification
How to read it
A non-concurrent collection was modified during iteration, by another thread or by the loop itself. The concurrent collections never throw this exception.

Key takeaways

  • ConcurrentHashMap locks one bin for a write and nothing for a read. Writers of different bins and all readers proceed in parallel.
  • Each method is atomic; a sequence of methods is not. Replace check-then-act with putIfAbsent, computeIfAbsent, compute, merge or replace.
  • A compute function runs while the bin is locked. Keep it short, never block in it and never touch the same map from it.
  • Iterators are weakly consistent and size() and mappingCount() are estimates. Neither is a basis for decisions.
  • CopyOnWriteArrayList is for small lists read far more often than written. A bounded BlockingQueue is for handoff with backpressure. ConcurrentLinkedQueue never blocks and never bounds.
  • A hot lock shows in a dump as many threads waiting to lock one address, and in JFR as jdk.JavaMonitorEnter events at one site.
  • A concurrent map gives per-key atomicity in one JVM. Invariants across keys or across instances need a different tool.

Practical check

Small scenarios, one decision each. Pick what you would do, then read why.

Scenario 1 of 4

A Kafka listener with 6 threads deduplicates webhook events with a ConcurrentHashMap<String, Boolean> seen. The code is: if (!seen.containsKey(id)) { seen.put(id, true); process(event); }. About 3 events in 10,000 are processed twice, only when the provider redelivers quickly.

Which change removes the duplicates?

Scenario 2 of 4

A rate cache uses rates.computeIfAbsent(currency, c -> fxClient.fetch(c)), where fetch is an HTTP call. During a slowdown of the FX provider, a thread dump shows one thread in SocketDispatcher.read0 under computeIfAbsent holding a ConcurrentHashMap$ReservationNode, and 40 threads BLOCKED in ConcurrentHashMap.putVal and computeIfAbsent.

What is the right fix?

Scenario 3 of 4

Request threads produce up to 2,000 audit events per second in bursts. One writer thread stores about 500 per second. The service must not run out of memory during a long burst, and it is acceptable for producers to wait briefly and then drop the event with a counter.

Which buffer fits?

Scenario 4 of 4

An in-memory session registry is a ConcurrentHashMap. To keep it under 50,000 entries the code does: if (sessions.size() < 50_000) sessions.put(id, session); else reject. Under a login storm with 64 request threads the map is observed at 50,037 entries. Separately, a nightly job iterates the map to count sessions per tenant while logins continue.

Which statement is correct?

References

References: Java SE 21 API: ConcurrentHashMap (retrievals, iterators, compute, merge, mappingCount) ↗ · Java SE 21 API: java.util.concurrent package summary (concurrent collections, weakly consistent iterators, queues) ↗ · Java SE 21 API: BlockingQueue (the four forms of each operation) ↗ · Java SE 21 API: CopyOnWriteArrayList ↗ · Java SE 21 API: ConcurrentLinkedQueue ↗ · Java SE 21 API: LongAdder (frequency map with ConcurrentHashMap) ↗ · OpenJDK 21 source: ConcurrentHashMap.java (implementation overview: bins, CAS, per-bin locks, resizing) ↗ · Java SE 21 tool reference: jcmd (Thread.print, JFR.start) ↗ · Report a problem