Go iter.Pull2 的 Stop 怎样提前结束迭代并释放资源

我在把一个键值对迭代器改成“找到目标就停”的写法时，最容易漏掉的不是 next()，而是 stop()。Go 的 iter.Pull2 会把 iter.Seq2 这种 push 风格迭代器转换成逐个取值的 next 和负责结束迭代的 stop。只要调用方可能提前返回，就应该在拿到这两个函数后立即写下 defer stop()。

官方地址：https://pkg.go.dev/iter#Pull2

一句话判断：完整读到 next 返回 false 时，序列已经自然结束；如果因为命中条件、错误或上游取消而提前离开，就必须让 stop 有机会执行，让迭代器完成收尾。stop 可以重复调用，next 在结束后会返回键和值的零值以及 false。

先看懂 Pull2 返回的两个函数

iter.Seq2[K, V] 表示每次向 yield 交付一对值，常见形态是键和值。iter.Pull2 把它转换为 next func() (K, V, bool) 与 stop func()：调用方负责主动取下一对数据，也负责在不再继续读取时发出停止信号。

package main

import (
    "fmt"
    "iter"
)

func pairs() iter.Seq2[string, int] {
    // Seq2 只描述键值对如何被逐个交给 yield。
    return func(yield func(string, int) bool) {
        for _, item := range []struct {
            key   string
            value int
        }{{"ready", 1}, {"retry", 3}, {"done", 9}} {
            // yield 返回 false 时，上游应停止继续提供数据。
            if !yield(item.key, item.value) {
                return
            }
        }
    }
}

func main() {
    // Pull2 把 push 风格的 Seq2 转成 next 与 stop 两个控制点。
    next, stop := iter.Pull2(pairs())
    defer stop()

    key, value, ok := next()
    if !ok {
        fmt.Println("序列为空")
        return
    }
    fmt.Println(key, value)
}

这里的 defer stop() 不是为了让代码看起来完整，而是给每个提前退出路径留一条收尾通道。只要没有把 next 和 stop 交给多个协程同时调用，这个结构就能覆盖正常返回、错误返回和后续新增的条件分支。

触发信号：命中一条记录后不再继续读取

把迭代器用于配置查找、索引扫描或流式解析时，常见触发信号是“已经找到目标”。这时继续把剩余数据读完，既没有业务价值，还可能让上游继续持有文件、网络流或其他资源。Pull2 的价值就是把这个决策点交给调用方。

func findValue(seq iter.Seq2[string, int], wanted string) (int, bool) {
    // 只在当前调用协程中消费 next 和 stop，避免并发调用同一组函数。
    next, stop := iter.Pull2(seq)
    defer stop()

    for {
        key, value, ok := next()
        if !ok {
            // false 表示自然到达序列末尾，value 此时是零值。
            return 0, false
        }
        if key == wanted {
            // 命中后立即返回，defer 会负责通知迭代器收尾。
            return value, true
        }
    }
}

这个函数的关键不是循环，而是返回前仍然保留了 stop。如果未来在循环里增加权限判断、解析错误或上游取消分支，它们也会共享同一条清理路径。

快速判断：完整消费和提前结束要分开

当 next 返回 false 时，Pull2 已经知道序列没有更多值；官方文档允许之后再次调用 next，仍会得到零值和 false。但这不等于所有调用场景都可以省略 stop。判断标准可以压缩成下面这张表：

处理步骤：把 Stop 放在资源链的最外层

我更倾向于把 stop 放在拿到 next 后的下一行，而不是等到某个分支里再补。这样写有三个好处：读者一眼能看到生命周期，异常或新增分支不容易漏清理，后续把函数改成返回错误时也不用重排资源管理。

func firstPositive(seq iter.Seq2[string, int]) (string, int, error) {
    // 创建拉取接口后立即登记清理责任。
    next, stop := iter.Pull2(seq)
    defer stop()

    for {
        key, value, ok := next()
        if !ok {
            // 没有匹配项时返回明确结果，零值不代表有效记录。
            return "", 0, fmt.Errorf("没有找到正数记录")
        }
        if value > 0 {
            // 提前返回仍然会执行 stop，避免上游停在半途。
            return key, value, nil
        }
    }
}

如果业务确实需要保留未消费的上游数据，也要把“谁拥有继续消费权”写进接口约定。不要把 next 返回给外层、把 stop 留在内层，否则调用责任会被拆开，异常路径很难判断谁负责收尾。

回滚路径：发现并发误用时先收回控制权

next 和 stop 不能被多个协程同时调用。若排查时发现它们被放进共享结构，优先把拉取动作收回一个拥有明确生命周期的调用函数，再通过通道或普通返回值把结果交给其他协程。不要靠“多包一层锁”就默认语义已经安全，因为上游迭代器的收尾顺序仍然需要由同一个消费方负责。

func consumeOne(seq iter.Seq2[string, int]) (string, int, bool) {
    // next 与 stop 的所有调用都留在当前函数，结果只通过返回值交给外层。
    next, stop := iter.Pull2(seq)
    defer stop()

    key, value, ok := next()
    if !ok {
        // 读到末尾时显式返回 false，避免把键和值的零值当成数据。
        return "", 0, false
    }
    return key, value, true
}

这条回滚路径的重点是缩小所有权，而不是增加更多并发控制。只要一个函数同时掌握 next 和 stop，资源归属就比较容易复查。

告警确认与复盘清单

• 如果提前返回，确认同一作用域中存在 defer stop()，而不是只在成功分支调用。
• 如果 ok 为 false，把键和值当作零值处理，不把它们当成一条有效记录。
• 如果需要再次调用 stop，不用额外设计幂等包装；官方契约允许重复调用。
• 如果迭代器内部发生 panic，保留原有 panic 传播语义，不要在文章示例中伪造恢复结果。
• 如果调用跨越协程边界，先重构消费所有权，再决定是否需要通道传输结果。

我的结论

对 iter.Pull2 来说，next 负责“取哪一对值”，stop 负责“什么时候不再取”。真正稳妥的写法不是等命中条件后临时补清理，而是在创建 Pull2 后马上登记 defer stop()，然后让所有退出路径共享它。完整消费、提前返回和并发误用是三个需要分开判断的边界，掌握这三个边界，Pull2 就能成为可控的适配层，而不是隐藏的资源悬挂点。

相关问题

调用 next 读到 false 后还需要调用 stop 吗？

自然结束后再次调用 stop 是合法的。工程代码通常仍保留 defer stop()，这样完整消费和提前退出使用同一套生命周期结构。

stop 调用两次会不会出错？

官方契约允许重复调用 stop，也允许在 next 已返回 false 后调用。不要因此省略统一的 defer 清理。

可以把 next 放到另一个协程里吗？

不要让 next 和 stop 被多个协程同时调用。更稳妥的方式是让一个消费函数拥有这两个函数，再通过返回值或通道交付已经取出的数据。