Java Reference ยท Streams and Functional
Stream laziness and short-circuiting
How Java stream pipelines execute: intermediate operations are lazy, the terminal operation pulls elements one by one, and short-circuiting stops early.
A Java stream pipeline has three parts: a source, zero or more intermediate operations (filter, map, sorted, limit...) and one terminal operation (collect, forEach, count, findFirst...). Building the pipeline does nothing. No element is touched, and no lambda runs, until the terminal operation starts the work.
Because of this laziness, the stream does not process the data one operation at a time. Instead each element travels through the whole pipeline before the next one starts, and the pipeline can stop as soon as the answer is known. This is why infinite streams are possible, and why the order in which you write operations affects how much work is done.
This page explains the idea. Each individual method has its own reference page.
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
How execution works
- Intermediate operations return a new stream and only record what to do. They are either stateless (
filter,map,peek,flatMap,mapMulti), where each element is handled alone, or stateful (sorted,distinct,limit,skip), which may need to remember or collect elements. - The terminal operation drives everything. It pulls elements from the source one at a time (loop fusion), so in the first example you see
source 2,filter 2,map 2together beforesource 3appears. - Short-circuiting operations can end the work early. Intermediate:
limit,takeWhile. Terminal:findFirst,findAny,anyMatch,allMatch,noneMatch. They are what makes an infinite source usable. - Barriers:
sorted()cannot emit anything until the source is exhausted. It still respects a laterlimit, but must read everything first, so it must not be applied to an infinite stream.
Usage notes
- A stream can be consumed once. Reusing it throws
IllegalStateExceptionwith the message "stream has already been operated upon or closed". Create a new stream, or keep aSupplier<Stream<T>>. - Order matters for cost, not results. Put
filterandlimitearly to shrink the data before expensivemapcalls. Movingsortedbeforefilteris wasted work. - Side effects in
peekandmapare fragile. The implementation may skip them when the result is known:count()on a sized source can answer without running amapat all (since Java 9). - Infinite sources (
Stream.iterate,Stream.generate) need a short-circuiting step or the terminal operation never ends. - Debugging: use
peek()to watch elements flow, as above, but remove it afterward. - Parallel streams relax the one-at-a-time order, but the laziness rules stay the same; see parallel streams.