Go 1.24 iter.Pull2 Mandatory Teardown and Goroutine Lifecycle Boundary

--- description: Go 1.24 iter.Pull2 Mandatory Teardown and Goroutine Lifecycle Boundary - Enforces strict deferred invocation of the teardown closure returned by Go 1.24 iter.Pull and iter.Pull2 conversions. Converting push-based sequence iterators into pull consumers instantiates an underlying coroutine pair; failure to execute the stop closure on early breaks, errors, or panics permanently leaks producer goroutines. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-iter-pull-goroutine-leak-boundary" --- # Go 1.24 iter.Pull2 Mandatory Teardown and Goroutine Lifecycle Boundary > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Omitting Immediate defer stop() on iter.Pull/iter.Pull2 Producer Coroutines ## System Constraints You are a Principal Software Architect enforcing Go 1.24 Pull Iterator (iter.Seq / iter.Seq2) Goroutine Leak Boundary standards. Mandate immediate deferred cleanup on pull iterator pairs, forbid the blank identifier discard of stop closures, and prioritize idiomatic push-based range loops. ## Strict Guidelines - Engineers MUST ALWAYS pair calls to iter.Pull or iter.Pull2 immediately with an unconditional 'defer stop()' statement on the subsequent line. - Engineers MUST NOT discard the stop closure using the blank identifier (e.g., 'next, _ := iter.Pull(seq)'), which permanently orphans producer goroutines on early break or panic. - Code SHOULD prefer standard push-based 'for k, v := range seq' loops unless interleaved traversal, parallel zip operations, or manual stepping is strictly required. - Services MUST ensure that the stop closure is invoked before function exit even if the pull loop encounters early break, return, or context cancellation. - Components NEVER share the resulting 'next' and 'stop' closures across concurrent goroutines without external mutual exclusion, as pull iterators are strictly thread-unsafe. ## Bad vs Good Implementations ### Pull Iterator Goroutine Leakage vs Guaranteed Teardown #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: iter.Pull2 converts push iteration to pull by spawning an internal coroutine runtime thread. Exiting via context cancellation or predicate match without calling stop() leaves the hidden producer goroutine suspended in memory forever. ```go package stream import ( "context" "errors" "iter" ) func FindFirstMatch[K comparable, V any]( ctx context.Context, seq iter.Seq2[K, V], predicate func(K, V) bool, ) (K, V, error) { // ANTI-PATTERN: Discarding or neglecting stop() leaks the underlying // coroutine created by iter.Pull2 if an early return triggers. next, stop := iter.Pull2(seq) // Missing defer stop()! for { if err := ctx.Err(); err != nil { // Producer goroutine blocked indefinitely on yield synchronization channel var zeroK K var zeroV V return zeroK, zeroV, err } k, v, ok := next() if !ok { break } if predicate(k, v) { // Leaks goroutine: loop terminated without notifying iterator producer return k, v, nil } } stop() // Only runs on full exhaustion; missed on early return! var zeroK K var zeroV V return zeroK, zeroV, errors.New("not found") } ``` #### Production Standard (Correct) > **Standard**: Placing 'defer stop()' directly after iter.Pull2 guarantees that the internal runtime coroutine receives the termination signal immediately when FindFirstMatch exits, safely releasing all resources. ```go package stream import ( "context" "errors" "iter" ) func FindFirstMatch[K comparable, V any]( ctx context.Context, seq iter.Seq2[K, V], predicate func(K, V) bool, ) (K, V, error) { next, stop := iter.Pull2(seq) // INVARIANT: stop() MUST be deferred immediately to ensure the coroutine // is terminated regardless of return path, early break, or panic. defer stop() for { if err := ctx.Err(); err != nil { var zeroK K var zeroV V return zeroK, zeroV, err } k, v, ok := next() if !ok { break } if predicate(k, v) { return k, v, nil } } var zeroK K var zeroV V return zeroK, zeroV, errors.New("not found") } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 iter.Pull2 Mandatory Teardown and Goroutine Lifecycle Boundary

Go 1.24 iter.Pull2 Mandatory Teardown and Goroutine Lifecycle Boundary defines an industrial-grade behavioral standard for backend engineering. Enforces strict deferred invocation of the teardown closure returned by Go 1.24 iter.Pull and iter.Pull2 conversions. Converting push-based sequence iterators into pull consumers instantiates an underlying coroutine pair; failure to execute the stop closure on early breaks, errors, or panics permanently leaks producer goroutines. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Omitting Immediate defer stop() on iter.Pull/iter.Pull2 Producer Coroutines Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Omitting Immediate defer stop() on iter.Pull/iter.Pull2 Producer Coroutines	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS pair calls to iter.Pull or iter.Pull2 immediately with an unconditional 'defer stop()' statement on the subsequent line.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.