skip to content

How does a Java Gatherer work: what do its four functions do, how does it short-circuit, and how do the built-in gatherers use them?

level: middleimportance: should knowfreq 32%

answer

  1. four functions, only one required
  2. state, element, downstream
  3. two booleans: push and integrate
  4. greedy relays a stop, never starts one
  5. fold emits only from its finisher

basics

~20 s

A Gatherer's initializer creates state, its integrator handles each element and may push output, its combiner merges states for parallel runs, and its finisher acts at end of input. A false from the integrator stops input; the finisher still runs.

solid answer

~50 s

A `Gatherer<T, A, R>` is four functions. `initializer()` creates private state, one per partition in a partitioned run; `integrator()` handles each element given the state and a `Downstream`; `combiner()` merges two states and is what allows partitioned evaluation; `finisher()` runs at end of input and can still emit. Output goes through `Downstream.push`, which returns `false` once the next stage wants no more. The integrator's own return value means the same thing upstream: `false` treats the input as ended, and the finisher still runs. An `Integrator.ofGreedy` integrator promises never to start a stop and only relays one. In the JDK 27 source all the built-ins are sequential and greedy: `fold` pushes only from its finisher, `scan` pushes every value from its integrator, `windowFixed` pushes full windows and flushes the partial one in its finisher, and `mapConcurrent` runs tasks on virtual threads and pushes results in stream order from its integrator and finisher.

code

java · 42 lines
java
import java.util.ArrayList;
import java.util.List;
import java.util.function.Predicate;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

public class BatchUntil {

    static <T> Gatherer<T, ?, List<T>> batchUntil(Predicate<? super T> stop, int size) {
        return Gatherer.ofSequential(
            // Initializer: fresh state for each evaluation.
            () -> new ArrayList<T>(size),

            // Integrator: not greedy, because it can start a stop on its own.
            Gatherer.Integrator.of((batch, element, downstream) -> {
                if (stop.test(element)) {
                    return false; // Treat the input as ended.
                }
                batch.add(element);
                if (batch.size() < size) {
                    return true; // Keep buffering.
                }
                var full = new ArrayList<T>(batch);
                batch.clear();
                return downstream.push(full); // Relay whether downstream wants more.
            }),

            // Finisher: runs after a stop too, and flushes the partial batch.
            (batch, downstream) -> {
                if (!batch.isEmpty() && !downstream.isRejecting()) {
                    downstream.push(new ArrayList<T>(batch));
                }
            });
    }

    public static void main(String[] args) {
        List<List<Integer>> batches = Stream.iterate(1, i -> i + 1)
            .gather(batchUntil(i -> i > 7, 3))
            .toList();
        System.out.println(batches); // [[1, 2, 3], [4, 5, 6], [7]]
    }
}

go deeper

for a junior

Recall the four names with one line each: the initializer makes state, the integrator handles each element, the combiner merges states and the finisher runs at the end. Know that only the integrator is required.

for a middle

Explain the two booleans: push reports whether the next stage still accepts elements, and the integrator's return says whether it wants more input. Trace windowFixed through its integrator and finisher to show how the last partial window gets out.

for a senior

Show production judgment: mark an integrator greedy only when it never starts a stop, keep state out of fields, and check isRejecting before costly finisher work. For mapConcurrent, discuss bounded concurrency, ordered output and best-effort cancellation.

for a principal

Decide when a combiner is worth writing. The documentation warns that partitioned gathering may perform better or worse depending on integrator and combiner cost, so ask for measurement and keep order-dependent gatherers sequential.

## The four functions A **gatherer** is a custom intermediate stream operation, applied with `Stream.gather`. `Gatherer<T, A, R>` consumes elements of type `T`, keeps optional private state of type `A` and produces elements of type `R`. It is specified by four functions: | Function | Type | Role | Default, and what it signals | |---|---|---|---| | `initializer()` | `Supplier<A>` | Creates a new, potentially mutable state | `defaultInitializer()`: stateless, and invoking it is optional | | `integrator()` | `Integrator<A, T, R>` | Handles one element with the state and a `Downstream` | None: the only abstract method | | `combiner()` | `BinaryOperator<A>` | Merges two states into one for parallel evaluation | `defaultCombiner()`: sequential evaluation only | | `finisher()` | `BiConsumer<A, Downstream<? super R>>` | Performs a final action at end of input and can push more | `defaultFinisher()`: no end-of-stream hook, and invoking it is optional | The Javadoc says a gathering operation should produce a result equivalent to this order: 1. `initializer().get()` creates the state. 2. `integrator().integrate(state, element, downstream)` runs for each element, until the input ends or it returns `false`. 3. `finisher().accept(state, downstream)` runs once. Two rules bind an implementer. Each call to one of the four accessor methods must return a semantically identical result. The state and the `Downstream` must not be captured, retained or exposed to other threads beyond the call they were passed to. ## Two booleans drive short-circuiting **Short-circuiting** means ending the work before the input is exhausted. - **`Downstream.push(element)`** sends one element to the next stage and returns `true` if more can be sent. Once it returns `false`, no further elements are accepted and later calls also return `false`. - **`Integrator.integrate(...)`** returns whether it wants more input. `false` is treated as if no elements remained, so the **finisher still runs**. - **`Downstream.isRejecting()`** is a best-effort check that the next stage wants nothing more, useful before costly work. Many integrators end with `return downstream.push(x)`, which relays the next stage's refusal back up the pipeline. A **greedy integrator**, built with `Integrator.ofGreedy`, promises not to start a stop itself and may only relay one. The Javadoc lets the library skip inspecting its return value, and the package-private `GathererOp` leaves the short-circuit flag off for it, so traversal can avoid per-element cancellation checks when no other stage short-circuits. On JDK 27, a greedy integrator returning `false` on its own at the second of four elements receives all four through `toList` but only two with a later `limit`, while a plain one stops at two both ways. On a sequential stream a later `limit` still ends a greedy gatherer's pipeline, because that stop arrives from downstream. ## How the built-ins use them In the JDK 27 source, every built-in in `Gatherers` is created with `Gatherer.ofSequential` and `Integrator.ofGreedy`: none supplies a combiner and none starts a stop. | Gatherer | State from the initializer | Integrator | Finisher | |---|---|---|---| | `fold(initial, folder)` | The current value | Updates the value, pushes nothing, always returns `true` | Pushes the value | | `scan(initial, scanner)` | The current value | Pushes each new value and returns `push`'s result | None | | `windowFixed(n)` | An array of `n` slots and an index | Stores the element; when full, pushes a list and returns `push`'s result | Pushes a partial window unless downstream is rejecting | | `mapConcurrent(max, mapper)` | A private deque of in-flight tasks | Starts a task on a virtual thread, pushes finished tasks from the head, waits for the head at capacity | Waits for and pushes every remaining task in order | The consequences: - **`fold`** emits only from its finisher, so an empty stream yields the initial value, and an infinite source never finishes, even with a later `limit`. - **`scan`** does not emit the initial value: summing 1, 2, 3 from 0 gives 1, 3, 6, and an empty stream yields nothing. - **`windowFixed`** windows are specified as unmodifiable, and a size below 1 throws `IllegalArgumentException`. At JDK 27 they also accept nulls, which no API page promises. The Javadoc warns that a large window on a small stream may use excessive memory, because windows may be allocated eagerly. - **`mapConcurrent`** keeps stream order because it pushes only from the head of the deque, and at most `maxConcurrency` tasks are in flight. If downstream stops, or a failed task reaches the head of the deque, it calls `cancel(true)` on the remaining tasks and joins their threads, so a mapper that ignores interruption holds the pipeline until it returns. A failure therefore surfaces only after every earlier task has finished. The Javadoc calls cancellation after a downstream stop best-effort. A mapper's `RuntimeException` is rethrown as it is, and any other cause is wrapped in a `RuntimeException`. ## Parallel evaluation and the combiner - **With a combiner** (`Gatherer.of`), the library may partition the input. Each partition gets its own state and integrates until it is done or returns `false`, the states merge through the combiner, and the finisher runs on the joined state. If an earlier partition short-circuits, outputs and state later in the input are discarded. - **Without one** (`Gatherer.ofSequential`), the gatherer may only be evaluated sequentially. JEP 485 compares this mode to `parallel().forEachOrdered()`, with upstream and downstream operations still able to run in parallel; `GathererOp` pre-processes upstream in parallel only for a greedy integrator. The default combiner throws `UnsupportedOperationException` if invoked, and the library does not invoke it. - **Stateless shortcut.** `Gatherer.of(integrator)` is parallelizable because it uses a package-private combiner that returns `null`. - **Barrier.** On a parallel stream at JDK 27, a `gather` stage is evaluated whole before a later `limit` or `findFirst` takes effect. An infinite source runs out of memory, while a plain integrator returning `false` does stop it. The Javadoc notes that partitioned gathering may perform better or worse, depending on the relative cost of the integrator and the combiner.

  • What goes wrong if an integrator built with Integrator.ofGreedy returns false on its own?
    It breaks the marker's promise that no short-circuiting will be initiated, and the library need not inspect a greedy integrator's return value, so the result depends on the pipeline. On JDK 27, a greedy integrator returning `false` at the second of four elements receives all four through `toList`, `collect` and `forEach`, but only two with a later `limit` or `takeWhile`. A plain integrator stops at two every time. Use `Integrator.of` whenever the integrator can decide to stop.
  • Does the finisher run after a short-circuit, and can it still emit?
    It runs after the integrator returns `false` and after a later stage stops wanting elements. Whether it can emit depends on who stopped. When the gatherer stopped itself and the next stage still accepts, the pushes go through. When the next stage has refused, `push` returns `false` and the element goes nowhere, which is why `windowFixed` checks `isRejecting()` before building its last window.
  • How does mapConcurrent keep output in stream order while mapper calls finish out of order?
    Its private state holds a deque of tasks in arrival order, and it pushes only from the head. A finished head goes downstream; a finished task behind an unfinished head waits. Once the deque reaches `maxConcurrency`, the integrator blocks on the head before returning, which caps tasks in flight and holds back the source until a slot frees.
  • Why should a gatherer create its state in the initializer rather than in a field of the Gatherer?
    One gatherer instance can be used by several pipelines, and with a combiner it runs over partitions concurrently, so each evaluation or partition needs its own state. A shared field would leak values between runs and race in parallel. The contract also says the state and the `Downstream` must not be retained beyond the call that received them.

A gatherer is a station on an assembly line. The worker sets up a bench before the shift (initializer), handles each arriving part and may pass pieces to the next station (integrator), can pull a stop cord when no more parts are wanted, and clears the bench at the end of the shift even after a stop (finisher). Merging two benches after a split shift is the combiner.

  • The combiner runs on every gathering, including on a sequential stream.
  • The finisher is skipped once the integrator has returned false.
  • A false from Downstream.push rejects one element, and later elements may still be accepted.
  • Gatherers.mapConcurrent emits results in completion order, as soon as each mapper call finishes.
  • Gatherers.fold on an empty stream emits nothing, so its result is empty.
  • On a sequential stream, a greedy integrator keeps consuming an infinite source after a later limit is satisfied.

Stream Gatherers (Stream.gather, Gatherer, Gatherers)
Java 24pre-release 22

Assumes Java 27; Stream Gatherers are final since 24, and the Gatherer, Gatherers and GathererOp code reads the same at 25.

context