Writing Push Iterators

## What `iter.Seq` actually is Go's `iter` package declares two types and nothing complicated: ``` type Seq[V any] func(yield func(V) bool) type Seq2[K, V any] func(yield func(K, V) bool) ``` So a "sequence" in Go is a **function**, not a data structure. When someone calls it, it pushes values one at a time into the callback it was handed. That callback is conventionally named `yield`. These are called *push* iterators because the iterator is in charge: it runs a loop of its own and calls you for each element. ## The range loop is sugar for calling your function Since Go 1.23 the compiler accepts `for v := range f` when `f` has type `func(func(V) bool)`. It compiles the loop body into a function and passes that function as `yield`. The generated `yield` returns `true` to mean "keep going" and `false` once the loop is finished with you — because the body executed a `break`, a `return`, or otherwise left the loop. That is the whole protocol. ## The shape you write The idiomatic form is a small factory returning a closure: ``` func Names(dir string) iter.Seq[string] { return func(yield func(string) bool) { ... } } ``` Why a factory? Because `iter.Seq[V]` has exactly one parameter — the yield callback — and the range statement supplies it. Any other input the iterator needs (a directory path, a filter, a limit) has to be captured by the closure rather than passed as a parameter. `Names(dir)` therefore returns a value you can hand straight to `range`, or store, or pass to another function. ## The rules for the body 1. **Call `yield` once per element.** The element is the value the caller's loop variable will be bound to. 2. **Check the result every time.** `if !yield(v) { return }`. A false result means the consumer is done and you must produce nothing more. 3. **Do the work lazily.** The factory should not read anything. Callers expect that building the sequence is free and that cost is paid inside the loop. 4. **Own your resources inside the closure.** If the sequence needs a file or a handle open for the duration of the loop, open it inside the closure and `defer` its release there; the closure's frame lives exactly as long as the loop does. 5. **Return normally when the source is exhausted.** There is no sentinel value and no "done" flag: the loop ends when your function returns. ## A first example Listing the names in a directory: ``` func Names(dir string) iter.Seq[string] { return func(yield func(string) bool) { entries, err := os.ReadDir(dir) if err != nil { return } for _, e := range entries { if !yield(e.Name()) { return } } } } ``` The caller writes `for name := range Names("/etc")`. Note the awkward part: the error from `os.ReadDir` has nowhere to go, because the factory already returned before any reading happened. That is exactly what `iter.Seq2[string, error]` is for — a two-value yield where the second value carries the failure. ## `Seq2` in one paragraph `iter.Seq2[K, V]` yields pairs, and the caller writes `for k, v := range s`. The pair is whatever you decide it is: index and value, key and value, or value and error. The contract is identical — call `yield(k, v)`, check the bool, return when it is false. ## When a sequence is the wrong answer A sequence is not automatically better than a slice. If the result is small, already in memory, and callers want to sort it, index it, or keep it, return `[]T` — it is simpler, it can be re-used freely, and it does not require callers to be on a recent Go toolchain. A sequence earns its place when the result is large or streamed, when callers routinely stop early, or when producing a value costs something you would rather not pay for elements nobody looks at. ## The mental model to keep A push iterator is a loop you wrote, temporarily lending its body to somebody else. Everything that follows from that — checking yield's answer, cleaning up when they walk away, deciding where errors go — is a consequence of the fact that the loop is yours and the body is theirs.