Skip to content

Confusing paragraph in Gatherers API page #256

Description

@authentictech

In Learn > The Stream API > The Gatherer API

I found the paragraph in the section on "Interrupting a Stream" initially quite confusing and wasn't sure what point it was getting at - in particular, from "It turns out":

It would be very inefficient to process all the elements from ints, which is the reason why this limit() call has the capacity to tell its upstream that it is not going to process any more element. It turns out that this upstream is returned by a map() call. The implementation of this operation should manage this interruption and push it to its upstream. This upstream pulls elements from the list, so it should stop doing that.

Can this paragraph be replaced with something clearer?

For what it's worth (take it or leave it) I asked ChatGPT to rewrite the paragraph in a clearer and more understandable way and this is what it came up with:

Suppose that you have a list containing one million elements. Processing every element with a costly map() operation would be inefficient if you only need the first ten results. The limit(10) operation solves this by stopping the stream once ten elements have passed through it. When that happens, the stream pipeline signals that no further elements are required. Each intermediate operation, such as map(), must propagate this stop request so that earlier stages also stop processing. As a result, the stream reads and maps only as many elements as necessary, rather than processing the entire list.

I find this much clearer and easier to understand - but does it fit the intended meaning?

At the very least, "element" in the original text should be pluralised.

Apologies if I'm just being dense. :-)

Activity

  1. JosePaumard commented on Jun 19, 2026

    @JosePaumard
    Contributor

    Thank you for your report! I just pushed a fix for the typo you mentionned.
    As for your request of rewriting this paragraph. I think that it accurately descibes what is happening.
    The ChatGPT version assumes that there is some kind of "stream pipeline" that has the capacity of interrupting itself or "signaling" that the stream is done. There is no such thing, and this is not how things happen. It may be simpler to understand, but it's wrong.
    Each intermediate operation pulls objects from an upstream and pushes them (or not, or some others, it could even push more than one) to a downstream. If an intermediate operation knows at some point that it will not push anymore object to its downstream, then it should notify its upstream that should act accordingly. If it does not, then you have an inefficient implemetation, too bad.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions