Path 4 · lesson 3 of 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.
| Collection | How it stays safe | Use it for |
|---|---|---|
ConcurrentHashMap | A lock per bin for writes, no lock for reads | Shared maps: caches, registries, counters, in-flight sets |
CopyOnWriteArrayList | Every write copies the whole array; readers use the old array | Lists read constantly and changed rarely: listeners, routing tables |
ConcurrentLinkedQueue | A non-blocking linked queue; poll returns null when empty | Unbounded handoff where no thread should ever wait |
ArrayBlockingQueue, LinkedBlockingQueue | Locks and conditions; put waits when full, take waits when empty | Producer and consumer threads with backpressure; the work queue of a thread pool |
ConcurrentSkipListMap | A concurrent skip list | A shared map that must stay sorted by key |
Eight threads, two CPUs, one lock
Simulation · not a real JVMAll 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:
synchronizedon 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:
gettakes no lock at all. It reads the array slot and walks the bin throughvolatilefields. 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 of | Use | What 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 outputput(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
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 output674793: 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 outputcomputeIfAbsent 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.ConcurrentModificationExceptioncomputeIfAbsent 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()andcontainsValue()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 alongand is the method the Javadoc recommends oversize(), because the map can hold more entries than anintcan express. It is an estimate under concurrent updates, likesize().- No nulls. Neither keys nor values may be null. A null from
gettherefore always means that the key is absent.
Program outputThree kinds of iterator (java ConcurrentCollections.java iteration)
Real JVM outputHashMap, 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
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
| Class | Bounded | When a thread waits | Typical job |
|---|---|---|---|
CopyOnWriteArrayList | No | Never for reads. A write copies the whole array. | Listener lists and configuration read on every request and changed a few times a day |
ConcurrentLinkedQueue | No | Never. poll() returns null when empty. | Handing work between threads that must not block. Its size() walks the queue and is not constant time. |
ArrayBlockingQueue | Yes, fixed at construction | put when full, take when empty | A buffer between producers and consumers that must push back on producers |
LinkedBlockingQueue | Optionally; Integer.MAX_VALUE without a capacity | take when empty; put only if a capacity was given | The default pool work queue. Give it a capacity. |
SynchronousQueue | Holds nothing | Each put waits for a take and the reverse | Direct handoff between two threads, as in a cached thread pool |
PriorityBlockingQueue | No | take when empty | Work taken by priority and not by arrival order |
DelayQueue | No | take until the head's delay has expired | Retries 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
- 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
- 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.
putIfAbsentcloses the gap by making the map decide: exactly one caller gets null back, and that return value is the permission to proceed.- 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 outputpid 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
Thread dumpjcmd 4603 Thread.print during the global run: a waiter and the owner
Real JVM output4603: 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 outputContention by Site StackTrace Count Avg. Max. --------------------------------------------------------- ----- ------- ------- LockContention.recordGlobal(String) 894 22.7 ms 58.7 ms
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 outputjdk.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
...
]
}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 output8 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
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
containsKeyorget(...) == nullfollowed byput. - Lost updates: counters and balances that drift low under load. Look for
getfollowed byputof 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 plainArrayList. The map is safe, the lists are not, andmap.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.
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
LongAdderJavadoc.computeIfAbsentcreates 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.
package com.example.shop;import java.time.Instant;import java.util.concurrent.ConcurrentHashMap;import org.springframework.stereotype.Component;/** Stops one instance from processing the same payment id twice at the same time. */@Componentpublic class InFlightPayments { private final ConcurrentHashMap<String, Instant> inFlight = new ConcurrentHashMap<>(); /** True for exactly one caller per payment id until finish() is called. */ public boolean tryBegin(String paymentId) { return inFlight.putIfAbsent(paymentId, Instant.now()) == null; } public void finish(String paymentId) { inFlight.remove(paymentId); } public long inFlightCount() { return inFlight.mappingCount(); }}Why it is written this way
putIfAbsentis the whole mechanism: the map decides which caller wins, and the return value tells each caller whether it did.- Call
finishin afinallyblock, or an exception leaves the id claimed for ever. - This protects one JVM. With several instances behind a load balancer the same guarantee needs a shared store, for example a unique constraint in the database.
mappingCount()is used for a gauge. It is an estimate while payments start and finish, which is all a gauge needs.
package com.example.shop;import java.util.List;import java.util.concurrent.CopyOnWriteArrayList;import org.springframework.stereotype.Component;/** A few listeners registered at start-up, notified thousands of times per second. */@Componentpublic class PriceFeed { public interface PriceListener { void onPrice(String sku, long cents); } private final List<PriceListener> listeners = new CopyOnWriteArrayList<>(); public void subscribe(PriceListener listener) { listeners.add(listener); } public void unsubscribe(PriceListener listener) { listeners.remove(listener); } public void publish(String sku, long cents) { for (PriceListener listener : listeners) { listener.onPrice(sku, cents); } }}Why it is written this way
publishiterates without a lock over the array that existed when the loop started. A listener may subscribe or unsubscribe during the loop, even from insideonPrice, and the loop is unaffected.- Each
subscribecopies the array. With 5 listeners and a handful of changes a day that is free. With thousands of elements or frequent writes it is the wrong class. - A synchronized list would force every
publishto hold a lock for the whole loop, including the listeners' own code.
package com.example.shop;import java.util.ArrayList;import java.util.List;import java.util.concurrent.ArrayBlockingQueue;import java.util.concurrent.BlockingQueue;import java.util.concurrent.TimeUnit;import java.util.concurrent.atomic.LongAdder;import org.springframework.stereotype.Component;/** Request threads offer audit lines; one writer thread drains them in batches. */@Componentpublic class AuditBuffer { private final BlockingQueue<String> lines = new ArrayBlockingQueue<>(10_000); private final LongAdder dropped = new LongAdder(); /** Called on request threads. Waits at most 20 ms for space. */ public boolean submit(String line) throws InterruptedException { boolean accepted = lines.offer(line, 20, TimeUnit.MILLISECONDS); if (!accepted) { dropped.increment(); } return accepted; } /** Called in a loop by the single writer thread. Waits up to 1 s for the first line. */ public List<String> nextBatch() throws InterruptedException { List<String> batch = new ArrayList<>(500); String first = lines.poll(1, TimeUnit.SECONDS); if (first != null) { batch.add(first); lines.drainTo(batch, 499); } return batch; } public long droppedCount() { return dropped.sum(); }}Why it is written this way
- The capacity of 10,000 is the memory bound. An unbounded
LinkedBlockingQueueor aConcurrentLinkedQueuehere would grow until the heap is full if the writer stalls. offerwith a timeout is a deliberate middle way: a request waits up to 20 ms for space, then gives up and the loss is counted.putwould make request threads wait without limit;addwould throw.pollwith a timeout lets the writer thread wake up regularly, so it can notice a shutdown.drainTothen takes up to 499 more without waiting, which gives batches under load and low delay when idle.- Alert on
droppedCount. A bounded queue turns an invisible backlog into a number.
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
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.
reservereads the quantity, decides, and writes a value calculated from what it read. Between the read and the write another thread can do the same.restockhas the same shape: get, add, put.producttests 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
restockthat 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:
getthenputon shared counters lost 101,300 of 800,000 updates, andcontainsKeythenputlet 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
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. computeIfAbsentruns 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
reservecan spin under heavy contention on one SKU. Each retry is cheap, but a flash sale on a single item makes many threads retry; acomputeon that key or a per-SKU queue serialises them instead. productnow returns aCompletableFuture, 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
loadFactoradjusts the initial sizing only.concurrencyLevelis 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
synchronizedblock is recorded as an event only if it lasts at least this long. - When to change it
- Use
settings=profilefor 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 JVMChange 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.
What you should see
With the global lock, throughput is set by how long each operation holds the lock. More threads add blocked threads and no throughput, and more CPUs add almost nothing, because only one thread at a time can be inside. Shortening the time inside the lock raises the limit until the CPUs become the bottleneck. With the striped lock almost nobody is blocked and throughput follows the CPU count. The real lab, with 8 threads on 2 CPUs, measured 563,433 updates per second and 7 blocked threads with the global lock, and 1,132,185 per second with ConcurrentHashMap and LongAdder.
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
containsKeythenput, orgetthenput, 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)orremove(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
BLOCKEDinConcurrentHashMap.putValorcomputeIfAbsent, waiting to lock aConcurrentHashMap$Nodeor$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
CompletableFuturein 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,computeIfAbsentormergecalled 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
ConcurrentModificationExceptionandArrayIndexOutOfBoundsExceptionfromArrayList. - Cause
map.get(k).add(x)mutates a plainArrayListfrom several threads. The map protects the mapping, not the object it maps to.- Fix
- Mutate inside
computeso 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()andmappingCount()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.copyOfunderCopyOnWriteArrayList.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
NullPointerExceptionfromConcurrentHashMap.put,computeIfAbsentorgetafter replacing aHashMap.- Cause
ConcurrentHashMapdoes not allow null as a key or a value, unlikeHashMap.- 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 lockthe same address is one hot lock. Search the dump forlocked <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.jfrshows 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
lockedon such a node insidecomputeorcomputeIfAbsentis 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
containsKeyorgetwithin four lines above aput. If theputdepends 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
ConcurrentHashMaplocks 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,mergeorreplace. - 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()andmappingCount()are estimates. Neither is a basis for decisions. CopyOnWriteArrayListis for small lists read far more often than written. A boundedBlockingQueueis for handoff with backpressure.ConcurrentLinkedQueuenever blocks and never bounds.- A hot lock shows in a dump as many threads waiting to lock one address, and in JFR as
jdk.JavaMonitorEnterevents 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