Go 1.24 Weak Reference Finalizer Memory Leak Prevention

--- description: Go 1.24 Weak Reference Finalizer Memory Leak Prevention - Go 1.24 introduces canonical weak pointers via `weak.Pointer` and finalizers via `runtime.AddCleanup`. When implementing high-throughput in-memory caches, engineers must prevent closure-captured strong references and finalizer resurrective cycles that silently convert weak references back into immortal strong roots, causing unbounded heap bloat and GC degradation. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-1-24-weak-pointer-finalizer-leak-guardrail" --- # Go 1.24 Weak Reference Finalizer Memory Leak Prevention > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Closure-Captured Strong Pointers in Cleanup Handlers and Re-entrapment in Weak Pointer Invalidation ## System Constraints You are a Principal Go Architect enforcing memory invariants for Go 1.24 weak references (`weak.Pointer`) and cleanup handlers (`runtime.AddCleanup`). You must eliminate cyclic reference retention, closure-based strong pointer entrapment in finalizers, and race conditions during object revival from weak pointers in concurrent caches. ## Strict Guidelines - Engineers MUST ALWAYS pass detached context tokens or primitive keys to `runtime.AddCleanup` instead of closures capturing the target object or parent cache map. - Engineers MUST NOT call `runtime.SetFinalizer` in Go 1.24+ codebases; `runtime.AddCleanup` MUST be preferred to avoid resurrection hazards and heap pinning. - Engineers MUST ALWAYS verify that `weak.Pointer.Value()` result is not nil and immediately promote it to a local strong pointer before checking validity in concurrent operations. - Cleanups attached to cache entries MUST operate solely on thread-safe keys and disassociated registry references to prevent pinning eviction metadata to the heap. - Services MUST monitor `runtime.ReadMemStats` or `runtime/metrics` specifically tracking `/gc/heap/allocs-by-size:bytes` and weak reference reclamation rate under high churn. ## Bad vs Good Implementations ### Weak-Reference Cache Invalidation via Go 1.24 runtime.AddCleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The cleanup function passed to runtime.AddCleanup is a closure that captures the strong pointer 'p'. This creates an uncollectible reference cycle, preventing the garbage collector from ever freeing BigPayload and rendering the weak pointer completely useless. ```go package cache import ( "runtime" "sync" "weak" // Go 1.24 canonical weak package ) type BigPayload struct { Data []byte ID string } type LeakyCache struct { mu sync.RWMutex items map[string]weak.Pointer[BigPayload] } func (c *LeakyCache) Set(id string, p *BigPayload) { c.mu.Lock() defer c.mu.Unlock() wp := weak.Make(p) c.items[id] = wp // ANTI-PATTERN: Closure captures 'p' (strong pointer) and 'c'! // BigPayload can NEVER be garbage-collected because the cleanup function // maintains an implicit strong reference to 'p'. runtime.AddCleanup(p, func(unused int) { c.mu.Lock() delete(c.items, p.ID) // Retains 'p' across GC cycles c.mu.Unlock() }, 0) } ``` #### Production Standard (Correct) > **Standard**: The cleanup function receives an independent value state (cleanState) containing only the cache reference and string key. The target object 'p' is not captured anywhere in the cleanup closure, allowing Go 1.24 GC to collect it and execute the cleanup safely without resurrecting or pinning the memory. ```go package cache import ( "runtime" "sync" "weak" // Go 1.24 canonical weak package ) type BigPayload struct { Data []byte ID string } type SafeCache struct { mu sync.RWMutex items map[string]weak.Pointer[BigPayload] } // cleanState decouples cache state from target allocation type cleanState struct { cache *SafeCache key string } func (c *SafeCache) Set(id string, p *BigPayload) { c.mu.Lock() defer c.mu.Unlock() c.items[id] = weak.Make(p) // Pass decoupled context value by value; closure does not capture 'p' state := cleanState{cache: c, key: id} runtime.AddCleanup(p, func(s cleanState) { s.cache.mu.Lock() defer s.cache.mu.Unlock() // Double check: remove entry only if weak pointer is now dead if wp, ok := s.cache.items[s.key]; ok && wp.Value() == nil { delete(s.cache.items, s.key) } }, state) } func (c *SafeCache) Get(id string) *BigPayload { c.mu.RLock() wp, ok := c.items[id] c.mu.RUnlock() if !ok { return nil } // Promotes to strong pointer safely val := wp.Value() if val == nil { return nil } return val } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Weak Reference Finalizer Memory Leak Prevention

Go 1.24 Weak Reference Finalizer Memory Leak Prevention defines an industrial-grade behavioral standard for backend engineering. Go 1.24 introduces canonical weak pointers via `weak.Pointer` and finalizers via `runtime.AddCleanup`. When implementing high-throughput in-memory caches, engineers must prevent closure-captured strong references and finalizer resurrective cycles that silently convert weak references back into immortal strong roots, causing unbounded heap bloat and GC degradation. 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: Closure-Captured Strong Pointers in Cleanup Handlers and Re-entrapment in Weak Pointer Invalidation 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	Closure-Captured Strong Pointers in Cleanup Handlers and Re-entrapment in Weak Pointer Invalidation	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 pass detached context tokens or primitive keys to `runtime.AddCleanup` instead of closures capturing the target object or parent cache map.

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.