Iterator Pattern — Senior¶

1. The architectural question¶

Junior taught the shape — an object that yields one element at a time via Next()/Value(), hiding the structure of the underlying collection. Middle taught the variants — iter.Seq and iter.Seq2 from Go 1.23, push vs pull, error propagation, lazy composition with slices.Collect and the iter package. Senior is what happens when an iterator stops being a local convenience and becomes the public contract of a library, a database driver, a Kubernetes controller, or a Kafka consumer.

The day your *sql.Rows ships in database/sql, every Go program that talks to a relational database depends on its loop shape. The day your bufio.Scanner ships, every shell-script-replacement-in-Go follows the same for s.Scan() rhythm. The day your Kubernetes Watch returns an iter.Seq2[*Pod, error], controller-runtime authors rewrite their reconcile loops.

The senior-level forces:

1. Iterator design in published APIs — sql.Rows, bufio.Scanner, ast.Inspect, filepath.WalkDir, regexp.FindAllStringSubmatchIndex. The shape of these iterators determined how a generation of Go programmers wrote code. Some shapes aged well; some didn't.
2. iter.Seq adoption strategy — Go 1.23 shipped the iter package and range-over-func. Libraries now choose between push iterators (callback), pull iterators (Next/Value), and the new iter.Seq[T]/iter.Seq2[K, V] shape. The choice is not aesthetic — it has API stability, error handling, and performance consequences.
3. Backward compatibility — *sql.Rows cannot become an iter.Seq overnight. Real libraries keep Next()/Value() and expose an iter.Seq adapter. The transition strategy across major versions matters.
4. Distributed iterators — paginated REST APIs (nextPageToken), gRPC streaming, etcd Watch, Kafka consumers, Bigtable Table.ReadRows. The iterator hides not just collection layout but also network protocol, cursor management, snapshot semantics, and resumption.
5. Context cancellation — every iterator over an unbounded or slow source must honour ctx.Done(). Iterators that don't are a class of bug, not a corner case.
6. Concurrent iteration safety — most Go iterators are not safe for concurrent iteration. The contract must be explicit. The few that are (sync.Map.Range) document it loudly.
7. Memory considerations — lazy iteration is the whole point of the pattern. Materialising into a slice defeats it. But sometimes you must — and the trade-off is real.
8. Real ecosystems — client-go list/watch, etcd clientv3.Watch, Sarama/segmentio Kafka consumers, Bigtable Table.ReadRows, AWS SDK paginators. Each is an iterator under the hood; each has its own conventions, its own postmortems.
9. Anti-pattern resistance — leaked iterators (forgotten Close()), materialised-millions, infinite iteration on broken streams, iterators with hidden side effects, iterators that capture goroutines.

This file walks the senior-level shape of all of it. Sections 3-6 cover iterator design in published APIs and iter.Seq adoption. Sections 7-10 cover distributed iterators, context, and concurrency. Sections 11-14 cover memory, performance, and real ecosystems. Section 15 is postmortems. The rest is anti-patterns, cross-language comparison, mistakes, questions, and reference material.

2. Table of Contents¶

1. The architectural question
2. Table of Contents
3. Iterator design in published APIs: three canonical case studies
4. iter.Seq and iter.Seq2: the Go 1.23 shape
5. Adoption strategy: how a library moves to iter.Seq
6. Backward compatibility: keeping Next()/Value() and adding iter.Seq
7. Distributed iterators: paginated APIs, cursors, snapshots
8. Iterator with context cancellation
9. Concurrent iteration safety
10. Memory considerations: lazy vs materialised
11. Real ecosystems: client-go, etcd, Kafka, Bigtable
12. Performance at scale: per-element overhead, batching
13. Anti-patterns: leaks, materialisation, side effects
14. Profiling and debugging iterators in production
15. Postmortems
16. Cross-language comparison
17. Common senior-level mistakes
18. Tricky questions
19. Cheat sheet
20. Further reading

3. Iterator design in published APIs: three canonical case studies¶

Three iterators from the Go standard library define the design space. Every iterator you ship is a variation on one of these.

3.1 database/sql.Rows — the resource-owning pull iterator¶

rows, err := db.QueryContext(ctx, "SELECT id, email FROM users WHERE active = $1", true)
if err != nil {
    return err
}
defer rows.Close()

for rows.Next() {
    var id int64
    var email string
    if err := rows.Scan(&id, &email); err != nil {
        return err
    }
    // ... use id, email
}
if err := rows.Err(); err != nil {
    return err
}

Five primitives:

• Next() bool — advances; returns false when no more rows or on error.
• Scan(dest ...any) error — decodes the current row into destinations.
• Err() error — call after the loop to distinguish exhausted from errored.
• Close() error — must be called; releases the underlying connection.
• Columns(), ColumnTypes() — metadata access during iteration.

The design encodes hard requirements:

1. Resource ownership. Rows holds a *sql.Conn (or pooled equivalent). Forgetting Close() leaks the connection, which means pool exhaustion in 10 minutes under load.
2. Error after exhaustion. Next() == false is ambiguous — it could mean "no more rows" or "the network died". Err() after the loop disambiguates.
3. Streaming, not buffered. Each Next() may trigger a network round-trip (for cursors) or read from a streaming response. The driver decides whether to prefetch.
4. Single-use, single-goroutine. Rows is not safe for concurrent iteration. The contract is explicit in the godoc.

What aged well: - The defer rows.Close() idiom is universal. Every Go programmer learns it once. - The Err()-after-loop pattern is unusual but correct. It separates two failure modes that the boolean return collapses.

What aged badly: - Scan with ...any and out-parameters is awkward — type errors caught at runtime, not compile time. Sqlx, sqlc, and pgx all offer better shapes. - No iter.Seq adapter in the standard library as of Go 1.23. Third-party wrappers exist but you can't iterate rows with range rows in stdlib.

3.2 bufio.Scanner — the line/token pull iterator with internal buffer¶

f, err := os.Open("/var/log/syslog")
if err != nil { return err }
defer f.Close()

scanner := bufio.NewScanner(f)
scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) // grow to 1 MB
for scanner.Scan() {
    line := scanner.Text()
    if strings.Contains(line, "ERROR") {
        process(line)
    }
}
if err := scanner.Err(); err != nil {
    return err
}

Three primitives, very similar to sql.Rows:

• Scan() bool — read the next token; returns false at EOF or error.
• Text() / Bytes() — the current token.
• Err() error — distinguishes EOF from real error (io.EOF is not returned; it's the absence of Err).

Design choices:

1. Buffered. Scanner holds an internal buffer; it reads chunks from the underlying io.Reader, finds tokens, returns them.
2. Pluggable token boundary. scanner.Split(bufio.ScanWords) switches from lines to words. Custom SplitFunc lets you scan TLVs, fixed-width records, anything.
3. Token reuse caveat. scanner.Bytes() returns a slice into the internal buffer. The next Scan() overwrites it. If you need to keep the bytes, copy them. This is a senior-level footgun documented in the godoc but missed routinely.
4. Max token size. Default 64 KB. A line longer than that returns bufio.ErrTooLong. The Buffer method raises the cap. The Scanner actively refuses pathologically long inputs — the design assumes log files, not arbitrary streams.

// ANTI-PATTERN: keeping a slice into the scanner buffer
var lines [][]byte
for scanner.Scan() {
    lines = append(lines, scanner.Bytes())  // BUG: all entries point at the same buffer
}
// After the loop, all `lines[i]` are equal to the last scanned line.

// FIX: copy
for scanner.Scan() {
    b := scanner.Bytes()
    cp := make([]byte, len(b))
    copy(cp, b)
    lines = append(lines, cp)
}

Or use scanner.Text(), which allocates a new string each call — slower but safer.

What aged well: - SplitFunc is genuinely flexible. The same scanner reads lines, words, runes, custom framings. - The "token boundaries can be customised" abstraction is right.

What aged badly: - The default max-token-size has caused thousands of bug reports. People don't read the godoc; they hit bufio.ErrTooLong in production on a long JSON line. - The "bytes returned alias the buffer" trap. A new design would copy by default and offer a zero-copy variant explicitly.

3.3 go/ast.Inspect — the push iterator with visitor¶

import "go/ast"

ast.Inspect(file, func(n ast.Node) bool {
    if call, ok := n.(*ast.CallExpr); ok {
        if id, ok := call.Fun.(*ast.Ident); ok && id.Name == "panic" {
            fmt.Println("found panic at", fset.Position(call.Pos()))
        }
    }
    return true  // continue
})

One primitive: Inspect(root, func(Node) bool). The caller passes a closure; the function calls it for every node in the tree, in depth-first pre-order. Return false to stop descending into the current subtree.

This is the push iterator shape — also called the internal iterator in design pattern literature. The library drives the loop; the caller provides a callback.

Trade-offs vs the pull shape:

Push iterators are right when the iteration structure is non-trivial (a tree, a graph) and you want to hide the traversal logic. Pull iterators are right when iteration is linear and the caller wants control over flow.

What aged well: - For tree traversal, push is unambiguously better. ast.Inspect is a clean API. - The return false to prune subtrees is exactly the right primitive.

What aged badly: - No way to abort the whole walk early. You can return false to skip a subtree, but to stop entirely you have to panic or set a captured flag (and then keep returning false for all remaining nodes — wasteful). - No context support. If you're walking a huge AST and the user cancels, you can't honour it. - The iter.Seq shape (Go 1.23) would let ast.Inspect be replaced by for n := range ast.Walk(file) with break working naturally. The standard library has not done this yet, but third-party AST walkers have.

3.4 The honourable mentions¶

• filepath.WalkDir — push iterator over a directory tree. Returns filepath.SkipDir to prune subtrees. Has context-like cancellation via the error return.
• regexp.FindAllStringSubmatchIndex — materialised iterator. Returns a slice of all matches. Convenient but un-streamable. For very large inputs, use FindAllStringSubmatchIndexN with a limit, or build a manual loop with FindStringSubmatchIndex.
• encoding/json.Decoder.Token — pull iterator over a JSON stream. Returns one token at a time ({, }, key, value). Used for streaming-decode large JSON without loading it all.
• net/http.Header.Values — was a []string returner until Go 1.14, when adding it broke nothing because slices iterate trivially. A slice is itself an iterator API.

4. iter.Seq and iter.Seq2: the Go 1.23 shape¶

Go 1.23 (released August 2024) added two things that changed iterator design in the language:

1. Range-over-func. for x := range f { ... } works when f has the right shape.
2. The iter package. Standard types iter.Seq[V] and iter.Seq2[K, V], plus helpers in slices and maps.

4.1 The types¶

package iter

type Seq[V any]      func(yield func(V) bool)
type Seq2[K, V any]  func(yield func(K, V) bool)

A Seq[V] is a function that, when called, drives an iteration by calling yield for each element. If yield returns false, the producer stops. The compiler turns for x := range seq { ... } into a closure-passing call.

// Producer
func Count(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := 0; i < n; i++ {
            if !yield(i) {
                return
            }
        }
    }
}

// Consumer
for i := range Count(10) {
    fmt.Println(i)
    if i == 5 {
        break  // sets yield's return to false; producer stops
    }
}

Seq2[K, V] is the same shape for two-value yields (map-like, or value+error):

func Lines(r io.Reader) iter.Seq2[int, string] {
    return func(yield func(int, string) bool) {
        s := bufio.NewScanner(r)
        i := 0
        for s.Scan() {
            if !yield(i, s.Text()) {
                return
            }
            i++
        }
    }
}

for lineNum, line := range Lines(f) {
    fmt.Printf("%d: %s\n", lineNum, line)
}

4.2 Why this matters architecturally¶

Before Go 1.23, libraries had to choose:

• Pull (Next()/Value()) — caller controls flow but every iterator is a custom struct.
• Push (callback) — library controls flow but break doesn't work; errors flow through closures.
• Channels — natural-looking for x := range ch but goroutine cost, channel allocation, no synchronous backpressure, hard to bound lifecycle.

iter.Seq is the missing fourth option:

• Looks like for x := range ch — caller-friendly.
• No goroutine; the producer runs synchronously in the consumer's goroutine.
• break works because the yield returns false.
• No channel allocation.
• Composes with slices.Collect, slices.Sorted, maps.All, etc.

4.3 Error propagation in iter.Seq2¶

A common pattern: iter.Seq2[T, error] returns each element with its potential error.

func ReadRecords(ctx context.Context, db *sql.DB) iter.Seq2[Record, error] {
    return func(yield func(Record, error) bool) {
        rows, err := db.QueryContext(ctx, "SELECT id, name FROM records")
        if err != nil {
            yield(Record{}, err)
            return
        }
        defer rows.Close()

        for rows.Next() {
            var r Record
            if err := rows.Scan(&r.ID, &r.Name); err != nil {
                if !yield(Record{}, err) {
                    return
                }
                continue
            }
            if !yield(r, nil) {
                return
            }
        }
        if err := rows.Err(); err != nil {
            yield(Record{}, err)
        }
    }
}

// Usage
for r, err := range ReadRecords(ctx, db) {
    if err != nil {
        log.Printf("scan error: %v", err)
        continue
    }
    process(r)
}

This is the canonical shape for fallible iterators in modern Go. It collapses three previously-separate things — element, error, EOF — into one range loop.

Compare to the sql.Rows shape:

// Pre-Go-1.23 shape
for rows.Next() {
    var r Record
    if err := rows.Scan(&r.ID, &r.Name); err != nil {
        return err
    }
    process(r)
}
if err := rows.Err(); err != nil {
    return err
}
rows.Close()

// Go 1.23+ shape
for r, err := range ReadRecords(ctx, db) {
    if err != nil { return err }
    process(r)
}
// Close happens inside the iterator via defer.

The new shape is shorter and harder to get wrong. Forgotten Close is now the iterator implementer's bug, not the caller's.

4.4 The "pull" form via iter.Pull¶

Sometimes you need the inverse — convert a push iterator (Seq) back into a pull style (Next()-like). The iter package provides this:

func iter.Pull[V any](seq Seq[V]) (next func() (V, bool), stop func())
func iter.Pull2[K, V any](seq Seq2[K, V]) (next func() (K, V, bool), stop func())

seq := Count(10)
next, stop := iter.Pull(seq)
defer stop()

for {
    v, ok := next()
    if !ok { break }
    fmt.Println(v)
    if v == 3 { break }
}

iter.Pull internally spins up a goroutine that runs the producer; next reads from it via a channel-like rendezvous. It allocates a goroutine. Use only when you genuinely need pull-style flow (interleaving two iterators, custom protocols). For ordinary loops, for v := range seq is cheaper.

4.5 Composing with slices and maps¶

import "slices"

// Collect all elements
xs := slices.Collect(Count(10))  // []int{0,1,...,9}

// Sort
sorted := slices.Sorted(Count(10))

// Take first N
first5 := slices.Collect(Limit(Count(1000000), 5))

// Filter, map
evens := slices.Collect(Filter(Count(10), func(i int) bool { return i%2 == 0 }))

slices.Collect materialises a Seq[V] into a []V. Useful for tests, small results, or when you genuinely need a slice. Don't Collect an unbounded iterator — it OOMs.

slices.All, slices.Values, maps.All, maps.Keys, maps.Values go the other direction — from a slice/map to a Seq. The whole standard library now composes uniformly.

5. Adoption strategy: how a library moves to iter.Seq¶

You ship a library. You have Next()/Value() iterators from 2020. Go 1.23 ships. Customers ask for iter.Seq. What do you do?

5.1 The strategy matrix¶

The standard library's pattern (as seen in slices.All, maps.All, etc.) is the gold standard: add new methods that return iter.Seq, leave old methods alone, never deprecate. A library with a million users has no other option.

5.2 Pattern: add an .All() method that returns iter.Seq¶

This is the dominant pattern in the Go ecosystem since 1.23.

type RecordSet struct {
    rows *sql.Rows
    // ...
}

// Legacy API — unchanged.
func (rs *RecordSet) Next() bool { ... }
func (rs *RecordSet) Value() Record { ... }
func (rs *RecordSet) Err() error { ... }
func (rs *RecordSet) Close() error { ... }

// New API in v1.5 — returns iter.Seq2 for range-over-func.
func (rs *RecordSet) All() iter.Seq2[Record, error] {
    return func(yield func(Record, error) bool) {
        defer rs.Close()
        for rs.Next() {
            if !yield(rs.Value(), nil) {
                return
            }
        }
        if err := rs.Err(); err != nil {
            yield(Record{}, err)
        }
    }
}

Now callers can do either:

// Old style — still works
for rs.Next() {
    r := rs.Value()
    // ...
}
if err := rs.Err(); err != nil { ... }
rs.Close()

// New style — Go 1.23+
for r, err := range rs.All() {
    if err != nil { ... }
    // ...
}
// rs.Close() handled by All()

Zero breakage. Old callers keep working. New callers get the modern shape.

5.3 Pattern: factory functions return iter.Seq directly¶

For new functions added in v1.23+, skip the legacy shape entirely:

// New in v1.5 — no Next()/Value() variant exists
func (db *DB) StreamRecords(ctx context.Context, filter Filter) iter.Seq2[Record, error] {
    return func(yield func(Record, error) bool) {
        rows, err := db.QueryContext(ctx, "SELECT ...", filter.Args()...)
        if err != nil {
            yield(Record{}, err)
            return
        }
        defer rows.Close()

        for rows.Next() {
            select {
            case <-ctx.Done():
                yield(Record{}, ctx.Err())
                return
            default:
            }
            var r Record
            if err := rows.Scan(&r.ID, &r.Name); err != nil {
                if !yield(Record{}, err) { return }
                continue
            }
            if !yield(r, nil) { return }
        }
        if err := rows.Err(); err != nil {
            yield(Record{}, err)
        }
    }
}

New features can use the modern shape from day one.

5.4 The "wrap don't replace" rule¶

Bad:

// v2.0 — breaking change
type RecordSet struct { ... }
// Removed: Next(), Value(), Err(), Close()
// Replaced with: iterator() iter.Seq2[Record, error]

Every customer breaks. Every. Single. One.

Good:

// v1.5 — additive
type RecordSet struct { ... }
// Existing: Next(), Value(), Err(), Close()  // unchanged
// New: All() iter.Seq2[Record, error]

If iter.Seq adoption is universal in 3 years, you can document the legacy shape as Deprecated in v1.10 and remove it in v2.0. By then, customers have had ample time to migrate.

5.5 The minimum-Go-version question¶

Adding iter.Seq requires Go 1.23. If your library's go.mod says go 1.21, you can't reference iter.Seq without bumping it.

Bumping the minimum Go version is itself a breaking change for some users. Strategies:

• Major version bump (v2): bump min Go, add iter.Seq. Customers migrate.
• Build tags: ship iter.Seq methods behind //go:build go1.23. The library compiles on older Go without the new API.
• Separate module: github.com/me/lib/iter as a submodule that requires Go 1.23. Main module stays put.

In practice, by mid-2026 most actively-maintained libraries have moved to Go 1.23 as their minimum. The transition cost is real but bounded.

6. Backward compatibility: keeping Next()/Value() and adding iter.Seq¶

The technical details of the dual-API strategy.

6.1 The wrapper that bridges both worlds¶

// Iterator is the legacy, pull-style API.
type Iterator[T any] struct {
    next  func() (T, bool, error)
    closeFn func() error

    current T
    err     error
    closed  bool
}

func (it *Iterator[T]) Next() bool {
    if it.closed { return false }
    v, ok, err := it.next()
    if err != nil {
        it.err = err
        return false
    }
    if !ok { return false }
    it.current = v
    return true
}

func (it *Iterator[T]) Value() T { return it.current }

func (it *Iterator[T]) Err() error { return it.err }

func (it *Iterator[T]) Close() error {
    if it.closed { return nil }
    it.closed = true
    return it.closeFn()
}

// All returns a range-over-func iterator. Calling it consumes the iterator.
// Do not mix calls to Next() with iteration via All().
func (it *Iterator[T]) All() iter.Seq2[T, error] {
    return func(yield func(T, error) bool) {
        defer it.Close()
        for it.Next() {
            if !yield(it.current, nil) {
                return
            }
        }
        if it.err != nil {
            yield(*new(T), it.err)
        }
    }
}

The same iterator object can be used either way. The godoc warns about mixing — calling Next() then All() then Next() again is undefined.

6.2 The "from iter.Seq back to Next()" adapter¶

Some callers want a pull-style API for an iter.Seq:

func NewIterator[T any](seq iter.Seq2[T, error]) *Iterator[T] {
    next, stop := iter.Pull2(seq)
    return &Iterator[T]{
        next: func() (T, bool, error) {
            v, e, ok := next()
            return v, ok, e
        },
        closeFn: func() error {
            stop()
            return nil
        },
    }
}

iter.Pull2 spawns a goroutine. The cost is real (one goroutine per iterator, ~2 KB stack at minimum). For high-rate iterator construction (e.g., per-request), prefer not to convert; use the form natural to the call site.

6.3 Real example: how database/sql would adopt (and why it hasn't)¶

*sql.Rows is the most-used iterator in Go. Adding All() would let:

// Imagined future API
for r, err := range rows.All() {
    if err != nil { return err }
    var id int64
    var name string
    if err := r.Scan(&id, &name); err != nil { return err }
    // ...
}

The Scan call is still needed because *sql.Rows doesn't know your target struct. The Go core team has discussed this; the current state (mid-2026) is that database/sql has not yet added All(). The conservatism is intentional — a stdlib change ships forever.

Third-party libraries (sqlx, sqlc, pgx) have added iter.Seq adapters faster. The pattern: a generic Rows[T] type that knows its row type and yields directly:

type Rows[T any] struct {
    raw  *sql.Rows
    scan func(*sql.Rows) (T, error)
}

func (r *Rows[T]) All() iter.Seq2[T, error] {
    return func(yield func(T, error) bool) {
        defer r.raw.Close()
        for r.raw.Next() {
            v, err := r.scan(r.raw)
            if !yield(v, err) { return }
            if err != nil { continue }
        }
        if err := r.raw.Err(); err != nil {
            yield(*new(T), err)
        }
    }
}

6.4 The "mixed loop" pitfall¶

// BUG: mixing Next() and All()
for it.Next() {
    if filter(it.Value()) {
        for v, err := range it.All() {  // resumes from current state — surprising
            // ...
        }
    }
}

Decide on one API per call site. Documentation should say so loudly:

Calling All() on an iterator that has been partially advanced via Next() continues from the current position. Calling Next() after All() has been consumed returns false.

6.5 What changes for testing¶

Old tests look like:

func TestIteratorReturnsAllRecords(t *testing.T) {
    it := repo.All()
    var got []Record
    for it.Next() {
        got = append(got, it.Value())
    }
    if err := it.Err(); err != nil {
        t.Fatal(err)
    }
    if !reflect.DeepEqual(got, want) {
        t.Errorf("got %v, want %v", got, want)
    }
}

New tests use slices.Collect:

func TestIteratorReturnsAllRecords(t *testing.T) {
    seq := repo.All()
    var got []Record
    for r, err := range seq {
        if err != nil { t.Fatal(err) }
        got = append(got, r)
    }
    if !reflect.DeepEqual(got, want) {
        t.Errorf("got %v, want %v", got, want)
    }
}

When testing, prefer to drain into a slice and assert on the slice — it makes failure messages much better.

7. Distributed iterators: paginated APIs, cursors, snapshots¶

When the data lives on another machine, the iterator hides not just collection layout but also network protocol, cursor state, and snapshot semantics. The senior-level concerns multiply.

7.1 Three patterns for distributed iteration¶

7.2 Pagination iterator: the canonical shape¶

type PaginatedClient struct {
    httpClient *http.Client
    baseURL    string
}

func (c *PaginatedClient) ListUsers(ctx context.Context) iter.Seq2[User, error] {
    return func(yield func(User, error) bool) {
        nextToken := ""
        for {
            page, err := c.fetchPage(ctx, nextToken)
            if err != nil {
                yield(User{}, fmt.Errorf("fetch page (token=%q): %w", nextToken, err))
                return
            }
            for _, u := range page.Users {
                if !yield(u, nil) {
                    return
                }
            }
            if page.NextPageToken == "" {
                return
            }
            nextToken = page.NextPageToken

            // Honour cancellation between pages
            select {
            case <-ctx.Done():
                yield(User{}, ctx.Err())
                return
            default:
            }
        }
    }
}

func (c *PaginatedClient) fetchPage(ctx context.Context, token string) (*Page, error) {
    u, _ := url.Parse(c.baseURL + "/users")
    q := u.Query()
    if token != "" {
        q.Set("page_token", token)
    }
    u.RawQuery = q.Encode()

    req, _ := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
    resp, err := c.httpClient.Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()

    if resp.StatusCode != 200 {
        return nil, fmt.Errorf("unexpected status %d", resp.StatusCode)
    }
    var p Page
    if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
        return nil, err
    }
    return &p, nil
}

Key design points:

• Iterator is lazy. No network call happens until the first yield. If the consumer breaks immediately, only one page is fetched.
• Page is opaque. The iterator hides whether the page is 10 or 1000 elements. The caller iterates per element.
• Cancellation between pages. A select { ... ctx.Done() ... } check between page fetches lets long iterations be cancelled.
• Errors carry context. Wrapping the error with the failed token helps debugging.

7.3 Cursor-based iteration with retry on transient failures¶

Real APIs fail. The iterator should retry transient errors:

func (c *PaginatedClient) ListUsersResilient(ctx context.Context) iter.Seq2[User, error] {
    return func(yield func(User, error) bool) {
        nextToken := ""
        for {
            page, err := c.fetchPageWithRetry(ctx, nextToken, 3)
            if err != nil {
                yield(User{}, err)
                return
            }
            for _, u := range page.Users {
                if !yield(u, nil) { return }
            }
            if page.NextPageToken == "" { return }
            nextToken = page.NextPageToken
        }
    }
}

func (c *PaginatedClient) fetchPageWithRetry(ctx context.Context, token string, maxAttempts int) (*Page, error) {
    var lastErr error
    backoff := 100 * time.Millisecond
    for attempt := 0; attempt < maxAttempts; attempt++ {
        page, err := c.fetchPage(ctx, token)
        if err == nil { return page, nil }
        if !isRetryable(err) { return nil, err }
        lastErr = err
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        case <-time.After(backoff):
        }
        backoff *= 2
    }
    return nil, fmt.Errorf("after %d attempts: %w", maxAttempts, lastErr)
}

The senior concern: where does the retry belong — inside the iterator or in a decorator over it? Both work. Inside is simpler; decorator is more testable. For libraries, document which.

7.4 Snapshot consistency¶

Cursor-based pagination on most databases is snapshot-stable: the cursor token references a server-side snapshot taken at the first request. Writes after that point are invisible to the iteration.

But not all APIs guarantee this. GitHub's REST API explicitly says pagination is not snapshot-stable — items can be repeated or skipped under concurrent writes. The same is true of MongoDB's natural-order pagination, of Elasticsearch's from/size, and of any "offset-based" API.

The iterator's godoc must say which:

// ListUsers returns an iterator over all users matching the filter.
//
// Snapshot semantics: the iteration is snapshot-stable as of the first
// request. Users created after the iteration started are not visible.
// Users deleted during iteration may or may not appear, depending on
// when they're deleted relative to the cursor's position.
//
// Best effort: the iterator retries transient errors up to 3 times.
// Non-retryable errors stop the iteration.
func (c *Client) ListUsers(ctx context.Context, filter Filter) iter.Seq2[User, error] { ... }

Without that documentation, callers either assume snapshot stability (and write code that breaks when it isn't) or assume no stability (and write defensive deduplication for no reason).

7.5 Resumable iteration via persisted cursors¶

For very long iterations (batch jobs, daily exports), persist the cursor:

type ResumableIterator struct {
    client      *PaginatedClient
    checkpoint  CheckpointStore  // file, redis, dynamodb, etc.
    key         string
}

func (r *ResumableIterator) All(ctx context.Context) iter.Seq2[User, error] {
    return func(yield func(User, error) bool) {
        token, _ := r.checkpoint.Load(ctx, r.key)
        for {
            page, err := r.client.fetchPage(ctx, token)
            if err != nil {
                yield(User{}, err)
                return
            }
            for _, u := range page.Users {
                if !yield(u, nil) {
                    // Save progress before exiting — caller wants to resume later
                    r.checkpoint.Save(ctx, r.key, token)
                    return
                }
            }
            if page.NextPageToken == "" {
                r.checkpoint.Delete(ctx, r.key) // iteration complete
                return
            }
            token = page.NextPageToken
            r.checkpoint.Save(ctx, r.key, token)  // checkpoint after each page
        }
    }
}

Trade-off: checkpoint frequency. Per-page is cheap and gives at-most-one-page reprocessing on restart. Per-element is expensive and gives near-zero reprocessing. The right frequency depends on the cost of duplicate work and the cost of checkpoint storage.

7.6 The "ListAndWatch" pattern (Kubernetes-style)¶

For systems that need both bulk-load and follow-changes, the canonical pattern is:

1. List — paginate the current state into the iterator's consumer.
2. Watch — open a stream from the list's revision; receive updates indefinitely.

func (c *ResourceClient) ListAndWatch(ctx context.Context) iter.Seq2[Event, error] {
    return func(yield func(Event, error) bool) {
        // Phase 1: list
        resourceVersion := ""
        for {
            page, err := c.list(ctx, resourceVersion)
            if err != nil {
                yield(Event{}, err)
                return
            }
            for _, item := range page.Items {
                if !yield(Event{Type: EventAdded, Item: item}, nil) {
                    return
                }
            }
            if page.NextToken == "" {
                resourceVersion = page.ResourceVersion
                break
            }
        }

        // Phase 2: watch from the list's revision
        events, err := c.watch(ctx, resourceVersion)
        if err != nil {
            yield(Event{}, err)
            return
        }
        for e := range events {
            if !yield(e, nil) { return }
        }
    }
}

This is the conceptual shape of Kubernetes informers, etcd watchers, Bigtable change streams, and most CDC (change-data-capture) systems. The iterator unifies the "snapshot" and "tail" phases into one stream that the consumer doesn't have to manage.

8. Iterator with context cancellation¶

Every iterator that does I/O or that can run for an unbounded time must honour ctx.Done(). This is non-negotiable in production code.

8.1 Where to check¶

Three places:

1. Before each network call. Don't issue a request you already know is doomed.
2. Between elements. A consumer that breaks gets the iterator's return, but a consumer that doesn't break (because the iterator is producing infinitely) needs the iterator to check.
3. At blocking I/O. Use context-aware APIs (db.QueryContext, http.NewRequestWithContext) so the underlying syscall returns on cancellation.

func StreamRecords(ctx context.Context, db *sql.DB) iter.Seq2[Record, error] {
    return func(yield func(Record, error) bool) {
        rows, err := db.QueryContext(ctx, "SELECT ...")  // (1) context-aware query
        if err != nil {
            yield(Record{}, err)
            return
        }
        defer rows.Close()

        for rows.Next() {
            // (2) check between elements
            select {
            case <-ctx.Done():
                yield(Record{}, ctx.Err())
                return
            default:
            }

            var r Record
            if err := rows.Scan(&r.ID, &r.Name); err != nil {
                if !yield(Record{}, err) { return }
                continue
            }
            if !yield(r, nil) { return }
        }
        if err := rows.Err(); err != nil {
            yield(Record{}, err)
        }
    }
}

8.2 The "ctx in the iterator constructor" question¶

Should the iterator capture ctx at construction time, or accept it per-call?

// Option A: ctx in constructor
func (c *Client) ListUsers(ctx context.Context) iter.Seq2[User, error] { ... }

// Option B: no ctx in constructor; iterator can't be cancelled
func (c *Client) ListUsers() iter.Seq2[User, error] { ... }

// Option C: ctx passed per element (impossible with iter.Seq's signature)

Always use Option A. The iterator captures the context at construction; cancellation flows through the captured context. This is consistent with how db.QueryContext returns *sql.Rows that's bound to the original ctx.

The consequence: an iterator is bound to a context. Reusing it across requests means reusing the original request's context, which may already be cancelled. Construct one iterator per request scope.

8.3 Cancellation latency¶

If the iterator is mid-call to a slow backend, cancellation takes effect when the backend's I/O returns. For a database query that's already executing, that's the time to interrupt the query (PostgreSQL: ~10 ms via cancel request; MySQL: depends on the query's check points).

For long-running iterations, design the iterator to break iteration into chunks that respect cancellation more frequently. E.g., for a cursor query that returns 10K rows in one network round trip, the cancellation only takes effect at the next round trip. Setting a smaller page size makes cancellation more responsive at the cost of more network round trips.

8.4 Deadlines vs cancellation¶

Both flow through ctx. The iterator doesn't care which — ctx.Done() fires on either. But the caller should know:

// Caller: deadline-bound iteration
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

for r, err := range repo.ListUsers(ctx) {
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            // Partial result; handle accordingly
            log.Warn("hit timeout, processed N records so far")
            break
        }
        return err
    }
    process(r)
}

For batch jobs, deadline is the safety net. For interactive requests, cancellation is the user-driven case. The same iterator handles both because the same ctx.Done() signal flows.

8.5 The errors.Is(err, context.Canceled) check¶

Iterators that return ctx.Err() on cancellation should make this discoverable:

for r, err := range repo.ListUsers(ctx) {
    if err != nil {
        switch {
        case errors.Is(err, context.Canceled):
            // Caller cancelled; don't log as failure
            return nil
        case errors.Is(err, context.DeadlineExceeded):
            log.Warn("timeout during iteration")
            return err
        default:
            return fmt.Errorf("iteration: %w", err)
        }
    }
    process(r)
}

This is the senior-level error-handling pattern. Surface the cause, classify it, act accordingly.

9. Concurrent iteration safety¶

Most Go iterators are not safe for concurrent iteration from multiple goroutines. The contract must be explicit.

9.1 The default assumption¶

By convention, a Go iterator is single-iterator, single-goroutine:

// Default: NOT safe for concurrent use
type Iterator[T any] struct {
    pos  int
    data []T
}

func (it *Iterator[T]) Next() bool { ... }
func (it *Iterator[T]) Value() T   { ... }

Two goroutines calling Next() on the same Iterator is a data race. The godoc must say "not safe for concurrent use".

9.2 The sync.Map.Range exception¶

sync.Map.Range is safe for concurrent use with concurrent writes to the map. It returns a consistent (eventually) view; new inserts may or may not be visible.

var m sync.Map
m.Store("a", 1)

// Other goroutines may Store/Delete during this:
m.Range(func(k, v any) bool {
    fmt.Println(k, v)
    return true
})

The implementation: sync.Map keeps a "read" snapshot and a "dirty" overlay. Range iterates the read snapshot, which is immutable; writes go to dirty. Readers see a stable view; the eventual consistency comes from periodic promotion of dirty to read.

This is the only standard-library iterator that's safe under concurrent modification. Everything else either panics (map-range during write) or returns undefined data.

9.3 The "fork" question¶

Can one iterator be split into N concurrent iterators?

seq := someIterator()
// Want: 4 workers, each processes 1/4 of elements

No, not directly. iter.Seq is a closure with one yield receiver. You can't pass it to four goroutines and have each consume.

Two strategies:

1. Materialise then partition.

   xs := slices.Collect(seq)
   n := len(xs) / 4
   for i := 0; i < 4; i++ {
       go process(xs[i*n:(i+1)*n])
   }
   

   Defeats laziness; OOMs on large iterators.

2. Fan out via channel.

   ch := make(chan Item, 100)
   go func() {
       defer close(ch)
       for x := range seq {
           ch <- x
       }
   }()
   // N workers all read from ch
   for i := 0; i < 4; i++ {
       go func() {
           for x := range ch {
               process(x)
           }
       }()
   }
   

   Each item is processed by one worker; the channel distributes. This works and is the canonical Go pattern.

9.4 The race detector¶

go test -race catches most concurrent iteration bugs:

func TestIteratorIsConcurrentSafe(t *testing.T) {
    it := makeIterator()
    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for v := range it.All() {
                _ = v
            }
        }()
    }
    wg.Wait()
}

If the iterator is not concurrent-safe, the race detector flags accesses to it.pos or it.current from multiple goroutines. Don't ship without running tests with -race.

9.5 The "thread-confined" pattern¶

For data sources that produce in one goroutine and consume in another, the thread-confined iterator is right:

• Producer goroutine owns the iterator state.
• Consumer goroutine receives via channel.
• No shared mutable state between them.

func produceAndIterate(ctx context.Context, src DataSource) iter.Seq[Item] {
    return func(yield func(Item) bool) {
        ch := make(chan Item, 100)
        go func() {
            defer close(ch)
            for {
                item, ok := src.Read(ctx)
                if !ok { return }
                select {
                case ch <- item:
                case <-ctx.Done():
                    return
                }
            }
        }()
        for item := range ch {
            if !yield(item) {
                // Caller broke; signal producer to stop
                // (closing ch from the receive side is wrong; use ctx)
                return
            }
        }
    }
}

Note the subtle bug above — if yield returns false, we return, but the producer goroutine keeps reading and may block on ch <- item forever. The fix: pair the goroutine with a cancellable context.

func produceAndIterate(ctx context.Context, src DataSource) iter.Seq[Item] {
    return func(yield func(Item) bool) {
        innerCtx, cancel := context.WithCancel(ctx)
        defer cancel()

        ch := make(chan Item, 100)
        go func() {
            defer close(ch)
            for {
                item, ok := src.Read(innerCtx)
                if !ok { return }
                select {
                case ch <- item:
                case <-innerCtx.Done():
                    return
                }
            }
        }()
        for item := range ch {
            if !yield(item) {
                return  // defer cancel() stops producer
            }
        }
    }
}

Now the producer dies on consumer-break. Goroutine leak prevented.

10. Memory considerations: lazy vs materialised¶

The iterator pattern's reason for being is laziness. Materialising defeats it. But materialising is sometimes the right answer.

10.1 The lazy default¶

Iterators should produce one element at a time, on demand. Memory usage is O(1) regardless of dataset size — only the current element + iteration state.

// Lazy: streams a 10 GB file, ~64 KB peak memory
for line := range LinesFromFile("/var/log/huge.log") {
    if strings.Contains(line, "ERROR") {
        process(line)
    }
}

10.2 When materialisation is justified¶

• Small datasets. If you know the result fits in tens of MB, materialise. Loops over slices are cleaner than range-over-func, and benchmarks show ~2x speedup.
• Random access required. Sorting, indexing, repeated traversal — you need a slice.
• Cross-goroutine handoff with bounded data. Easier to ship a slice across a channel than an iterator.
• Caching the result. Same query, multiple callers — materialise once, share the slice.

10.3 When materialisation is a bug¶

• Unbounded sources. Streams, watch APIs, log tails — never slices.Collect these.
• Large datasets. A million rows from a database, each row 1 KB = 1 GB resident memory. Process streaming.
• Long-running services. Each materialisation is a transient allocation; GC reclaims it eventually. But while it's live, RSS is high. For services with tight memory budgets (containers with 256 MB), this is the difference between healthy and OOM-killed.

10.4 Mixing styles: bounded materialisation¶

When you need slice-like operations but want bounded memory:

// Process in batches of N
func Batched[T any](seq iter.Seq[T], n int) iter.Seq[[]T] {
    return func(yield func([]T) bool) {
        batch := make([]T, 0, n)
        for x := range seq {
            batch = append(batch, x)
            if len(batch) >= n {
                if !yield(batch) { return }
                batch = make([]T, 0, n)  // fresh slice; caller might keep it
            }
        }
        if len(batch) > 0 {
            yield(batch)
        }
    }
}

// Usage
for batch := range Batched(repo.AllRecords(ctx), 1000) {
    if err := db.BulkInsert(ctx, batch); err != nil {
        return err
    }
}