how a stream pipeline runs

the picture

you know how list.stream().filter(...).map(...) looks like it loops over the list twice, once to filter and once to map? it doesn't. it loops once, and it might not even finish the loop.

think of a cook working a ticket rail. each order goes all the way from chopping to the plate before the next ticket is read. nobody chops onions for all fifty orders up front, and if the restaurant only needs two plates, the other forty-eight tickets are never touched.

one element at a time

this is the whole chapter. press play and follow one marble.

·

see? the pipeline is vertical, not horizontal. element 2 is filtered, mapped, counted by limit and stored in the list before element 3 leaves the source. and because limit(2) is satisfied after element 4, elements 5 through 8 never exist as far as the pipeline is concerned.

here's the real program the figure is drawn from, with print statements inside the lambdas so you can see the order:

import java.util.stream.*;
 
void main() {
    var result = Stream.of(1, 2, 3, 4, 5, 6, 7, 8)
            .filter(n -> { IO.println("filter " + n); return n % 2 == 0; })
            .map(n -> { IO.println("map    " + n); return n * 10; })
            .limit(2)
            .toList();
    IO.println(result);
}

filter 1
filter 2
map    2
filter 3
filter 4
map    4
[20, 40]

List<String> names = List.of("ada", "bob", "cy");
names.stream().map(s -> { IO.print(s.toUpperCase() + " "); return s; });
IO.println("done");

laziness, proven

the stages are built when you call filter and map. the lambdas only run when the terminal operation starts pulling:

import java.util.stream.*;
 
void main() {
    Stream<Integer> s = Stream.of(1, 2, 3)
            .filter(n -> { IO.println("filter " + n); return true; })
            .map(n -> { IO.println("map " + n); return n * 10; });
    IO.println("pipeline built");
    IO.println(s.toList());
}

pipeline built
filter 1
map 1
filter 2
map 2
filter 3
map 3
[10, 20, 30]

laziness isn't just a performance trick. it's what makes infinite sources usable. Stream.iterate(1, n -> n * 2) never ends, and this still finishes instantly, because findFirst stops pulling as soon as it has an answer:

import java.util.stream.*;
 
void main() {
    int first = Stream.iterate(1, n -> n * 2)
            .filter(n -> n > 100)
            .findFirst()
            .orElseThrow();
    IO.println(first);
}

128

operations that can finish without seeing every element are called short-circuiting: limit, takeWhile, findFirst, findAny, anyMatch, allMatch, noneMatch. put one of those in front of an infinite source and you're fine. put sorted() or count() there instead and it runs forever.

what's actually in memory

each intermediate operation returns a brand new stage object that points back at the one before it. here's the pipeline from the figure, after .limit(2) and before .toList(), with the real class names from jdk 25:

when toList() runs on d, it walks that chain backwards and wraps one sink inside another: the list's sink, inside limit's, inside map's, inside filter's. then it feeds the source's elements into the outermost sink, one by one. filter's sink calls map's sink only if the predicate passed, map's sink calls limit's, and so on. that nesting is why each element goes all the way down before the next one starts. limit stops the whole thing by answering "yes" when the source asks cancellationRequested().