design: DESTROY and weaken() implementation plan

[fglock]

Summary

Design document for implementing DESTROY support for blessed objects and weaken()/isweak()/unweaken() for weak references. This is a plan document only — no code changes.

Key Design Decisions

• Targeted reference counting on RuntimeBase — only blessed objects whose class defines DESTROY, not all objects
• Four-state refCount field: -1 = untracked, 0 = tracked with zero counted containers (fresh from bless), >0 = N strong references, Integer.MIN_VALUE = destroyed. Eliminates the need for a separate destroyCalled boolean
• refCount=0 at bless time — the bless-time RuntimeScalar is a temporary that travels through the return chain without cleanup; not counting it eliminates overcounting for the common single-boundary return pattern
• Post-assignment DESTROY ordering — old referent is saved before assignment, decremented after, so DESTROY sees the new variable state (correct Perl 5 semantics)
• Zero overhead for the hot path — set() fast path (int/double/string/undef) is untouched; refcount logic lives only in setLarge() slow path
• One integer comparison per reference assignment for untracked objects (99% of refs)
• GC safety net via Cleaner sentinel pattern for escaped references
• External WeakRefRegistry — no per-scalar memory cost for weak ref tracking
• Zero additional memory — refCount field fits in existing alignment padding on RuntimeBase

Bytecode Trace Findings (v3.0)

Disassembly and interpreter tracing revealed:

• Both JVM and interpreter backends share the same runtime methods (addToScalar() -> set() -> setLarge())
• return $obj wraps the SAME RuntimeScalar in RuntimeList (no copy through return chain)
• Copies only occur at my declarations via addToScalar(target) -> target.set(this) -> setLarge()
• Return epilogue does NOT call emitScopeExitNullStores — no cleanup for my variables on return path
• emitScopeExitNullStores IS emitted for all normal scope exits (blocks, loops, if/else)

Alternatives Considered

Approach	Verdict
Full refcounting on ALL objects (like Perl 5)	Rejected: too expensive
GC-only (Cleaner, no refcounting)	Rejected: wrong timing, proxy problem (DestroyManager attempt)
Scope-based without refcounting (PR #450 style)	Rejected: 20+ failures for returned objects
Compile-time escape analysis	Rejected: impossible to do perfectly
Explicit destructor registration	Rejected: not Perl-compatible
Targeted refcounting + Cleaner safety net	Chosen

Implementation Phases

1. Infrastructure — add refCount field (default -1), create DestroyDispatch class
2. Scalar refcounting + DESTROY — hook setLarge(), undefine(), scopeExitCleanup(), delete(); init refCount=0 at bless
3. weaken/isweak/unweaken — external registry, proper semantics
4. GC safety net — Cleaner sentinel pattern
5. Global destruction — ${^GLOBAL_PHASE}, shutdown hook
6. Collection cleanup (optional) — deterministic DESTROY for arrays/hashes at scope exit

What is Blocked Without This

• Moo/Moose accessor tests (isweak() always false)
• POE::Wheel event loop hangs (DESTROY never fires)
• File::Temp, IO::Handle, Net::SMTP resource leaks
• Test2/Test::Builder circular ref management
• ~20+ bundled modules with DESTROY methods that never fire

Prior Art

• PR WIP: DESTROY support for blessed objects #450 (WIP, open) — eager DESTROY without refcounting, caused 20+ test failures
• DestroyManager (reverted) — GC-based with proxy objects, fundamentally broken
• ioHolderCount on RuntimeGlob — existing targeted refcount pattern that proves this approach works

Test plan

• Design review
• Plan approved for implementation

Generated with Devin