peek, forEach and side effects

For this lesson, we'll focus on the stream-operation angle: when peek runs, why forEach is not a loop with a break, how ordering changes in parallel streams, and why mutating outside state from a pipeline is usually the bug. We covered laziness, flags, and the count() surprise in How a stream pipeline executes, so here we'll use that model instead of rebuilding it.

01Picture it first: an inspection window and an exit bin

Picture a warehouse conveyor. A small glass window lets you inspect packages while they pass, but it does not pull packages by itself. The exit bin at the end is what makes the belt move.

That is the relationship between peek and forEach. peek observes traversal; forEach starts traversal. If the terminal operation does not need to open the belt, or it stops after three packages, your inspection window sees only that much.

Fig. 1

A stream conveyor shows peek as an inspection window that only sees traversed elements and forEach as the terminal exit bin that consumes them

Notice the control point. The terminal operation decides how much source data is requested. peek has no promise that every source element will pass its window.

02peek under the hood: useful, but not load-bearing

The JDK describes peek as mainly existing to support debugging. I treat that wording seriously in code review. If removing a peek changes the business result, the pipeline is carrying logic in the wrong place.

import java.util.List;

final class PeekCountDemo {
    public static void main(String[] args) {
        long count = List.of("new", "paid", "shipped").stream()
                .peek(status -> System.out.println("peek " + status))
                .count();

        System.out.println("count " + count);
    }
}

On Java 21, the output is:

count 3

No peek lines print. A List stream is SIZED, and peek does not change the number of elements, so count() can answer from metadata. Since Java 9, this optimization is visible to you when peek is used for logging or mutation.

Short-circuiting is the other common surprise.

import java.util.List;

final class PeekShortCircuitDemo {
    public static void main(String[] args) {
        boolean hasPaid = List.of("new", "retry", "paid", "shipped").stream()
                .peek(status -> System.out.println("seen " + status))
                .anyMatch("paid"::equals);

        System.out.println("has paid " + hasPaid);
    }
}

The output is:

seen new
seen retry
seen paid
has paid true

shipped is not visited because anyMatch already knows the answer. This is not a bug in peek. It is the stream model doing exactly what pipeline execution says it can do.

Notice three things:

• peek is intermediate and lazy. It needs a terminal operation.
• peek observes elements that are actually traversed, not necessarily every element in the source.
• If the action is required, put it in a terminal operation or, better, produce data and handle the effect outside the stream.