Skip to content

Annotate Gatherer APIs. - #79

Merged
cpovirk merged 5 commits into
mainfrom
gatherer
Nov 20, 2026
Merged

cpovirk merged 5 commits into
mainfrom
gatherer

Conversation

@cpovirk

@cpovirk cpovirk commented Oct 4, 2024

Copy link
Copy Markdown
Collaborator

No description provided.

@wmdietl wmdietl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These look like they were missed, but I don't know this API:

default <RR> Gatherer<T, ?, RR> andThen(Gatherer<? super R, ?, ? extends RR> that) on line 274 in Gatherer: shouldn't RR allow null?
static <A> Supplier<A> defaultInitializer() on line 289 and static <A> BinaryOperator<A> defaultCombiner() on line 304 in Gatherer: should A allow null?
static <A, R> BiConsumer<A, Downstream<? super R>> defaultFinisher() { on line 321 in Gatherer: A and R should be nullable?

@cpovirk

cpovirk commented Oct 7, 2024

Copy link
Copy Markdown
Collaborator Author

Thanks, I had totally missed those.

andThen looks straightforward, assuming that I haven't been missing anything big throughout this PR.

The others are more interesting. The implementations of default* methods all look capable of handling null—or, in the case of the BinaryOperator for combiner(), as incapable of handling null as of any other value (and I think this point is that the Gatherer infrastructure treats combiner() as a sentinel that says not to invoke the method). There are two things that make that interesting:

  • First, the initializer() returns null. I think that means that we actually want to return a Supplier<@Nullable A>.
  • Second, the Gatherer API doesn't do PECS. That means that we probably shouldn't force other methods (like defaultCombiner()) to return a more general type, which is to say BinaryOperator<@Nullable A> (since we can't change it to the fully general type BinaryOperator<@Nullable Object>, since that would require a change to the base type). So I think it makes sense to let callers pick their nullness, just as they can pick the base type.

I have never actually used these APIs, so I could well still be missing things. I would be OK with waiting to merge this until I can justify taking the time to investigate more deeply, or we could go for it and figure that we'll get feedback if users encounter actual problems.

@cpovirk
cpovirk requested a review from wmdietl October 7, 2024 16:54

@wmdietl wmdietl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I had missed that this was updated. I merged in main and things look good to me.

@msridhar

msridhar commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator

@cpovirk are we good to merge this one? Or are we holding off until someone can do a deeper investigation?

@cpovirk

cpovirk commented Aug 9, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks for checking. (And thanks for all the other reviews!) I have been holding off until we can take a closer look. At this point, I don't remember even the level of detail in my comment above. (That might be a good thing, since I could try annotating the API again someday with fresh eyes and then see if the results match my earlier attempt :)) I don't have any specific plans to come back to this, though.

@cpovirk

cpovirk commented Sep 22, 2026

Copy link
Copy Markdown
Collaborator Author

I pointed Gemini at this PR. It suggested that I use <A extends @Nullable Object> on defaultInitializer(), even though the return type is already (appropriately) Supplier<@Nullable A>. It cited some precedent, but I contended that that precedent doesn't quite hold here and that Gemini was neglecting the possibility of calling Gatherers.<@NonNull T>defaultInitializer() (or hopefully having that type inferred automatically by a nullness checker). It signed onto my counterarguments once I laid them out.

It's hard to know precisely how much of an endorsement to view all that as, but clearly it's better than if Gemini had immediately identified some obvious problems :)

Overall, the annotations across Gatherer, Gatherers, and Stream.gather are very well-matched to both JSpecify's rules and the runtime behavior of java.util.stream.

There is one small improvement worth considering on Gatherer.defaultInitializer(), and the rest of the design choices hold up on close inspection.


1. Recommended Change: Upper bound of <A> on Gatherer.defaultInitializer()

Currently, line 287 of Gatherer.java is:

static <A> Supplier<@Nullable A> defaultInitializer()

Compare this with:

static <A extends @Nullable Object> Supplier<@Nullable A> defaultInitializer()

(analogous to how Comparator.nullsFirst and Objects.compare declare <T extends @Nullable Object> even when T appears as @Nullable T in the signature).

Why <A extends @Nullable Object> is preferable here while still keeping Supplier<@Nullable A>:

  1. Still enforces nullability of the supplied state: Returning Supplier<@Nullable A> still prevents a caller from assigning Gatherer.defaultInitializer() to a Supplier<NonNullState> (or passing it to Gatherer.of(defaultInitializer(), integrator, ...) with an Integrator<NonNullState, T, R>), because @Nullable A is always a nullable type regardless of whether A is instantiated as State or @Nullable State.
  2. Allows explicit or inferred nullable type arguments: With <A> bounded by non-null Object, an explicit call like Gatherer.<@Nullable Void>defaultInitializer() or Gatherer.<A>defaultInitializer() (where A is a type variable with bound A extends @Nullable Object, as in Gatherer.initializer() or Gatherer.ofSequential when matching target type Supplier<@Nullable Void>) violates A's upper bound in checkers that validate type arguments against bounds. Adding extends @Nullable Object avoids this while preserving the exact same return-type guarantee.

2. Verification of the Other Key Decisions

A. defaultInitializer(), defaultCombiner(), and defaultFinisher()

Your reasoning in PR #79 holds up when verified against Gatherers.Value.DEFAULT, Gatherers.Composite, and GathererOp:

  • Why defaultInitializer() must return Supplier<@Nullable A>: Whenever a gatherer's initializer is defaultInitializer(), GathererOp.GatherSink.begin and GathererOp.Sequential elide calling initializer.get() and leave A state as null (and if defaultInitializer().get() is called directly, Gatherers.Value.DEFAULT.get() returns null). That null state is then passed directly to integrator.integrate(state, ...) and finisher.accept(state, ...). Having defaultInitializer() return Supplier<@Nullable A> ensures that Gatherer.of(defaultInitializer(), ...) cannot infer a non-null state type A.
  • Why Gatherer.initializer() must stay Supplier<A> (not Supplier<@Nullable A>): The four methods on Gatherer<T, A, R> (initializer(), integrator(), combiner(), finisher()) all share A. If initializer() returned Supplier<@Nullable A>, then for a stateful Gatherer<T, NonNullState, R>, A state = gatherer.initializer().get() could not be passed to gatherer.integrator().integrate(state, t, downstream) (as in the class Javadoc snippet at Gatherer.java:78-84). When a gatherer is stateless, its A type argument itself should be nullable (such as @Nullable Void).
  • Why defaultCombiner() and defaultFinisher() use A (with <A extends @Nullable Object>) rather than @Nullable A: Unlike defaultInitializer(), defaultCombiner() and defaultFinisher() are routinely paired with a stateful, non-null initializer (e.g., Gatherer.of(State::new, integrator, Gatherer.defaultCombiner(), Gatherer.defaultFinisher())). Because Gatherer.of takes Supplier<A>, BinaryOperator<A>, and BiConsumer<A, Downstream<? super R>> without wildcards on A, returning BinaryOperator<@Nullable A> or BiConsumer<@Nullable A, ...> would force A to be @Nullable even when State::new produces a non-null State. Using <A extends @Nullable Object> lets A be either non-null or @Nullable.

B. @Nullable Void on Stateless Factory Methods (Gatherer.of / Gatherer.ofSequential)

  • In Gatherer.ofSequential and Gatherer.of, replacing Void with @Nullable Void in Gatherer<T, @Nullable Void, R>, Integrator<@Nullable Void, T, R>, and BiConsumer<@Nullable Void, Downstream<? super R>> is necessary and accurate:
    • The state parameter passed to the user's Integrator and BiConsumer at runtime is null.
    • Because A in Gatherer<T, A, R> has upper bound @Nullable Object, Gatherer<T, @Nullable Void, R> is a subtype of Gatherer<T, ?, R> (since an unbounded wildcard ? in @NullMarked code inherits the @Nullable Object upper bound of its corresponding type parameter), so it composes cleanly with Stream.gather and Gatherer.andThen.

C. Built-in Gatherers in Gatherers

  • windowFixed and windowSliding: Both store input elements into an Object[] and construct the output List<TR> via SharedSecrets.getJavaUtilCollectionAccess().listFromTrustedArrayNullsAllowed(...). Thus <TR extends @Nullable Object> Gatherer<TR, ?, List<TR>> accurately reflects that the windows themselves are non-null List instances whose element nullness matches TR.
  • fold, scan, and mapConcurrent: All three validate their function arguments with Objects.requireNonNull and pass input (T) and output (R) elements through without dereferencing them (in mapConcurrent, FutureTask<R> permits null results). Annotating <T extends @Nullable Object, R extends @Nullable Object> on all three is accurate.

You're right—that distinction holds, and defaultInitializer() belongs in the WeakReference<T> / Equivalence<T> (jspecify#78) bucket rather than the Comparator.nullsFirst bucket.

Why defaultInitializer() matches WeakReference / Equivalence

  1. A only appears as @Nullable A:
    In Comparator.nullsFirst (<T extends @Nullable Object> Comparator<@Nullable T> nullsFirst(@Nullable Comparator<? super T> comparator)), T also appears unannotated in Comparator<? super T>, so <T extends @Nullable Object> is needed to allow passing a Comparator<@Nullable Foo> without a bound mismatch.
    In static <A> Supplier<@Nullable A> defaultInitializer(), A appears only once and is already @Nullable A. Instantiating A with Foo and with @Nullable Foo would produce the exact same return type (Supplier<@Nullable Foo>), so leaving <A> with a non-null upper bound avoids giving callers two ways (Gatherer.<Foo>defaultInitializer() and Gatherer.<@Nullable Foo>defaultInitializer()) to express the same type.

  2. How callers interact with <A> in practice:

    • Unqualified calls (Gatherer.defaultInitializer()): When passed to Gatherer.of(defaultInitializer(), ...) where the target type is Supplier<@Nullable Void> (or Supplier<@Nullable State>), the constraint @Nullable A = @Nullable Void is satisfied by A = Void (non-null), which meets A extends Object.
    • Explicit type arguments: A caller writing an explicit type argument for a concrete type writes Gatherer.<Void>defaultInitializer() (getting back Supplier<@Nullable Void>), and only a caller forwarding a nullable-bounded type variable A extends @Nullable Object explicitly would need Gatherer.<@NonNull A>defaultInitializer() (or to rely on target-type inference, as Gatherer.initializer() and Gatherer.ofSequential() do). That is the exact same tradeoff made for WeakReference<T> and Equivalence<T>.

With that accounted for, I don't see any changes needed in the branch relative to main—the PR looks ready as-is.

@cpovirk

cpovirk commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

We now have some usage of Gatherer in our monorepo, though not much and mostly not in places where we apply nullness checking. Still, it's an additional kind of testing, and the initial results are looking fine. Because you only live once, I also burned some Fable 5.2 (Max) tokens and sent this for an internal human review. If all goes well, I'll merge the PR. And of course we can always revise afterward as necessary, as always.

My takeaways from Fable are:

  • "The inherited initializer() cannot be made sound," interesting. I should think about this more someday, but I'm assuming it's no worse than, say, AtomicReference.
  • It's fun that this is a case in which @Nullable Void could be wrong because of the non-null type parameter. Maybe someday VoidMissingNullable should handle this as it does similar cases.

The annotations are correct and complete; I found nothing that needs to change before merging. The full write-up, with the evidence for each declaration, is [in a separate blockquote below].

Three things need your eye:

  • defaultInitializer(): I would keep <A> Supplier<@Nullable A>. It is the form the @NonNull Javadoc recommends: "If a type variable has all its usages being projected in one direction or the other, it should be given a non-null upper bound."
    • Cost: an explicit type argument must be <Void>, not <@Nullable Void>, while defaultCombiner() and defaultFinisher() need <@Nullable Void> for the same stateless gatherer. NullAway rejects the @Nullable spelling.
    • How often it bites: javac forces an explicit type argument in a sentinel comparison when the state type is concrete, and the JDK's own GathererAPITest writes them on all three methods.
    • Optional: a one-line comment there would pre-empt the "shouldn't this bound be nullable?" question. Say the word and I'll add it.
  • Not verified: the JSpecify reference checker (your sibling checkout isn't built, and building it would write outside this workspace) and a JDK build. Instead I checked runtime behaviour on JDK 27 and ran NullAway 0.14.0 against a replica of the annotated API. I can try the reference checker if you want.
  • NullAway gap, for information: it does not enforce Supplier<@Nullable A> when A is inferred, so Supplier<Counter> s = Gatherer.defaultInitializer(); is accepted. This is not caused by your annotations; a standalone repro is in Repro.java.

Full writeup:

Review: JSpecify annotations for Gatherer (#79)

Verdict: the annotations are correct and complete, and I found nothing that needs to change before merging. Each one matches what the implementation does at runtime, the debated defaultInitializer() signature is the form that JSpecify's own documentation recommends, and the idioms from the Gatherer Javadoc check cleanly under NullAway's JSpecify mode.

There is one optional follow-up (a comment on defaultInitializer()) and three things worth knowing that need no action.

What I reviewed

HEAD (8f172b51af8, the merge of main into gatherer, which is also the tip of origin/gatherer) against the merge base 8cc8594c6d4, which is the current tip of main. The diff is therefore exactly what the PR adds today: 3 files, +36/−28, annotations and imports only.

The public surface is fully covered: everything in Gatherer (including Downstream, Integrator and Greedy), the five Gatherers factories, and Stream.gather. The only other code under src/ that mentions Gatherer is the package-private GathererOp and ReferencePipeline. Leaving those, and the non-public nested classes in Gatherers, unannotated matches how the repo treats Collectors.CollectorImpl.

How I checked

Check Result
Read the implementation: Gatherers.Value, Gatherers.Composite, GathererOp Consistent with every annotation (see the next table)
Ran 32 runtime assertions against the real java.util.stream.Gatherer on the local JDK 27.0.1 [RuntimeFacts.java) All pass
Ran NullAway 0.14.0 in JSpecify mode over about 70 small client methods compiled against a replica of the annotated API Intended uses accepted and misuse reported, with the exceptions described below
Compared against the PR thread, the user guide, the @NullMarked / @Nullable / @NonNull Javadoc, and jspecify/jspecify#78 Consistent

The replica is generated mechanically from the two annotated source files by make_replica.py: the package is renamed, @ForceInline and SharedSecrets are removed, and java.util.function types are replaced by same-package copies that carry jspecify/jdk's annotations. It is compiled with plain javac, so NullAway reads the annotations from class files, as it would for the JDK. I built it three times, differing only in defaultInitializer(), to compare the PR's signature with the two alternatives.

[!NOTE]
Two things I did not verify. I did not run the JSpecify reference checker: your sibling checkout is not built, and building it would write into the sibling checkouts and may need to download dependencies (Maven Central is blocked in my sandbox). I also did not build the JDK; the mechanically transformed copies of both files do compile with javac 25.

Declaration by declaration

Declaration Annotation in the PR Why it is right
Gatherer<T, A, R>, Integrator<A, T, R>, Greedy<A, T, R>, Downstream<T> Every type parameter extends @Nullable Object Streams carry null elements. The state is null for every stateless gatherer: GatherSink.begin skips the default initializer and leaves state null, and Composite passes a literal null. Same shape as Collector<T, A, R>.
initializer(), integrator(), combiner(), finisher() Unchanged: plain A A stateful gatherer's state is only ever what its own initializer or combiner returned.
andThen <RR extends @Nullable Object>, that non-null requireNonNull(that); null elements pass between the two stages.
defaultCombiner(), defaultFinisher() Nullable-bounded A (and R), used as plain A Both are sentinels that never look at the state: the combiner always throws UnsupportedOperationException and the finisher is a no-op. Because of(...) has no wildcards, they must take on the caller's exact state type: non-null for of(State::new, …, defaultCombiner(), defaultFinisher()), nullable for a stateless gatherer. NullAway accepts both uses.
defaultInitializer() <A> Supplier<@Nullable A> See the next section.
Stateless of / ofSequential (4 overloads) @Nullable Void as the state type, in parameters and return type The integrator and finisher are called with null, sequentially and in parallel. Same convention as CompletableFuture<@Nullable Void> and RecursiveAction.
Stateful of / ofSequential (3 overloads) Nullable-bounded T, A, R; all parameters non-null requireNonNull on every argument.
Integrator.of, Integrator.ofGreedy Nullable-bounded; parameter non-null These are identity functions with no null check, but passing null has no legitimate use.
Gatherers.windowFixed, windowSliding <TR extends @Nullable Object> Gatherer<TR, ?, List<TR>> Windows are built with listFromTrustedArrayNullsAllowed, and do contain nulls at runtime.
Gatherers.fold, scan, mapConcurrent Nullable-bounded T, R; function parameters non-null Values are only stored and forwarded; a null initial value, null inputs and null results all work. The functions are null-checked.
Stream.gather <R extends @Nullable Object> Same shape as map.

defaultInitializer()

static <A> Supplier<@Nullable A> defaultInitializer()

Supplier<@Nullable A> is right. The supplier returns null, and more importantly every user function of a gatherer built on it receives a null state: the integrator, the finisher and, in a parallel stream, the user's own combiner. All three are confirmed at runtime. With plain Supplier<A>, Gatherer.<Counter>defaultInitializer() would claim to supply a non-null Counter. NullAway rejects that under the PR's signature and accepts it under Supplier<A>.

<A> rather than <A extends @Nullable Object> is the documented recommendation. A is used only in the nullable projection @Nullable A, and the @NonNull Javadoc says: "If a type variable has all its usages being projected in one direction or the other, it should be given a non-null upper bound." The specification itself allows either form (the outcome of jspecify/jspecify#78), which is why the PR thread could go back and forth on it. The PR's form is the recommended one.

The non-null bound has one cost. It is the only difference I could observe between the two forms; every other probe behaves identically under both.

  • An explicit type argument must be the non-null form. Gatherer.<Void>defaultInitializer() is accepted and has type Supplier<@Nullable Void>, but NullAway reports:

    error: [NullAway] Type argument cannot be @Nullable, as method <A>defaultInitializer()'s type variable A is not @Nullable
        return gatherer.initializer() == Gatherer.<@Nullable Void>defaultInitializer();
    
  • Explicit type arguments are less exotic here than for most generic methods. javac rejects the sentinel comparison g.initializer() == Gatherer.defaultInitializer() when the state type is a concrete type such as Void ("incomparable types: Supplier and Supplier"), and the JDK's own GathererAPITest passes explicit type arguments to all three default*() methods. Once such code moves to @Nullable Void, it has to write <Void> for the initializer but <@Nullable Void> for the combiner and the finisher.

    I would keep <A>: it follows the documented advice, existing Gatherer.<Void>defaultInitializer() calls keep working unchanged, and the error message tells the user what to do.

    Optional follow-up. The nullable bound is the first thing a reviewer reaches for here: the earlier Gemini pass did, and so did I on first read. A one-line comment, in the style of the @PolyNull notes in Optional.java, might spare the next reader the same detour.

    Worth knowing (no action needed)

    1. The inherited initializer() cannot be made sound. A class that implements Gatherer<T, State, R> and inherits initializer() has its integrator called with a null State (confirmed at runtime), and a checker cannot object, because the inherited method is declared to return Supplier<A>. No annotation fixes this: declaring initializer() as Supplier<@Nullable A> would make the state nullable for every stateful gatherer. Leaving it as Supplier<A> is the right call.

    2. @Nullable Void has its usual price. Null-marked callers get a finding if they declare Gatherer<String, Void, Integer>, hold an Integrator<Void, …> in a variable, or pass a method reference whose state parameter is Void. Lambdas and Integrator.ofGreedy(…), which are the forms the Javadoc and the JEP use, are unaffected, and NullAway correctly treats the state as nullable inside them.

    3. NullAway has two limitations that show up here. Neither is caused by these annotations, and no other signature would avoid them.

      • It does not enforce Supplier<@Nullable A> when A is inferred. Supplier<Counter> s = Gatherer.defaultInitializer(); and Gatherer.of(Gatherer.defaultInitializer(), statefulIntegrator, …) are accepted, although both are rejected once the type argument is written out. It reproduces with no Gatherer involved, in Repro.java, which you may want to pass on to the NullAway maintainers.
      • It does not appear to propagate nullness through wildcards such as ? super T. stream.gather(Gatherers.windowFixed(2)) on a stream of @Nullable String is reported until the caller writes Gatherers.<@Nullable String>windowFixed(2), and a few mismatches that go through wildcards are missed, such as andThen with a second gatherer that cannot take the nulls the first one emits.

    Probe files

    All of these are in the conversation's scratch directory; nothing in the repository was modified.

    File What it covers
    RuntimeFacts.java The 32 runtime assertions; run with java RuntimeFacts.java
    Client.java Factories, default*(), direct implementations, pipelines
    Client2.java, Client5.java, Repro.java Misuse of defaultInitializer() and of the null state, with explicit and inferred type arguments
    Client3.java The GathererAPITest pattern, with the state type spelled three ways
    Client4.java, Client6.java Everyday pipelines, method references, nullable-element windows
    compare.sh Runs NullAway on a client file against all three variants of defaultInitializer()

    NullAway ran from the 0.14.0 jar in ~/.m2, with your local Error Prone 1.0-HEAD-SNAPSHOT build, on JDK 25, with JSpecifyMode=true and OnlyNullMarked=true.

@cpovirk
cpovirk merged commit a55e825 into main Nov 20, 2026
9 checks passed
@cpovirk
cpovirk deleted the gatherer branch November 20, 2026 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants