Go 1.24 Weak Pointer & Finalizer-Free Cache Lifetime Invariants

--- description: Go 1.24 Weak Pointer & Finalizer-Free Cache Lifetime Invariants - Enforces modern Go 1.24+ memory reclamation standards using weak.Pointer and runtime.AddCleanup for high-concurrency caches. Prevents garbage collector multi-phase sweep delays and Stop-The-World (STW) latency spikes caused by legacy runtime.SetFinalizer object resurrection and leaking strong cache references. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-1-24-weak-pointer-cache-lifetime-invariants" --- # Go 1.24 Weak Pointer & Finalizer-Free Cache Lifetime Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Retaining strong references in cache indices or using runtime.SetFinalizer causing GC resurrection loops and tail-latency spikes ## System Constraints You are a Principal Go Architect enforcing Go 1.24 memory management invariants. Ban runtime.SetFinalizer in caching layers and mandate weak.Pointer with runtime.AddCleanup to guarantee single-pass garbage collection without object resurrection. ## Strict Guidelines - Engineers MUST ALWAYS use `weak.Pointer[T]` via `weak.Make` for canonicalization maps, intern tables, and non-owning cache indices in Go 1.24+. - Engineers MUST NEVER use `runtime.SetFinalizer` for cache lifetime tracking or memory eviction; finalizers resurrect objects and postpone deallocation across multiple GC cycles. - Engineers MUST ALWAYS verify that `weakPtr.Value()` is non-nil and validate pointer identity atomically before serving cached structures to callers. - Services MUST register disassociated cleanup callbacks using `runtime.AddCleanup` when external descriptors (such as mmap or C-pointers) require finalization upon object unreachable state. - Code SHOULD implement periodic or amortized sweeps to remove expired `weak.Pointer` entries whose `.Value()` resolves to `nil` from cache storage maps. ## Bad vs Good Implementations ### In-Memory Interning Cache: Finalizer Resurrection vs. Go 1.24 Weak Pointers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using runtime.SetFinalizer introduces object resurrection: the GC cannot collect LargeEntry during the sweep because it must schedule the finalizer goroutine. Moreover, the finalizer closure captures 'c' and creates reference cycles, holding memory pinned and triggering multi-pass GC pauses under heavy write loads. ```go package cache import ( "runtime" "sync" ) type LargeEntry struct { ID string Data []byte } type Cache struct { mu sync.RWMutex items map[string]*LargeEntry } func (c *Cache) GetOrSet(id string, supplier func() *LargeEntry) *LargeEntry { c.mu.Lock() defer c.mu.Unlock() if entry, found := c.items[id]; found { return entry } entry := supplier() c.items[id] = entry // ANTI-PATTERN: runtime.SetFinalizer resurrects entry into GC root set, // delaying reclamation across multiple GC passes and spiking p99 latency. runtime.SetFinalizer(entry, func(e *LargeEntry) { c.mu.Lock() delete(c.items, e.ID) c.mu.Unlock() }) return entry } ``` #### Production Standard (Correct) > **Standard**: Go 1.24 weak.Pointer allows the cache to retain a non-owning reference. When caller goroutines drop strong references, LargeEntry is reclaimed in a single GC pass. runtime.AddCleanup passes only the identifier 'id' to the cleanup hook without resurrecting LargeEntry or pinning it to the heap. ```go package cache import ( "runtime" "sync" "weak" ) type LargeEntry struct { ID string Data []byte } type WeakCache struct { mu sync.RWMutex items map[string]weak.Pointer[LargeEntry] } func NewWeakCache() *WeakCache { return &WeakCache{items: make(map[string]weak.Pointer[LargeEntry])} } func (c *WeakCache) GetOrSet(id string, supplier func() *LargeEntry) *LargeEntry { c.mu.Lock() defer c.mu.Unlock() if wp, found := c.items[id]; found { if entry := wp.Value(); entry != nil { return entry } // Expired weak pointer; purge dead key slot delete(c.items, id) } entry := supplier() wp := weak.Make(entry) c.items[id] = wp // Attach finalizer-free cleanup without resurrecting the object runtime.AddCleanup(entry, func(k string) { c.mu.Lock() if existing, exists := c.items[k]; exists && existing.Value() == nil { delete(c.items, k) } c.mu.Unlock() }, id) return entry } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Weak Pointer & Finalizer-Free Cache Lifetime Invariants

Go 1.24 Weak Pointer & Finalizer-Free Cache Lifetime Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces modern Go 1.24+ memory reclamation standards using weak.Pointer and runtime.AddCleanup for high-concurrency caches. Prevents garbage collector multi-phase sweep delays and Stop-The-World (STW) latency spikes caused by legacy runtime.SetFinalizer object resurrection and leaking strong cache references. 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: Retaining strong references in cache indices or using runtime.SetFinalizer causing GC resurrection loops and tail-latency spikes 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	Retaining strong references in cache indices or using runtime.SetFinalizer causing GC resurrection loops and tail-latency spikes	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 use `weak.Pointer[T]` via `weak.Make` for canonicalization maps, intern tables, and non-owning cache indices in Go 1.24+.

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.