Java Parallel Streams
What a Parallel Stream Is
A normal (sequential) stream processes elements one after another on the thread that runs the terminal operation. A parallel stream splits the source into chunks, processes the chunks at the same time on several threads, and then combines the partial results. On a multi-core machine, CPU-heavy work over a large data set can finish several times faster.
The point of the Streams API design is that you don't write any threading code yourself: the same pipeline becomes parallel with one call.
list.stream() // sequential
list.parallelStream() // parallel, from a collection
stream.parallel() // turn an existing stream parallel
stream.sequential() // turn it back
stream.isParallel() // check
parallel() and sequential() set a flag on the whole pipeline, not on individual steps. If you call both, the last call wins — you cannot run filter in parallel and map sequentially in one pipeline.
A First Example
import java.util.*;
import java.util.stream.*;
public class P1 {
public static void main(String[] args) {
List<Integer> nums = IntStream.rangeClosed(1, 8).boxed().toList();
System.out.println("sequential: " + nums.stream().map(n -> n * n).toList());
System.out.println("parallel: " + nums.parallelStream().map(n -> n * n).toList());
System.out.println("isParallel: " + nums.stream().parallel().isParallel());
System.out.print("forEach: ");
nums.parallelStream().forEach(n -> System.out.print(n + " "));
System.out.print("\nforEachOrdered: ");
nums.parallelStream().forEachOrdered(n -> System.out.print(n + " "));
System.out.println();
System.out.println("findFirst: " + nums.parallelStream().filter(n -> n > 3).findFirst().get());
System.out.println("findAny: " + nums.parallelStream().filter(n -> n > 3).findAny().get());
System.out.println("sum: " + nums.parallelStream().mapToInt(Integer::intValue).sum());
}
}
Output from one run (the forEach line and the findAny result can change from run to run):
sequential: [1, 4, 9, 16, 25, 36, 49, 64]
parallel: [1, 4, 9, 16, 25, 36, 49, 64]
isParallel: true
forEach: 3 4 1 2 7 8 5 6
forEachOrdered: 1 2 3 4 5 6 7 8
findFirst: 4
findAny: 5
sum: 36
This shows the most important rule about ordering:
- Results keep the encounter order.
toList(),collect,reduceandfindFirston a parallel stream give the same answer as sequentially — the list is[1, 4, 9, ...]in order, even though the squares were computed on different threads. The framework puts the partial results back together in the right order. - Side effects don't.
forEachruns the action on whichever thread processes the element, as soon as it's processed, so the printing order is unpredictable.forEachOrderedrespects the encounter order, but it has to wait for earlier elements, which removes much of the benefit of running in parallel. findAnyreturns whichever matching element some thread finds first — any element greater than 3 is a correct answer. It's cheaper thanfindFirstin parallel because no thread has to wait for earlier chunks. Use it when you don't care which match you get.
How It Works: Splitting and the Common Pool
Two pieces of machinery run a parallel stream:
- Splitting. Every stream source provides a
Spliterator(a "splittable iterator") that can divide its elements into two halves, and those halves into halves, until the chunks are small. Each chunk is processed as an ordinary sequential pipeline, and the results are merged in pairs on the way back — the same divide-and-conquer pattern used by merge sort. - Threads. The chunks run as tasks in the common
ForkJoinPool, a JVM-wide thread pool shared by all parallel streams (and byCompletableFutureasync methods without an executor). Its default size is number of cores − 1; the thread that calls the terminal operation also takes chunks, so all cores are used.
import java.util.*;
import java.util.concurrent.*;
import java.util.stream.*;
public class Pool {
static String check(int id) {
try { Thread.sleep(100); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
return id + "@" + Thread.currentThread().getName().replace("ForkJoinPool.commonPool-", "");
}
public static void main(String[] args) {
System.out.println("cores: " + Runtime.getRuntime().availableProcessors()
+ ", common pool parallelism: " + ForkJoinPool.commonPool().getParallelism());
List<Integer> ids = IntStream.rangeClosed(1, 8).boxed().toList();
long t0 = System.nanoTime();
ids.stream().map(Pool::check).toList();
long seq = (System.nanoTime() - t0) / 1_000_000;
t0 = System.nanoTime();
List<String> r = ids.parallelStream().map(Pool::check).toList();
long par = (System.nanoTime() - t0) / 1_000_000;
System.out.println(r);
System.out.printf("sequential ~%d ms, parallel ~%d ms%n", Math.round(seq / 100.0) * 100, Math.round(par / 100.0) * 100);
}
}
Output on a 2-core machine, first with the default settings, then with java -Djava.util.concurrent.ForkJoinPool.common.parallelism=3 Pool:
cores: 2, common pool parallelism: 1
[1@worker-1, 2@worker-1, 3@worker-1, 4@worker-1, 5@main, 6@main, 7@main, 8@main]
sequential ~800 ms, parallel ~400 ms
cores: 2, common pool parallelism: 3
[1@worker-3, 2@worker-3, 3@worker-1, 4@worker-1, 5@worker-2, 6@worker-2, 7@main, 8@main]
sequential ~800 ms, parallel ~200 ms
- With 2 cores, the pool has 1 worker; together with
main, two threads split the 8 tasks, so 800 ms becomes about 400 ms. - The system property
java.util.concurrent.ForkJoinPool.common.parallelismchanges the pool size for the whole JVM. Here four threads run, so the time drops to about 200 ms — but only because each task sleeps. For CPU-bound work, more threads than cores gives no extra speed. - The output list is still in order 1 to 8, whichever thread processed each element.
Warning: this example uses sleep only to make the threads visible. Real blocking work — HTTP calls, database queries, file reads — does not belong in parallel streams: the blocked threads are the common pool's few workers, so every other parallel stream and async task in the JVM waits too. Use an ExecutorService (or virtual threads, Java 21+) for I/O; the Multithreading lessons cover both.
Shared Mutable State: The Classic Bug
Lambdas in a parallel stream run on several threads at once. If they modify a shared object that isn't thread-safe, updates are lost or the object is corrupted.
import java.util.*;
import java.util.stream.*;
public class Race {
public static void main(String[] args) {
for (int run = 1; run <= 3; run++) {
List<Integer> evens = new ArrayList<>();
try {
IntStream.range(0, 100_000).parallel().filter(n -> n % 2 == 0).forEach(evens::add);
System.out.println("run " + run + ": shared ArrayList size " + evens.size());
} catch (ArrayIndexOutOfBoundsException e) {
System.out.println("run " + run + ": ArrayIndexOutOfBoundsException");
}
}
List<Integer> safe = IntStream.range(0, 100_000).parallel().filter(n -> n % 2 == 0).boxed().toList();
System.out.println("toList size " + safe.size() + ", first " + safe.subList(0, 5));
int[] counter = {0};
IntStream.range(0, 100_000).parallel().forEach(n -> counter[0]++);
System.out.println("shared counter: " + counter[0]);
System.out.println("count(): " + IntStream.range(0, 100_000).parallel().count());
}
}
Output from one run with four threads (every run is different; sometimes a run even looks correct):
run 1: shared ArrayList size 38126
run 2: shared ArrayList size 34743
run 3: ArrayIndexOutOfBoundsException
toList size 50000, first [0, 2, 4, 6, 8]
shared counter: 89996
count(): 100000
There should be 50,000 even numbers, but:
ArrayList.addreads the current size, stores the element and increments the size. Two threads that do this at the same moment can write into the same slot (one element is lost) or both trigger a resize at once (theArrayIndexOutOfBoundsException).counter[0]++is a read-modify-write of three steps, not one atomic action, so increments are lost.- The danger is that the result is sometimes correct, so the bug can pass testing and fail in production.
The fix is not to add synchronized everywhere (that makes threads wait for each other and removes the speedup), but to let the stream build the result: toList(), collect(...), count(), sum(), reduce(...). These operations give each thread its own partial result and merge them safely. As the Stream Reduce lesson explained, a reduce must use an associative function with a true identity value for this to work.
Lambdas in a parallel stream should therefore be stateless (their result depends only on the element) and non-interfering (they don't modify the stream's source).
When Parallel Streams Help
Parallelism has a cost: splitting the source, scheduling tasks, and merging results. It pays off only when the work saved is larger than that overhead.
import java.util.*;
import java.util.function.*;
import java.util.stream.*;
public class Bench {
static boolean isPrime(int n) {
if (n < 2) return false;
for (int d = 2; (long) d * d <= n; d++) if (n % d == 0) return false;
return true;
}
static void time(String label, Supplier<Object> task) {
for (int i = 0; i < 3; i++) task.get(); // warm-up runs
long best = Long.MAX_VALUE; Object result = null;
for (int i = 0; i < 5; i++) {
long t0 = System.nanoTime();
result = task.get();
best = Math.min(best, System.nanoTime() - t0);
}
System.out.printf("%-27s %12s %7.1f ms%n", label, result, best / 1e6);
}
public static void main(String[] args) {
time("primes, sequential", () -> IntStream.range(0, 3_000_000).filter(Bench::isPrime).count());
time("primes, parallel", () -> IntStream.range(0, 3_000_000).parallel().filter(Bench::isPrime).count());
List<Integer> array = IntStream.range(0, 1_000_000).boxed().collect(Collectors.toCollection(ArrayList::new));
List<Integer> linked = new LinkedList<>(array);
time("small work, sequential", () -> array.stream().mapToLong(i -> i).sum());
time("small work, parallel", () -> array.parallelStream().mapToLong(i -> i).sum());
time("LinkedList, sequential", () -> linked.stream().mapToLong(i -> i).sum());
time("LinkedList, parallel", () -> linked.parallelStream().mapToLong(i -> i).sum());
time("Stream.iterate, sequential", () -> Stream.iterate(0, i -> i + 1).limit(1_000_000).mapToLong(i -> i).sum());
time("Stream.iterate, parallel", () -> Stream.iterate(0, i -> i + 1).limit(1_000_000).parallel().mapToLong(i -> i).sum());
}
}
Output from one run on a 2-core machine (absolute times depend on the hardware; the relationships are what matter):
primes, sequential 216816 694.7 ms
primes, parallel 216816 436.1 ms
small work, sequential 499999500000 1.0 ms
small work, parallel 499999500000 0.5 ms
LinkedList, sequential 499999500000 3.0 ms
LinkedList, parallel 499999500000 11.9 ms
Stream.iterate, sequential 499999500000 7.2 ms
Stream.iterate, parallel 499999500000 37.1 ms
- Primality testing is CPU-heavy per element, and an
IntStream.rangesplits perfectly, so two cores give a clear speedup (less than 2× because the halves of the range don't contain equal amounts of work and there is merge overhead). - Small work — adding a million numbers — takes a millisecond either way. Saving half a millisecond is rarely worth making code parallel.
LinkedListcan't be split without walking through the nodes one by one, andStream.iterategenerates each element from the previous one, so it is inherently sequential. Parallel versions of both are several times slower than sequential ones.- The benchmark warms up the JIT compiler before measuring and takes the best of five runs; single measurements of short code are unreliable. For serious measurements use a benchmarking tool such as JMH.
A useful rule of thumb from the JDK developers is the NQ model: parallelism pays off when N (number of elements) × Q (work per element) is large — the commonly quoted threshold is N × Q above roughly 10,000, where Q is measured in simple operations such as an addition. Many elements with trivial work, or few elements, aren't worth it.
| Factor | Good for parallel | Poor for parallel |
|---|---|---|
| Source | ArrayList, arrays, IntStream.range, HashSet/HashMap | LinkedList, Stream.iterate, BufferedReader.lines(), I/O-backed streams |
| Work per element | CPU-heavy (calculations, parsing, image processing) | Trivial (adding, simple field access) |
| Data size | Large (tens of thousands of elements or more, depending on the work) | Small |
| Operations | map, filter, reduce, sum, collect, findAny | limit, skip, findFirst, forEachOrdered, sorted on ordered streams |
| Blocking | None | I/O, locks, sleep |
| Environment | Spare cores on the machine | Busy server already using every core for requests |
Operations such as limit, skip and findFirst depend on encounter order, so in parallel they must coordinate chunks. If order doesn't matter, calling unordered() on the stream lets them work more cheaply.
The last row matters in web applications: a server handling many requests at once already keeps all cores busy. Making each request use a parallel stream doesn't create more CPU time — it only adds overhead and makes the requests compete for the shared common pool. Parallel streams are most useful in batch jobs, data processing and command-line tools.
Practical Example: Parallel Sales Report
A nightly job summarises two million sales by category. The work is a CPU-bound aggregation over a large ArrayList — a good fit for a parallel stream — and the result must be identical to the sequential version.
import java.util.*;
import java.util.concurrent.*;
import java.util.stream.*;
public class Sales {
record Sale(int id, String category, long paise, double weightKg) { }
static final String[] CATS = {"Books", "Electronics", "Grocery", "Toys"};
static Sale generate(int id) {
SplittableRandom r = new SplittableRandom(id);
return new Sale(id, CATS[r.nextInt(CATS.length)], 10_000 + r.nextLong(5_000_000), r.nextDouble(0.1, 20));
}
static Map<String, LongSummaryStatistics> report(Stream<Sale> sales) {
return sales.collect(Collectors.groupingBy(Sale::category, TreeMap::new,
Collectors.summarizingLong(Sale::paise)));
}
public static void main(String[] args) throws Exception {
List<Sale> sales = IntStream.range(0, 2_000_000).parallel().mapToObj(Sales::generate).toList();
Map<String, LongSummaryStatistics> seq = report(sales.stream());
Map<String, LongSummaryStatistics> par = report(sales.parallelStream());
seq.forEach((cat, s) -> System.out.printf("%-12s %,9d sales revenue Rs %,15.2f max Rs %,10.2f%n",
cat, s.getCount(), s.getSum() / 100.0, s.getMax() / 100.0));
System.out.println("same result: " + seq.toString().equals(par.toString()));
double wSeq = sales.stream().mapToDouble(Sale::weightKg).reduce(0, Double::sum);
double wPar = sales.parallelStream().mapToDouble(Sale::weightKg).reduce(0, Double::sum);
System.out.println("weight sequential " + wSeq);
System.out.println("weight parallel " + wPar);
System.out.println("weight sum() par " + sales.parallelStream().mapToDouble(Sale::weightKg).sum());
ForkJoinPool pool = new ForkJoinPool(2);
try {
Map<String, LongSummaryStatistics> limited = pool.submit(() -> report(sales.parallelStream())).get();
System.out.println("custom pool, same result: " + limited.toString().equals(seq.toString()));
} finally {
pool.shutdown();
}
}
}
Output from one run (the weight parallel value can differ in the last digits between runs):
Books 500,305 sales revenue Rs 12,574,272,790.47 max Rs 50,099.92
Electronics 500,321 sales revenue Rs 12,574,936,713.90 max Rs 50,099.93
Grocery 500,262 sales revenue Rs 12,548,602,643.57 max Rs 50,099.95
Toys 499,112 sales revenue Rs 12,515,945,103.95 max Rs 50,099.92
same result: true
weight sequential 2.009511946889864E7
weight parallel 2.009511946889913E7
weight sum() par 2.0095119468899146E7
custom pool, same result: true
How it works:
- Deterministic test data in parallel. Each sale is generated from its own
SplittableRandomseeded with its id, so the data doesn't depend on which thread created it. Sharing oneRandomacross threads would be both slower (threads compete for it) and non-reproducible. reportgroups by category into aTreeMap(sorted output) and computes count, sum, minimum, average and maximum per category withsummarizingLong. In parallel, each thread builds its own partial map, andgroupingBy's combiner merges them — no shared mutable state, andsame result: trueconfirms it.- Money as
longpaise. Integer addition is exact and associative, so the sums are the same in any order. The amounts are only converted to rupees for display. - The floating-point catch. Weights are
doubles, and floating-point addition is not exactly associative:(a + b) + ccan differ froma + (b + c)in the last bits because of rounding. A parallel sum adds in a different grouping, so the result differs slightly from the sequential one.DoubleStream.sum()uses a compensated summation algorithm that reduces the rounding error, but its result can still vary in the last digits. For exact totals, use integer units orBigDecimal. - Limiting parallelism with a custom pool. Submitting the stream to your own
ForkJoinPool(2)makes it run on that pool's threads instead of the common pool — useful to stop one heavy job from occupying the whole common pool. This relies on JDK implementation behaviour rather than a documented guarantee, but it has worked this way since Java 8 and is widely used. Always shut the pool down afterwards.
groupingByConcurrent and toConcurrentMap are alternative collectors for parallel streams that write into a single ConcurrentHashMap instead of merging per-thread maps. They can be faster for large unordered results, but they don't preserve encounter order, and with a few keys (like the four categories here) all threads compete to update the same entries.