Path 4 · lesson 4 of 5
ForkJoinPool and work stealing
How ForkJoinPool runs split-up work on per-worker deques, what the common pool is and who shares it, and how one blocking parallel stream starves unrelated code.
What you will learn
- Explain how per-worker deques and stealing keep every core busy on work that splits into subtasks
- Write a RecursiveTask with fork, compute and join in the right order, and choose a threshold from a measurement
- State the default parallelism of the common pool in JDK 21 and list the code that shares it
- Recognise common-pool starvation in a thread dump and tell it apart from CPU saturation
- Decide when blocking work belongs on a dedicated executor, behind a ManagedBlocker, or on virtual threads
Before you start
The concept
A ThreadPoolExecutor has one shared queue: every worker takes the next task from the same place. That is the right shape for independent requests. It is a poor shape for a task that splits itself into subtasks and waits for them, because a worker that waits for its own subtasks holds a thread while doing nothing, and all workers contend on one queue.
ForkJoinPool is an ExecutorService built for that second shape. Every worker thread owns a deque (a double-ended queue). A task that forks a subtask pushes it onto the deque of the worker it is running on. The worker takes its own tasks from the same end it pushed them (newest first), and a worker with nothing to do steals from the other end of someone else's deque (oldest first). The API documentation calls this work-stealing: all threads in the pool attempt to find and execute tasks submitted to the pool or created by other active tasks.
| ThreadPoolExecutor | ForkJoinPool | |
|---|---|---|
| Queues | One shared BlockingQueue | One deque per worker, plus shared submission queues for callers outside the pool |
| A task that waits for its subtasks | Blocks its thread. On a small pool this is the starvation from the CompletableFuture lesson | join() runs other pending tasks while it waits, and the pool may add a spare thread |
| Meant for | Independent tasks, including blocking I/O, with a size and queue you choose | CPU-bound work that divides recursively: sorting, aggregation, parallel streams |
| Threads | Core and maximum size, your thread factory | A target parallelism. Workers are daemon threads and are reclaimed when idle |
| When full | Queue fills, then the rejection policy runs | No bound on queued tasks. It rejects only when shut down or out of internal resources |
Program outputThe common pool on a 2-CPU, a tuned and an 8-CPU JVM (CommonPoolProbe.java)
Real JVM output$ java -XX:ActiveProcessorCount=2 -Xmx256m CommonPoolProbe.java availableProcessors=2 commonPool parallelism=1 8 blocking tasks of 500 ms took 2,028 ms on 2 threads ForkJoinPool.commonPool-worker-1 main $ java -XX:ActiveProcessorCount=2 -Djava.util.concurrent.ForkJoinPool.common.parallelism=3 -Xmx256m CommonPoolProbe.java availableProcessors=2 commonPool parallelism=3 8 blocking tasks of 500 ms took 1,017 ms on 4 threads ForkJoinPool.commonPool-worker-1 ForkJoinPool.commonPool-worker-2 ForkJoinPool.commonPool-worker-3 main $ java -XX:ActiveProcessorCount=8 -Xmx256m CommonPoolProbe.java availableProcessors=8 commonPool parallelism=7 8 blocking tasks of 500 ms took 533 ms on 8 threads ForkJoinPool.commonPool-worker-1 ... ForkJoinPool.commonPool-worker-7 main
main) and take about 2,000 ms. With parallelism 3 there are 4 threads and it takes about 1,000 ms. With 8 processors there are 7 workers plus main, and it takes about 500 ms. Elapsed time is tasks x 500 ms divided by parallelism + 1: the pool was sized for CPU work and has no idea these tasks only wait.Why it exists
Few teams create a ForkJoinPool on purpose. Almost every service uses one anyway, because the common pool sits behind APIs that look harmless:
| API | What the JDK 21 documentation says |
|---|---|
collection.parallelStream(), stream.parallel() | JEP 444 describes the common pool as the pool used in the implementation of parallel streams. The calling thread takes part as well. |
CompletableFuture.supplyAsync(f), runAsync, and every ...Async method without an executor argument | Performed using ForkJoinPool.commonPool(), unless it does not support a parallelism level of at least two, in which case a new Thread is created to run each task. |
Arrays.parallelSort, Arrays.parallelPrefix, Arrays.parallelSetAll | The ForkJoin common pool is used to execute any parallel tasks. |
ConcurrentHashMap bulk operations with a parallelism threshold (forEach, search, reduce) | The ForkJoinPool.commonPool() is used for all parallel computations. |
ForkJoinTask.fork() and invoke() called from a thread that is not a pool worker | Uses the common pool if not inForkJoinPool(). |
So the common pool is one small shared resource for the whole process: your code, every library on the classpath and the framework. It has a handful of threads, it was sized for CPU work, and it has no back-pressure. One piece of code that parks its workers on a slow remote call takes capacity away from every other user, and nothing in the code that suffers points at the code that caused it.
Program outputOn 2 CPUs, supplyAsync without an executor does not use a pool at all
Real JVM outputavailableProcessors=2 commonPool parallelism=1 unrelated supplyAsync (no executor): submitted at +100 ms, waited 7 ms, ran on Thread-0 plain blocking: 8 blocking calls of 500 ms in a parallel stream took 2,088 ms threads that ran the stream (2): [ForkJoinPool.commonPool-worker-1, main]
CompletableFuture.supplyAsync ran on Thread-0, not on a pool worker. That is the documented fallback: when the common pool cannot offer a parallelism of at least two, each async task gets a new thread. It was not delayed here, but nothing bounds the number of such threads. Many containers run with a CPU limit of 1 or 2, so this is a common production configuration, not a corner case.How it works inside
Deques: why own work is taken newest first and stolen oldest first
Take a task that sums 8 million numbers. It forks the left half (4 million) and continues with the right half, which forks again (2 million), and so on. The worker's deque now holds tasks of decreasing size: the oldest entry is the biggest piece of work, the newest is the smallest and its data was touched most recently.
- The owner pops the newest task. It is small, its data is likely still in the CPU cache, and this is the order a plain recursive call would have used.
- A thief takes the oldest task. It is the largest piece available, so one steal moves a lot of work and the thief does not have to come back soon. The thief then splits that piece on its own deque.
- Owner and thief work at opposite ends, so they rarely touch the same slot. This is what keeps contention low compared with one shared queue.
- A thread outside the pool (a request thread calling
pool.submitorpool.invoke) cannot push onto a worker's deque. Its task goes to a shared submission queue, which idle workers also scan.
The default mode is this stack-like (LIFO) processing of a worker's own tasks. A pool constructed with asyncMode = true processes its own tasks first-in-first-out instead, which the documentation recommends for event-style tasks that are never joined. The virtual-thread scheduler in the next lesson is a ForkJoinPool in that mode.
fork, compute, join
fork() pushes a task onto the current worker's deque and returns at once. join() returns the result of a task. If the task is still on the caller's own deque, join() simply runs it. If it was stolen, the joining worker does not go to sleep straight away: it runs other pending tasks while it waits, and the pool may start or resume a spare thread to keep the target parallelism. This is why a ForkJoinPool survives the nested waiting that deadlocks a small ThreadPoolExecutor.
Choosing a threshold
Below some size a task should stop splitting and do the work in a loop. Every split allocates a task object, pushes and pops it, and may be stolen. If the leaves are too large there is nothing to steal and cores sit idle; if they are too small the bookkeeping costs more than the work. The ForkJoinTask documentation gives a very rough rule: a task should perform more than 100 and fewer than 10,000 basic computational steps. Measure it for your own work.
Program outputSumming 20,000,000 longs on a ForkJoinPool of 2 with five thresholds (best of 8 runs each)
Real JVM outputavailableProcessors=2 commonPool parallelism=1 plain loop on one thread 45 ms threshold 20,000,000 1 leaf tasks 36 ms steals 1 threshold 1,000,000 32 leaf tasks 20 ms steals 4 threshold 10,000 2,048 leaf tasks 31 ms steals 5 threshold 100 262,144 leaf tasks 151 ms steals 2 threshold 4 7,417,088 leaf tasks 757 ms steals 3
Blocking, and ManagedBlocker
The pool keeps its parallelism when workers wait in join(), because it knows about that wait. It knows nothing about a worker that is stuck in a socket read, a JDBC call, Thread.sleep or a synchronized block. The documentation is explicit: no adjustments are guaranteed in the face of blocked I/O or other unmanaged synchronization. With parallelism 3, three blocked workers mean the pool does no work at all until one returns.
ForkJoinPool.managedBlock(blocker) is the way to tell the pool. You wrap the blocking call in a ManagedBlocker; when it runs on a pool worker, the pool may first be expanded with a spare thread so that the target parallelism is still available during the call. For the common pool the number of spares is capped by java.util.concurrent.ForkJoinPool.common.maximumSpares, default 256. CompletableFuture.join() and get() already go through this path, which you can see as ForkJoinPool.managedBlock in a thread dump.
Program outputThe same 8 blocking calls with the socket read wrapped in ForkJoinPool.managedBlock
Real JVM outputavailableProcessors=2 commonPool parallelism=3 unrelated supplyAsync (no executor): submitted at +100 ms, waited 9 ms, ran on ForkJoinPool.commonPool-worker-8 managedBlock: 8 blocking calls of 500 ms in a parallel stream took 595 ms threads that ran the stream (8): [ForkJoinPool.commonPool-worker-1, ForkJoinPool.commonPool-worker-2, ForkJoinPool.commonPool-worker-3, ForkJoinPool.commonPool-worker-4, ForkJoinPool.commonPool-worker-5, ForkJoinPool.commonPool-worker-6, ForkJoinPool.commonPool-worker-7, main] common pool now: java.util.concurrent.ForkJoinPool@4dd8dc3[Running, parallelism = 3, size = 8, active = 0, running = 0, steals = 8, tasks = 0, submissions = 0]
size = 8 (last line): each worker that announced a blocking call was compensated with a spare. All 8 calls ran at once (595 ms instead of about 1,000 ms) and the unrelated supplyAsync waited 9 ms. Compare with the unmanaged run in the Real-world section. The cost is the extra threads, up to 256 for the common pool, which is a thread-per-blocked-task pool that nobody sized.Architecture
Drawing diagram…
Flowchart. Parallel streams, CompletableFuture async calls without an executor and library code all submit to the common pool. Tasks from outside enter shared submission queues scanned by idle workers. Each worker pushes forked tasks onto its own deque and pops the newest. Idle workers steal the oldest task from another worker's deque. One worker is blocked on a slow remote service and does none of this.
flowchart LR PS["Parallel streams"] --> CP["Common pool, parallelism is processors minus 1"] CF["CompletableFuture async calls without an executor"] --> CP LIB["Arrays.parallelSort and library code"] --> CP CP --> SQ["Shared submission queues"] SQ -->|"scanned by idle workers"| W1["Worker 1"] W1 -->|"fork pushes, pop takes the newest"| D1["Deque of worker 1"] W2["Worker 2"] -->|"fork pushes, pop takes the newest"| D2["Deque of worker 2"] W2 -.->|"idle, steals the oldest"| D1 W3["Worker 3"] -.->|"idle, steals the oldest"| D2 W3 -->|"blocked in a socket read"| IO["Slow remote service"]
- The three boxes on the left do not know about each other. They meet in the common pool, which is why a problem in one shows up as slowness in another.
- Solid arrows from a worker to its deque are the cheap path: push and pop at the same end, with no other thread involved.
- Dotted arrows are steals. They take from the far end of another worker's deque, where the largest pending task is.
- Worker 3 is blocked on I/O. The pool still counts it as one of its three threads, so the capacity for everything on the left has dropped by a third, and nothing was queued or rejected to show it.
Step by step
Drawing diagram…
Sequence diagram. A caller invokes a sum over 8 million elements on worker 1. Worker 1 forks the left half onto its deque, keeps splitting the right half and forks a quarter. Worker 2 steals the oldest task, the left half, and splits it on its own deque. Worker 1 computes its leaf, joins the quarter by popping and running it, then joins the stolen half, helping with other tasks until worker 2 returns the result.
sequenceDiagram participant C as Caller thread participant A as Worker 1 participant Q as Deque of worker 1 participant B as Worker 2 C->>A: invoke sum of elements 0 to 8M A->>Q: fork left half, 0 to 4M Note over A: keeps the right half and splits it again A->>Q: fork 4M to 6M B->>Q: steal the oldest task, 0 to 4M Note over B: splits 0 to 4M on its own deque Note over A: computes 6M to 8M in a loop A->>Q: join 4M to 6M, still on the deque Note over A: pops it and runs it directly A->>B: join 0 to 4M, stolen and not finished Note over A: runs other pending tasks while it waits B-->>A: result for 0 to 4M A-->>C: total
- Worker 2 stole the 4-million-element task, not the 2-million one that was pushed later. One steal moved half of the whole job.
- The first
joincosts almost nothing: the task was never stolen, so the worker pops it from its own deque and runs it as an ordinary call. - The second
joinis on a stolen task. Worker 1 does not park immediately; it looks for other work first. If it does have to wait, the pool can activate a spare thread so that two threads are still running. - The caller thread blocks in
invokefor the whole computation. If the caller is a request thread, the request holds that thread for as long as the pool is busy.
In a real system
A catalog service runs in a pod with a CPU limit of 4, so its common pool has 3 workers. A nightly export enriches 50,000 SKUs with a price from the pricing service, and someone made it faster with skus.parallelStream(). The same service answers /quote requests, and that code calls CompletableFuture.supplyAsync(() -> tax.estimate(cart)) with no executor. Both pass their tests. During the export, p99 latency of /quote rises from 40 ms to over a second, CPU stays low, and nothing is logged.
The lab program below reproduces the mechanism on a real JVM with common-pool parallelism 3. Eight tasks each wait 500 ms for an answer on a socket inside a parallel stream. A separate thread, which stands for the /quote handler, submits one trivial supplyAsync 100 ms after the stream started.
Program outputA blocking parallel stream delays unrelated code (ForkJoinPoolWorkStealing.java blocked)
Real JVM outputavailableProcessors=2 commonPool parallelism=3 unrelated supplyAsync (no executor): submitted at +100 ms, waited 978 ms, ran on ForkJoinPool.commonPool-worker-3 plain blocking: 8 blocking calls of 500 ms in a parallel stream took 1,087 ms threads that ran the stream (4): [ForkJoinPool.commonPool-worker-1, ForkJoinPool.commonPool-worker-2, ForkJoinPool.commonPool-worker-3, main] common pool now: java.util.concurrent.ForkJoinPool@4f3f5b24[Running, parallelism = 3, size = 3, active = 0, running = 0, steals = 4, tasks = 0, submissions = 0]
main). Line 2 is the damage: the unrelated task needed no time at all, yet it waited 978 ms, because every common-pool worker was parked in a socket read and it could only start when one came back. Last line: submissions = 0 after the fact. A ForkJoinPool keeps no history of who waited, so you have to catch it while it happens.Reading it in a thread dump
Take a dump while the latency is high: jcmd <pid> Thread.print. Look for the threads named ForkJoinPool.commonPool-worker-N. This is the dump of the program above with the remote answering slowly:
Thread dumpjcmd <pid> Thread.print: a common-pool worker and the thread that is waiting for the pool
Real JVM output"ForkJoinPool.commonPool-worker-2" #21 [352869] daemon prio=5 os_prio=0 cpu=0.65ms elapsed=4.92s tid=0x000078d8d80015d0 nid=352869 runnable [0x000078d950428000] java.lang.Thread.State: RUNNABLE at sun.nio.ch.SocketDispatcher.read0(java.base@21.0.13/Native Method) at sun.nio.ch.SocketDispatcher.read(java.base@21.0.13/SocketDispatcher.java:48) at sun.nio.ch.NioSocketImpl.tryRead(java.base@21.0.13/NioSocketImpl.java:256) at sun.nio.ch.NioSocketImpl.implRead(java.base@21.0.13/NioSocketImpl.java:307) at sun.nio.ch.NioSocketImpl.read(java.base@21.0.13/NioSocketImpl.java:346) at sun.nio.ch.NioSocketImpl$1.read(java.base@21.0.13/NioSocketImpl.java:796) at java.net.Socket$SocketInputStream.read(java.base@21.0.13/Socket.java:1099) at java.net.Socket$SocketInputStream.read(java.base@21.0.13/Socket.java:1093) at ForkJoinPoolWorkStealing.fetchPrice(ForkJoinPoolWorkStealing.java:130) at ForkJoinPoolWorkStealing.lambda$blocking$4(ForkJoinPoolWorkStealing.java:173) ... at java.util.concurrent.CountedCompleter.exec(java.base@21.0.13/CountedCompleter.java:754) at java.util.concurrent.ForkJoinTask.doExec(java.base@21.0.13/ForkJoinTask.java:387) at java.util.concurrent.ForkJoinPool$WorkQueue.topLevelExec(java.base@21.0.13/ForkJoinPool.java:1312) at java.util.concurrent.ForkJoinPool.scan(java.base@21.0.13/ForkJoinPool.java:1843) at java.util.concurrent.ForkJoinPool.runWorker(java.base@21.0.13/ForkJoinPool.java:1808) at java.util.concurrent.ForkJoinWorkerThread.run(java.base@21.0.13/ForkJoinWorkerThread.java:188) "report-thread" #19 [352836] prio=5 os_prio=0 cpu=1.84ms elapsed=4.94s tid=0x000078d96c146570 nid=352836 waiting on condition [0x000078d950629000] java.lang.Thread.State: WAITING (parking) at jdk.internal.misc.Unsafe.park(java.base@21.0.13/Native Method) - parking to wait for <0x00000000e7a5eda8> (a java.util.concurrent.CompletableFuture$Signaller) at java.util.concurrent.locks.LockSupport.park(java.base@21.0.13/LockSupport.java:221) at java.util.concurrent.CompletableFuture$Signaller.block(java.base@21.0.13/CompletableFuture.java:1864) at java.util.concurrent.ForkJoinPool.unmanagedBlock(java.base@21.0.13/ForkJoinPool.java:3780) at java.util.concurrent.ForkJoinPool.managedBlock(java.base@21.0.13/ForkJoinPool.java:3725) at java.util.concurrent.CompletableFuture.waitingGet(java.base@21.0.13/CompletableFuture.java:1898) at java.util.concurrent.CompletableFuture.join(java.base@21.0.13/CompletableFuture.java:2117) at ForkJoinPoolWorkStealing.lambda$blocking$3(ForkJoinPoolWorkStealing.java:165)
ForkJoinPool.commonPool-worker-2 says which pool this is. (2) The top frames are a socket read (SocketDispatcher.read0, NioSocketImpl.read): a pool meant for computation is waiting on the network. (3) The state is RUNNABLE, which misleads: a platform thread blocked in a native socket read is reported as RUNNABLE. Compare cpu=0.65ms with elapsed=4.92s on the first line: the thread has used under a millisecond of CPU in almost 5 seconds. (4) The frames ForkJoinPool.scan and CountedCompleter.exec at the bottom, together with the java.util.stream frames cut from the middle, show that a parallel stream brought the call here, and your own frame (fetchPrice) says which one. In the full dump all three workers and main have this same stack. The second thread, report-thread, is the victim: WAITING (parking) in CompletableFuture.join on a task that no worker is free to run.| What you see | Common-pool starvation | CPU saturation |
|---|---|---|
| Process CPU | Low | At the limit |
| Worker stacks | All workers in the same blocking call: socket read, JDBC, Thread.sleep, a lock | Workers in your computation, different frames in each dump |
cpu= against elapsed= on worker threads | Milliseconds of CPU over seconds or minutes of life | CPU time close to elapsed time |
| Victims | Threads WAITING in CompletableFuture.join or get, or in a stream terminal operation | The same, but workers are busy, not parked |
| Fix | Move the blocking work off the common pool | Less work, more cores, or a higher threshold |
- Count the workers and compare with the parallelism:
jcmd <pid> Thread.print | grep -c 'ForkJoinPool.commonPool-worker'. - Print their stacks:
jcmd <pid> Thread.print | grep -A 14 'ForkJoinPool.commonPool-worker'. If every one shows the same I/O frame, the pool is starved, not busy. - Take a second dump a few seconds later. The same frames again mean the workers are stuck in long calls, not passing through short ones.
- Find the caller from the first application frame under the I/O frames. That is the code to move, not the code that reported the latency.
- With a JFR recording,
jfr print --events jdk.SocketRead <file>lists socket reads longer than 20 ms (the default threshold) with the thread name and stack, so reads onForkJoinPool.commonPool-worker-Nstand out.
Java and Spring Boot
Three pieces: a probe you can run in any environment to see the common pool you really have, a RecursiveTask written in the correct fork, compute, join order, and a Spring configuration that gives CPU-heavy fork/join work its own named pool so it cannot interfere with the common pool. The two plain-Java files were compiled with javac 21 and the probe was run; the Spring classes were compiled only against hand-written stand-ins for the Spring and Micrometer types, not against the real libraries.
import java.util.Set;import java.util.TreeSet;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.ForkJoinPool;import java.util.stream.IntStream;/** * Prints what the common pool looks like in this JVM, then runs 8 tasks that each block for 500 ms * in a parallel stream and reports which threads ran them and how long it took. * * java CommonPoolProbe.java * java -XX:ActiveProcessorCount=8 CommonPoolProbe.java * java -Djava.util.concurrent.ForkJoinPool.common.parallelism=3 CommonPoolProbe.java */public class CommonPoolProbe { public static void main(String[] args) { System.out.printf("availableProcessors=%d commonPool parallelism=%d%n", Runtime.getRuntime().availableProcessors(), ForkJoinPool.getCommonPoolParallelism()); Set<String> threads = ConcurrentHashMap.newKeySet(); long t0 = System.nanoTime(); IntStream.range(0, 8).parallel().forEach(i -> { threads.add(Thread.currentThread().getName()); try { Thread.sleep(500); // stands in for a blocking remote call } catch (InterruptedException e) { Thread.currentThread().interrupt(); } }); long ms = (System.nanoTime() - t0) / 1_000_000; System.out.printf("8 blocking tasks of 500 ms took %,d ms on %d threads%n", ms, threads.size()); new TreeSet<>(threads).forEach(name -> System.out.println(" " + name)); }}Why it is written this way
ForkJoinPool.getCommonPoolParallelism()is the number to check in the real container. It is fixed when the common pool is first used.- The set of thread names shows that the calling thread (
main) takes part in a parallel stream next to the pool workers. That is why the default parallelism is one less than the processor count. Thread.sleepis a blocking call the pool cannot see, like a socket read. Elapsed time therefore follows the thread count and not the processor count.- This is the same file as
labs/jvm/extras/CommonPoolProbe.java. Its output is shown in the Concept section.
package com.example.risk;import java.util.concurrent.RecursiveTask;/** Sums the exposure of positions[from, to). Splits until a range is at most THRESHOLD long. */public final class ExposureTask extends RecursiveTask<Double> { private static final long serialVersionUID = 1L; /** Chosen by measurement: leaves of 10,000 positions cost far more than the task bookkeeping. */ static final int THRESHOLD = 10_000; private final double[] quantity; private final double[] price; private final int from; private final int to; public ExposureTask(double[] quantity, double[] price, int from, int to) { this.quantity = quantity; this.price = price; this.from = from; this.to = to; } @Override protected Double compute() { if (to - from <= THRESHOLD) { double sum = 0; for (int i = from; i < to; i++) { sum += Math.abs(quantity[i] * price[i]); } return sum; } int mid = (from + to) >>> 1; ExposureTask left = new ExposureTask(quantity, price, from, mid); ExposureTask right = new ExposureTask(quantity, price, mid, to); left.fork(); // make the left half available to thieves double rightSum = right.compute(); // do the right half in this thread return rightSum + left.join(); // then take the left half back, or wait for the thief }}Why it is written this way
- The leaf is a plain loop over arrays. No allocation, no I/O, no locks: this is the kind of work a ForkJoinPool is for.
left.fork()thenright.compute()thenleft.join(). Joining in the reverse order of forking lets the worker pop its own task from the deque when nobody stole it.- The task reads shared arrays and writes nothing shared. Subtasks that write to a common structure need the tools from the concurrency path and usually lose the speed-up.
THRESHOLDis a constant here because the work per element is fixed. When work per element varies, split by estimated cost, not by element count.
package com.example.risk;import java.util.concurrent.ForkJoinPool;import java.util.concurrent.ForkJoinWorkerThread;import io.micrometer.core.instrument.MeterRegistry;import io.micrometer.core.instrument.binder.jvm.ExecutorServiceMetrics;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.stereotype.Service;@Configurationclass RiskPoolConfig { /** A dedicated pool for CPU-bound risk calculations. Never used for I/O. */ @Bean(destroyMethod = "shutdown") ForkJoinPool riskPool(MeterRegistry registry) { int parallelism = Math.max(1, Runtime.getRuntime().availableProcessors() - 1); ForkJoinPool.ForkJoinWorkerThreadFactory factory = pool -> { ForkJoinWorkerThread worker = ForkJoinPool.defaultForkJoinWorkerThreadFactory.newThread(pool); worker.setName("risk-fj-" + worker.getPoolIndex()); return worker; }; ForkJoinPool pool = new ForkJoinPool(parallelism, factory, null, false); ExecutorServiceMetrics.monitor(registry, pool, "risk-fj"); return pool; }}@Serviceclass ExposureService { private final ForkJoinPool riskPool; ExposureService(ForkJoinPool riskPool) { this.riskPool = riskPool; } double totalExposure(double[] quantity, double[] price) { return riskPool.invoke(new ExposureTask(quantity, price, 0, quantity.length)); }}Why it is written this way
- A named pool makes thread dumps readable:
risk-fj-3in a stack tells you which workload it is, whereForkJoinPool-2-worker-3does not. - Parallelism is processors minus one because the request thread that calls
invokewaits and the other request threads need a core as well. On a 2-CPU pod this pool has one worker, and the honest conclusion may be that fork/join buys nothing there. ExecutorServiceMetrics.monitorpublishes Micrometer gauges for a ForkJoinPool, among themexecutor.active,executor.running,executor.queuedand the counterexecutor.steals, tagged with the name given here.invokeblocks the calling request thread until the result is ready and rethrows the task's exception. Tasks submitted from outside go to the submission queues, which are unbounded, so limit how many requests may start a calculation at once.- The fourth constructor argument is
asyncMode.falsekeeps the default stack-like order, which is what joined, recursive tasks want.
Wrong, then right
The export from the Real-world section, as it is usually written and as it should be. The Spring classes follow Spring Boot 3.2 or later (RestClient) and were compiled only against hand-written stand-ins for the Spring types, not against the real libraries; the mechanism they rely on is the one measured above.
Incorrect implementation
package com.example.catalog;import java.math.BigDecimal;import java.util.List;import java.util.concurrent.CompletableFuture;import org.springframework.stereotype.Service;import org.springframework.web.client.RestClient;@Servicepublic class CatalogExportService { private final RestClient pricing; public CatalogExportService(RestClient.Builder builder) { this.pricing = builder.baseUrl("http://pricing.internal").build(); } /** Nightly export of 50,000 SKUs. "Made faster" with a parallel stream. */ public List<PricedSku> export(List<String> skus) { return skus.parallelStream() .map(sku -> new PricedSku(sku, fetchPrice(sku))) // a blocking HTTP call per element .toList(); } private BigDecimal fetchPrice(String sku) { return pricing.get().uri("/prices/{sku}", sku).retrieve().body(BigDecimal.class); } public record PricedSku(String sku, BigDecimal price) { }}/** Elsewhere in the same service: looks unrelated, shares the same pool. */@Serviceclass QuoteService { private final TaxCalculator tax; QuoteService(TaxCalculator tax) { this.tax = tax; } CompletableFuture<BigDecimal> estimateTax(Cart cart) { return CompletableFuture.supplyAsync(() -> tax.estimate(cart)); // no executor: common pool }}Why it is written this way
parallelStream()runs the lambda on the common pool's workers and on the calling thread. On a 4-CPU pod that is 3 workers plus the caller, for the whole JVM.fetchPriceblocks in a socket read. The pool cannot see that wait, so it does not add threads: each worker is simply gone for the duration of the call.QuoteServicenever mentions the export.supplyAsyncwithout an executor argument is the only link, and it is invisible at the call site.TaxCalculatorandCartare assumed from the rest of the project.
Why it fails
- The export is limited by the wrong number. Its speed is the parallelism of the common pool plus one, which came from the CPU limit of the pod, not from what the pricing service can take. On 4 CPUs, 50,000 calls of 80 ms run 4 at a time and need about 17 minutes; on 2 CPUs they run 2 at a time.
- While the export runs, every common-pool worker is parked in
fetchPricealmost all the time. AsupplyAsyncfromQuoteServicewaits in the submission queue until a worker returns from a remote call, so each quote gains up to one full pricing call of latency, and far more when pricing is slow. In the real run above a task that needed no time waited 978 ms. - Nothing fails loudly. The ForkJoinPool does not reject, has no queue limit and logs nothing. CPU is low, so autoscaling does not react. The symptom appears in
/quote, the cause is in the export, and the only artefact that connects them is a thread dump showingForkJoinPool.commonPool-worker-Nthreads in a socket read. - If the pricing service hangs without a read timeout, the workers never come back. From then on every parallel stream and every executor-less async call in the process hangs too, until a restart.
Corrected implementation
package com.example.catalog;import java.math.BigDecimal;import java.util.List;import java.util.concurrent.ArrayBlockingQueue;import java.util.concurrent.CompletableFuture;import java.util.concurrent.ExecutorService;import java.util.concurrent.ThreadFactory;import java.util.concurrent.ThreadPoolExecutor;import java.util.concurrent.TimeUnit;import org.springframework.beans.factory.annotation.Qualifier;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.stereotype.Service;import org.springframework.web.client.RestClient;@Configurationclass PricingIoConfig { /** Blocking calls to the pricing service get their own bounded pool. */ @Bean(destroyMethod = "shutdown") ExecutorService pricingIoExecutor() { ThreadFactory threads = Thread.ofPlatform().name("pricing-io-", 1).factory(); return new ThreadPoolExecutor( 16, 16, 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(500), threads, new ThreadPoolExecutor.CallerRunsPolicy()); }}@Servicepublic class CatalogExportService { private final RestClient pricing; private final ExecutorService pricingIo; public CatalogExportService(RestClient.Builder builder, @Qualifier("pricingIoExecutor") ExecutorService pricingIo) { this.pricing = builder.baseUrl("http://pricing.internal").build(); this.pricingIo = pricingIo; } public List<PricedSku> export(List<String> skus) { List<CompletableFuture<PricedSku>> calls = skus.stream() // sequential: it only submits .map(sku -> CompletableFuture.supplyAsync( () -> new PricedSku(sku, fetchPrice(sku)), pricingIo)) .toList(); return calls.stream().map(CompletableFuture::join).toList(); } private BigDecimal fetchPrice(String sku) { return pricing.get().uri("/prices/{sku}", sku).retrieve().body(BigDecimal.class); } public record PricedSku(String sku, BigDecimal price) { }}Why it is written this way
- 16 threads is a decision about the pricing service (how many concurrent calls it should receive from this export), not a consequence of the CPU count. 50,000 calls of 80 ms now take a little over 4 minutes on any pod size.
- The queue holds 500 tasks and the policy is
CallerRunsPolicy. When the queue is full the submitting thread makes the call itself, which slows down submission instead of piling 50,000 tasks into memory. See the lesson on rejection policies for what that costs. - The explicit executor argument on
supplyAsyncis the whole fix for the interference: the common pool is no longer involved, soQuoteServiceis unaffected. join()is called on the export's own thread after everything was submitted, never from inside a task onpricingIo. Blocking inside the pool on work queued to the same pool is the starvation shown in the CompletableFuture lesson.- Threads are named
pricing-io-N, so a dump shows at a glance how many are waiting on the pricing service. GiveQuoteServicean executor too iftax.estimateis not trivial. - Set a connect and a read timeout on the
RestClientrequest factory. A pool of 16 without timeouts is 16 threads that can hang for ever.
Trade-offs
- One more pool to size, name, monitor and shut down. Sixteen platform threads cost about 16 MB of reserved stack at the default 1 MB per thread on Linux x86-64, and most services end up with several such pools.
- The number 16 is now your responsibility. Too low and the export is slow; too high and it overloads the pricing service. It should come from the downstream limit, and it needs revisiting when that changes.
- The code is longer and less obvious than
parallelStream(). Exceptions arrive wrapped inCompletionExceptionatjoin(), and one failed SKU fails the export unless you handle it per future. - On Java 21 a virtual-thread-per-task executor with a
Semaphore(16)gives the same bound without a pool to size. It moves the question to the downstream limit, which is the subject of the next lesson. - Parallel streams remain the right tool for what they were designed for: CPU-bound work over data already in memory, with no blocking in the lambda.
Configuration
The common pool is configured only through system properties read when the pool is first used, so they belong on the command line or in JAVA_TOOL_OPTIONS, not in code that may run too late. Defaults are those of OpenJDK 21.
java.util.concurrent.ForkJoinPool.common.parallelismDefault Not stated in the API documentation. OpenJDK 21 uses available processors minus 1, minimum 1
- What it does
- The parallelism level of the common pool, a non-negative integer. Zero disables the use of threads in the common pool, and the documentation warns that unjoined tasks may then never be executed.
- When to change it
- Set it explicitly in containers so the value does not change silently with the CPU limit. Raising it to make blocking parallel streams faster treats the symptom: move the blocking work to its own executor instead.
java.util.concurrent.ForkJoinPool.common.maximumSparesDefault 256
- What it does
- The maximum number of extra threads the common pool may add to maintain its target parallelism while workers are blocked in joins or in a ManagedBlocker.
- When to change it
- Leave it alone unless a thread dump shows hundreds of common-pool workers, which means something blocks through
managedBlockat scale. Fix that code rather than the limit.
java.util.concurrent.ForkJoinPool.common.threadFactoryDefault none (a default factory whose threads are named ForkJoinPool.commonPool-worker-N)
- What it does
- Class name of a
ForkJoinPool.ForkJoinWorkerThreadFactory, loaded with the system class loader, used to create the common pool's workers. - When to change it
- Rarely needed. Some frameworks set it to control the context class loader of the workers. If you want different threads, a pool of your own is clearer.
java.util.concurrent.ForkJoinPool.common.exceptionHandlerDefault none
- What it does
- Class name of a
Thread.UncaughtExceptionHandlerfor common-pool workers that terminate because of an unrecoverable error in a task. - When to change it
- Exceptions thrown by tasks normally reach whoever joins them. Set a handler only to log the rare errors that kill a worker thread.
-XX:ActiveProcessorCount=<n>Default Not set: the JVM takes the number of available processors from the operating system
- What it does
- Overrides the number of CPUs the JVM uses to size its thread pools, including garbage collection threads and ForkJoinPool. It changes
Runtime.availableProcessors()and therefore the common pool. - When to change it
- Useful to reproduce a small container on a large machine, as this lesson's runs do. In production prefer an explicit common-pool parallelism over changing what the whole JVM believes about its CPUs.
ForkJoinPool constructor: parallelism, asyncMode, keepAliveTimeDefault parallelism = available processors, asyncMode = false, keepAliveTime = 60 seconds
- What it does
- Settings of a pool you create yourself. Parallelism is the target number of running threads, asyncMode switches a worker's own queue to first-in-first-out, and idle workers are terminated after the keep-alive time.
- When to change it
- Create your own pool for CPU-heavy fork/join work that must not compete with the common pool. Use asyncMode only for event-style tasks that are never joined.
Hands-on exercise
Measure the common pool you actually have
Run a 35-line probe on your own JDK 21 to see how the processor count sets the common pool's size, and how that size, not the work, decides how long blocking tasks in a parallel stream take.
Steps · 0 of 6 done
What you should see
On the lesson's machine the three commands printed parallelism 1 with 2 threads and 2,028 ms, parallelism 3 with 4 threads and 1,017 ms, and parallelism 7 with 8 threads and 533 ms. Your milliseconds will differ slightly; the thread counts and the step from about 2,000 to 1,000 to 500 ms should not. main appears in every thread list.
What can go wrong
Blocking I/O inside a parallel stream
- Symptom
- A batch job is slower in production than on a laptop, and unrelated asynchronous code in the same service gets slow while the job runs. CPU is low.
- Cause
- The lambda blocks common-pool workers on a remote call. The pool has processors minus one threads, cannot see the blocking and does not compensate for it.
- Fix
- Run blocking calls on a dedicated bounded executor with
CompletableFuture.supplyAsync(task, executor), or on virtual threads behind a semaphore. Keep parallel streams for CPU-bound work on in-memory data.
Async methods without an executor argument
- Symptom
supplyAsyncstages are delayed by seconds although their own work takes microseconds. On a 1 or 2 CPU pod the thread count of the process climbs under load.- Cause
- Without an executor the task goes to the common pool, where it waits behind whatever else is there. When the common pool's parallelism is below two, each task gets a brand new thread instead, with no limit.
- Fix
- Pass an executor to every
...Asynccall in service code. Make it a rule in code review: aCompletableFutureasync call with one argument is a finding.
A threshold that is far too small
- Symptom
- The parallel version of a computation is slower than the loop it replaced, and a profile shows time in
ForkJoinTask.fork,ForkJoinPoolinternals and allocation. - Cause
- The task splits down to a few elements, so most of the time goes into creating, queueing and joining millions of tiny tasks. In this lesson's run a threshold of 4 was about 20 times slower than no splitting.
- Fix
- Stop splitting while a leaf still does thousands of basic steps, then measure two or three thresholds an order of magnitude apart and keep the fastest.
Tuning common.parallelism to fix slow blocking streams
- Symptom
- Someone sets the common pool to 64 threads. The export gets faster, and CPU-bound parallel streams elsewhere in the service get slower and noisier.
- Cause
- The common pool now runs up to 64 CPU-bound tasks on a few cores when the stream is a real computation, which adds context switching. The blocking code is still sharing a pool with everything else.
- Fix
- Leave the common pool sized for CPU work and give the blocking workload its own executor with a size derived from the downstream service.
Calling join on both halves after forking both
- Symptom
- A RecursiveTask scales worse than expected and the pool creates more threads than its parallelism.
- Cause
- Forking both subtasks and then joining leaves the current worker with nothing to do but wait at every level, so the pool compensates with spare threads.
- Fix
- Fork one half, compute the other in the current thread, then join. Or call
invokeAll(left, right).
How to troubleshoot
Async stages or parallel streams are slow while CPU is low
Check
jcmd <pid> Thread.print | grep -A 14 'ForkJoinPool.commonPool-worker'
- How to read it
- If every worker shows the same blocking frame (
SocketDispatcher.read0, a JDBC driver,Thread.sleep, a monitor), the common pool is starved. The first application frame below it names the code that must move to its own executor.
You need to know whether a worker is computing or waiting
Check
The `cpu=` and `elapsed=` fields on the thread's first line in `jcmd <pid> Thread.print`, compared between two dumps a few seconds apart
- How to read it
- A blocked socket read is reported as
RUNNABLE. Ifcpu=barely moves between dumps whileelapsed=grows, the thread is waiting, whatever its state says.
Behaviour differs between a laptop and a container
Check
Log `Runtime.getRuntime().availableProcessors()` and `ForkJoinPool.getCommonPoolParallelism()` at start-up, or run `jcmd <pid> VM.system_properties | grep ForkJoinPool` to see whether a property overrides it
- How to read it
- A parallelism of 1 means parallel streams run on two threads and executor-less async calls create a new thread per task. No output from the grep means the default (processors minus one) is in effect.
Suspected backlog in a ForkJoinPool you own
Check
Log `pool.toString()`, or read the Micrometer gauges `executor.queued`, `executor.active` and `executor.running` registered by `ExecutorServiceMetrics`
- How to read it
toString()prints parallelism, size, active, running, steals, tasks and submissions.submissionsgrowing means callers are queueing.activeequal to the size withrunningnear zero means the workers are blocked rather than computing.
Hundreds of ForkJoinPool.commonPool-worker threads in a dump
Check
jcmd <pid> Thread.print | grep -c 'ForkJoinPool.commonPool-worker'
- How to read it
- A count far above the parallelism means the pool is adding spare threads for workers blocked in
joinor inForkJoinPool.managedBlock. Find the common blocking frame; the cap iscommon.maximumSpares(256).
Slow remote calls need to be attributed to a thread pool after the fact
Check
jfr print --events jdk.SocketRead recording.jfr
- How to read it
- Each event carries the duration, the remote address, the thread name and the stack. Socket reads over the 20 ms default threshold on
ForkJoinPool.commonPool-worker-Nare blocking I/O on the common pool.
Key takeaways
- A ForkJoinPool gives each worker its own deque. The owner takes the newest task, an idle worker steals the oldest and largest one, and
joinhelps with other work instead of just blocking. - It is built for CPU-bound work that splits. It has no queue limit and no rejection, and it cannot see a worker blocked in I/O.
- The common pool has processors minus one workers (at least one) in OpenJDK 21 and is shared by parallel streams, executor-less
CompletableFutureasync calls,Arrays.parallelSortand library code. - One blocking lambda in a parallel stream removes workers from that shared pool. The slowness shows up in unrelated code, with low CPU and no log line.
- The proof is a thread dump:
ForkJoinPool.commonPool-worker-Nthreads all in the same I/O frame, reported as RUNNABLE, with almost no CPU time. - Fix it by moving blocking work to an executor you sized from the downstream limit.
ManagedBlockerand a larger common pool only hide the problem. - Pick a fork/join threshold by measuring. Leaves that are too small can make the parallel version many times slower than a loop.
Practical check
Small scenarios, one decision each. Pick what you would do, then read why.
Scenario 1 of 4
A service runs in a pod with a CPU limit of 2. A report uses orders.parallelStream().map(o -> invoiceClient.fetch(o.id())) over 400 orders, and each fetch takes about 250 ms. On a developer's 16-core laptop the report took about 7 seconds.
Roughly how long will the report take in the pod, and why?
Scenario 2 of 4
p99 latency of an endpoint that calls CompletableFuture.supplyAsync(() -> cache.lookup(key)) rises from 5 ms to 900 ms every night at 02:00. Process CPU is at 15%. A thread dump shows 3 threads named ForkJoinPool.commonPool-worker-N, all RUNNABLE with SocketDispatcher.read0 on top and ReportExporter.upload below it.
What is the most likely cause?
Scenario 3 of 4
A RecursiveTask sums an array of 20 million longs on a pool of 2. With a threshold of 1,000,000 it takes 20 ms. A colleague lowers the threshold to 4 'so that both cores always have something to steal', and the run now takes about 750 ms.
What explains the slowdown?
Scenario 4 of 4
A team finds that a parallel stream doing blocking HTTP calls starves the common pool. Three fixes are proposed for the export: set common.parallelism=64, wrap each call in ForkJoinPool.managedBlock, or submit the calls to a dedicated pool of 16 threads with a bounded queue.
Which fix do you choose for service code, and what is the main reason?
References
References: ForkJoinPool (Java SE 21 API): work stealing, common pool properties, managedBlock ↗ · ForkJoinTask (Java SE 21 API): fork, join, task size rule of thumb, blocking tasks ↗ · CompletableFuture (Java SE 21 API): default executor for async methods ↗ · ForkJoinPool.ManagedBlocker (Java SE 21 API) ↗ · Arrays (Java SE 21 API): parallelSort uses the ForkJoin common pool ↗ · ConcurrentHashMap (Java SE 21 API): bulk operations and the common pool ↗ · OpenJDK 21 source, ForkJoinPool.java: common pool default parallelism and queue design notes ↗ · JEP 444: Virtual Threads (states that parallel streams use the common pool, in LIFO mode) ↗ · The java command (JDK 21): -XX:ActiveProcessorCount ↗ · Micrometer ExecutorServiceMetrics source: meter names for ForkJoinPool ↗ · Report a problem