Skip to content

Path 4 · lesson 4 of 5

Advanced26 minJava 21 (OpenJDK 21.0.13) · Spring Boot 3.5 (RestClient needs Spring Boot 3.2 or later)

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.

ThreadPoolExecutorForkJoinPool
QueuesOne shared BlockingQueueOne deque per worker, plus shared submission queues for callers outside the pool
A task that waits for its subtasksBlocks its thread. On a small pool this is the starvation from the CompletableFuture lessonjoin() runs other pending tasks while it waits, and the pool may add a spare thread
Meant forIndependent tasks, including blocking I/O, with a size and queue you chooseCPU-bound work that divides recursively: sorting, aggregation, parallel streams
ThreadsCore and maximum size, your thread factoryA target parallelism. Workers are daemon threads and are reclaimed when idle
When fullQueue fills, then the rejection policy runsNo bound on queued tasks. It rejects only when shut down or out of internal resources
The last row matters in production: a ForkJoinPool never pushes back on submitters.

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
The lines starting with $ are the commands; the rest is program output. With 2 processors the common pool has one worker, so 8 blocking tasks of 500 ms run two at a time (the worker and 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:

APIWhat 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 argumentPerformed 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.parallelSetAllThe 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 workerUses 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 output
availableProcessors=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]
Line 1: 2 processors give a common pool parallelism of 1. Line 2: the unrelated 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.submit or pool.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 output
availableProcessors=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
Read the threshold column against the time. One leaf (no splitting) is the single-threaded cost. 32 leaves of a million elements each is the fastest: enough pieces for the second worker to steal. At a threshold of 100 there are 262,144 tasks and the run is several times slower; at 4 there are over 7 million tasks and it is about 20 times slower than not splitting at all. The speed-up from two workers is modest because summing an array is limited by memory bandwidth, and this machine was running other JVMs at the same time, so treat the absolute milliseconds as noisy. The steal count stays in single digits: stealing happens near the top of the tree, where tasks are big.

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 output
availableProcessors=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]
Parallelism is still 3, but the pool grew to 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"]
One common pool serves several unrelated callers. Each worker has its own deque and steals from the others when idle.
  • 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
One fork/join computation on two workers: the owner takes the newest task, the thief takes the oldest and largest.
  1. 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.
  2. The first join costs almost nothing: the task was never stolen, so the worker pops it from its own deque and runs it as an ordinary call.
  3. The second join is 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.
  4. The caller thread blocks in invoke for 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 output
availableProcessors=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]
Line 3: 8 calls of 500 ms took 1,087 ms, that is two rounds on 4 threads (3 workers plus 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)
Four things to read. (1) The name 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 seeCommon-pool starvationCPU saturation
Process CPULowAt the limit
Worker stacksAll workers in the same blocking call: socket read, JDBC, Thread.sleep, a lockWorkers in your computation, different frames in each dump
cpu= against elapsed= on worker threadsMilliseconds of CPU over seconds or minutes of lifeCPU time close to elapsed time
VictimsThreads WAITING in CompletableFuture.join or get, or in a stream terminal operationThe same, but workers are busy, not parked
FixMove the blocking work off the common poolLess work, more cores, or a higher threshold
  1. Count the workers and compare with the parallelism: jcmd <pid> Thread.print | grep -c 'ForkJoinPool.commonPool-worker'.
  2. 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.
  3. 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.
  4. 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.
  5. 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 on ForkJoinPool.commonPool-worker-N stand 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.

CommonPoolProbe.javaJava
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.sleep is 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.

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

src/main/java/com/example/catalog/CatalogExportService.javaJava
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.
  • fetchPrice blocks 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.
  • QuoteService never mentions the export. supplyAsync without an executor argument is the only link, and it is invisible at the call site.
  • TaxCalculator and Cart are 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 fetchPrice almost all the time. A supplyAsync from QuoteService waits 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 showing ForkJoinPool.commonPool-worker-N threads 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

src/main/java/com/example/catalog/CatalogExportService.javaJava
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 supplyAsync is the whole fix for the interference: the common pool is no longer involved, so QuoteService is unaffected.
  • join() is called on the export's own thread after everything was submitted, never from inside a task on pricingIo. 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. Give QuoteService an executor too if tax.estimate is not trivial.
  • Set a connect and a read timeout on the RestClient request 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 in CompletionException at join(), 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 managedBlock at 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.UncaughtExceptionHandler for 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 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
supplyAsync stages 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 ...Async call in service code. Make it a rule in code review: a CompletableFuture async 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, ForkJoinPool internals 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. If cpu= barely moves between dumps while elapsed= 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. submissions growing means callers are queueing. active equal to the size with running near 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 join or in ForkJoinPool.managedBlock. Find the common blocking frame; the cap is common.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-N are 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 join helps 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 CompletableFuture async calls, Arrays.parallelSort and 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-N threads 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. ManagedBlocker and 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