Go 1.24 Range-Over-Func Pull Iterator Defer Cleanup and Heap Leak Elimination

--- description: Go 1.24 Range-Over-Func Pull Iterator Defer Cleanup and Heap Leak Elimination - Mandates strict lifecycle management and explicit cleanup semantics for Go 1.24 range-over-func pull iterators created via iter.Pull and iter.Pull2. Eliminates coroutine runtime leaks, goroutine starvation, and high-frequency heap escapes during early breaks or consumer errors in streaming ingest engines. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-range-over-func-pull-iterator-cleanup-guardrail" --- # Go 1.24 Range-Over-Func Pull Iterator Defer Cleanup and Heap Leak Elimination > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Discarding Pull Iterator Stop Closures Leading to Goroutine and Coroutine Resource Starvation ## System Constraints You are a Principal Go Systems Architect enforcing strict resource management for Go 1.24 iterators. Range-over-func pull iterators (iter.Pull, iter.Pull2) synthesize an internal coroutine paired with the consumer. If the consumer aborts iteration before next returns false, the stop closure MUST be executed to resume the yielding coroutine and run deferred cleanup blocks. You must mandate immediate deferred stop() execution, prohibit cross-iteration pointer capture of transient yielded payloads, and reject naked returns or breaking loops on pull iterators without explicit termination. ## Strict Guidelines - Engineers MUST ALWAYS invoke 'defer stop()' immediately following any call to iter.Pull or iter.Pull2, regardless of whether the loop is expected to run to completion. - Engineers MUST NOT retain direct references or pointers to transient memory buffers yielded by iterators without executing a deep-copy or clone operation. - Code SHOULD prefer push iterators (standard range-over-func syntax 'for k, v := range seq') over pull iterators unless interlocking or multi-stream consumption explicitly requires manual stepping. - Services MUST ensure that iterator producing functions clean up underlying I/O resources (e.g., io.Closer, net.Conn, database rows) in deferred routines executed upon yield returning false. - Components NEVER capture loop variables or yielded memory pointers in background goroutines without defensive allocation copies. ## Bad vs Good Implementations ### Go 1.24 iter.Pull2 Missing Stop Deferral on Early Exit #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If 'idx >= limit' triggers, the function returns without calling stop(). Go 1.24 pull iterators run on synthesized coroutines; omitting stop() causes the yielding coroutine to remain blocked forever, leaking its stack, open file descriptors, and buffered channel allocations. ```go package streaming import ( "context" "fmt" "iter" ) // ProcessBatches consumes events until a threshold is hit. // ANTI-PATTERN: Omits 'defer stop()' on iter.Pull2, leaking the producer coroutine on early break. func ProcessBatches(ctx context.Context, seq iter.Seq2[int, *StreamBuffer], limit int) ([]*StreamBuffer, error) { next, stop := iter.Pull2(seq) // Missing defer stop() here creates a coroutine leak if early exit occurs var collected []*StreamBuffer for { idx, buf, ok := next() if !ok { stop() break } if idx >= limit { // Early return without calling stop() starves producer goroutine return nil, fmt.Errorf("limit exceeded: %d", limit) } // Direct pointer capture anchors iterator transient buffer to the heap collected = append(collected, buf) } return collected, nil } ``` #### Production Standard (Correct) > **Standard**: The 'defer stop()' call guarantees that the yielding coroutine executes its cleanup defer chain even when returning early due to error or context cancellation. Value cloning prevents heap-retaining the iterator's mutable scratch buffer. ```go package streaming import ( "context" "fmt" "iter" ) // ProcessBatches consumes events with deterministic cleanup and safe memory copying. func ProcessBatches(ctx context.Context, seq iter.Seq2[int, *StreamBuffer], limit int) ([]StreamBuffer, error) { next, stop := iter.Pull2(seq) // Invariant: stop() MUST be deferred immediately to ensure the producer coroutine unwinds defer stop() var collected []StreamBuffer for { select { case <-ctx.Done(): return nil, ctx.Err() default: } idx, buf, ok := next() if !ok { break } if idx >= limit { return nil, fmt.Errorf("limit exceeded: %d", limit) } if buf != nil { // Perform explicit value copy to decouple life cycle from iterator scratchpad collected = append(collected, buf.Clone()) } } return collected, nil } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Range-Over-Func Pull Iterator Defer Cleanup and Heap Leak Elimination

Go 1.24 Range-Over-Func Pull Iterator Defer Cleanup and Heap Leak Elimination defines an industrial-grade behavioral standard for backend engineering. Mandates strict lifecycle management and explicit cleanup semantics for Go 1.24 range-over-func pull iterators created via iter.Pull and iter.Pull2. Eliminates coroutine runtime leaks, goroutine starvation, and high-frequency heap escapes during early breaks or consumer errors in streaming ingest engines. 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: Discarding Pull Iterator Stop Closures Leading to Goroutine and Coroutine Resource Starvation 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	Discarding Pull Iterator Stop Closures Leading to Goroutine and Coroutine Resource Starvation	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 invoke 'defer stop()' immediately following any call to iter.Pull or iter.Pull2, regardless of whether the loop is expected to run to completion.

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.