Status: exercised by the runtime suite (904 tests, 0 failures); the flag-driven stress
scenarios below are still unrun
Patch: v8_resurrecting_finalizers.patch — 6 files, +184/-3,
against V8 14.9.207.39 (branch-heads/14.9). The patch and the pinned
version live in NativeScript/v8-buildscripts.
Built clean for arm64-iphonesimulator (lite mode, no sandbox, no pointer compression).
Also applies unmodified to 14.4, 14.5 and 14.6; on 14.8+ the heap-symbols.h hunk needs
re-alignment (whitespace only).
ObjectManager::FinalizerCallback (ObjectManager.mm:34)
reads the dying object's internal fields and may refuse disposal by re-arming its
handle (ClearWeak() + SetWeak()). That requires v8::WeakCallbackType::kFinalizer,
which upstream removed one day after our pinned 10.3.22:
| Change | Commit | Landed in |
|---|---|---|
kFinalizer API removed |
2ae2aa92 |
~10.3.24 |
| GC machinery removed | cb92ed09 |
~10.3.27 |
| Node state machine simplified | 015632a0 |
~10.3.46 |
On stock 14.x the pattern is not merely unsupported but fatal: the handle slot is zapped
to 0xCA11 before the callback runs, and CHECK_WITH_MSG(Node::FREE == node->state(), ...)
crashes if a callback re-arms instead of resetting. Re-arming a kParameter handle is not
a workaround — that callback only fires once V8 has already committed to the object's death.
This patch exists to buy time: it keeps the current ownership semantics working on a modern V8 while the reachability-based redesign in RESURRECTION_TO_REACHABILITY.md is proven out. It is deliberately narrower than what upstream removed.
Upstream supported finalizers in both young and full GC. This patch does not.
- Young GC (scavenger + minor mark-sweep): finalizer handles are strong roots. They are
visited by
IterateYoungStrongAndDependentRoots()and skipped byProcessWeakYoungObjects(). A young collection never finalizes; it just promotes. Collection is deferred to the next full GC. - Full GC: the keep-alive pass runs, objects are queued, and callbacks fire after the pause.
This is what deletes the hardest part of a faithful revert. Upstream's young-generation
hooks lived in MinorMarkCompactCollector, which no longer exists (replaced by
minor-mark-sweep.cc), so a faithful port would have had to re-derive them. Both young
collectors call the same two GlobalHandles entry points, so treating finalizers as strong
is one change covering both, and scavenger.cc / minor-mark-sweep.cc are untouched.
1. Keep-alive (mark-compact.cc, end of MarkLiveObjects()). After the final marking
closure, IdentifyDeadFinalizerHandles() queues every finalizer handle whose object is
unmarked, IterateFinalizerHandlesAsRoots() visits them, and the marking closure
(MarkTransitiveClosureFixpoint(), falling back to MarkTransitiveClosureLinear())
re-drains the worklists.
2. Pending bit (global-handles.cc). A queued node carries a pending_finalizer flag
(bit 5 of flags_, previously unused) and is added to pending_finalizers_. While set, the
node is visited by IterateStrongRoots(), and re-identification is suppressed. The bit —
not the queue — is the source of truth: entries are re-checked before invocation, because GC
epilogue callbacks run before the drain and may reset a queued handle out from under it.
3. Post-pause invocation (GlobalHandles::PostGarbageCollectionProcessing). Callbacks
run from the GC epilogue via InvokeExternalCallbacks — not from the first-pass phantom
path, which runs in-pause and forbids allocation. The drain is wrapped in
AllowJavascriptExecution; see below for why that is required rather than incidental.
4. Lifting DisallowJavascriptExecution. Heap::CollectGarbage holds one across the
entire collection, epilogue included — heap.cc, "JS execution is not allowed in any of
the callbacks" — and InvokeExternalCallbacks() re-enables allocation
(AllowGarbageCollection) but deliberately not JS, asserting on entry that JS is disallowed.
Entering JS from a callback therefore hits
// src/execution/execution.cc, Invoke()
if (!AllowJavascriptExecution::IsAllowed(isolate)) {
GRACEFUL_FATAL("Invoke in DisallowJavascriptExecutionScope");
}and aborts the process. This is a behavioural change from 10.3, where
InvokeSecondPassPhantomCallbacks() ran under an explicit AllowJavascriptExecution.
The runtime depends on the 10.3 behaviour and cannot avoid it:
ObjectManager::FinalizerCallback → DisposeValue → [target release] runs -dealloc, and
any JS-backed override that teardown reaches — a JS UIView subclass being removed from its
superview, a delegate, a block — re-enters JS through ArgConverter::MethodCallback. So the
patch lifts the scope around the finalizer drain only: InvokeSecondPassPhantomCallbacks()
below it still asserts JS is disallowed, so the scope is closed before it runs.
Both scopes are live in release builds. Only the …DebugOnly aliases generated in
assert-scope.h compile away, and neither Heap::CollectGarbage nor this patch uses those.
The Android runtime shares this patch but does not depend on the lift: its finalizer makes a
single runtime-internal JNI call (makeInstanceWeakAndCheckIfAlive) and Java has no
synchronous destructor that could re-enter JS.
The public enum gains a third value; api.cc needs no change (it passes the type through,
and the only switch is in Node::MakeWeak).
These are the things that make it correct. Breaking any of them is a use-after-free, not a leak.
-
The keep-alive must run at the end of
MarkLiveObjects(), inside the cppgc atomic pause. Not inClearNonLiveReferences(). At the chosen point the cppgc marker is still live (CppHeap::FinishMarkingAndProcessWeakness()has not run), so the re-drained closure still pushes to cppgc viaVisitCppHeapPointer→AdvanceMarking. A resurrected wrapper whose JS properties reach cppgc-managed objects therefore marks correctly. Moving this block afterCollectGarbage:534silently drops those pushes and sweeps live cppgc objects. -
The keep-alive must precede all weakness processing. Everything that consumes liveness — phantom handles, ephemerons,
WeakRef/FinalizationRegistry, map-transition pruning, code flushing — lives inClearNonLiveReferences(), which runs after. Every such pass must observe the resurrected closure as live. -
The pending bit must never survive into a reallocated node. Cleared in
ClearImplFields()(release path),ClearWeakness()and bothMakeWeak()overloads (re-arm path). A freed node carries a zapped location; visiting it as a root would crash. -
A finalizer callback must reset or re-arm its handle. Enforced by
CHECK_WITH_MSGafter invocation. Doing neither leaves the handle rooted forever.
Two supporting facts, verified in 14.9 and worth re-checking on any upgrade: marking iterates
global handles via IterateStrongRoots (SkipRoot::kWeak), so pending nodes are protected
during a nested GC; root updating uses IterateAllRoots, a single pass over NORMAL||WEAK,
so a pending node's slot is updated exactly once after evacuation.
Finalizers run on whichever thread triggered the collection, and that can be any thread holding
the isolate's Locker — a JS function dispatched to a background queue included. An object that
first reached JS on the runtime's thread (ObjCDataWrapper/BlockWrapper::BornOnRuntimeThread,
recorded when the wrapper is built) is released on that thread: off it, ObjectManager queues
the native release ([object release], Block_release) and posts one event loop task to drain
the queue; the JS side is disposed immediately either way. The same applies to
__releaseNativeCounterpart called from such a thread: the wrapper is retired at once, the
object a loop turn later. Objects that first reached JS on another thread are released where the
collection runs, as are collection adapters, whose -dealloc retires the wrapper.
The queue needs no synchronization of its own: finalizers, __releaseNativeCounterpart, the
drain task, wrapper creation and teardown all hold the Locker. A new wrapper built for an object
whose release is still queued takes that release over (keeping the retain counts the extended
classes' swizzle reads exact). Teardown drains the queue inline, since the event loop has stopped
by then. For a worker, the runtime's thread is the worker's own thread, not the main thread.
While a release is queued the object is alive without a wrapper, where an inline release would
have deallocated it and zeroed the weak references to it. A native callback reaching it in that
window (a delegate method through a weak reference) builds a new wrapper, which takes the queued
release over: the JS override runs on a blank this, without the state the collected wrapper
held, and the object then lives as long as that new wrapper. Only an object that nothing but its
wrapper owned, collected off the runtime's thread, has this window.
- No
PENDINGstate, noNEAR_DEATHfor finalizers. 14.9'sNodeStateis 2 bits with all four values used; a separate flag bit avoids widening it, and keeps finalizer nodes out of theNEAR_DEATHaccounting inUpdateListOfYoungNodesImpl(). - Pending nodes are strong roots, not weak retainers. Upstream left a
NEAR_DEATHfinalizer node weak while its callback ran, which leaves the object unprotected against a GC nested inside the callback. Rooting it is stricter. ResetWeakNodeIfDead()reports finalizer handles alive rather thanUNREACHABLE(). Client isolates of a shared space get their ownIterateWeakRootsForPhantomHandles()pass (mark-compact.cc:3166) that the keep-alive does not cover. Reporting alive defers collection by a cycle in that exotic case instead of crashing.Node::PostGarbageCollectionProcessingkeeps upstream's name deliberately.tools/cfi/ignores.txtblocklists*GlobalHandles*PostGarbageCollectionProcessing*becauseweak_callback_is invoked on the wrong type. Renaming it breaks CFI builds.
IdentifyDeadFinalizerHandles() snapshots the dead set before IterateFinalizerHandlesAsRoots()
and the re-drain, so the queue is built against pre-resurrection marking. If two wrappers are
both JS-unreachable and one references the other, both are queued:
n1holdsn2; neither is reachable from a JS root, so both are queued.- The keep-alive marks
n1's whole closure —n2included — live, so nothing is swept. n2's callback runs first and disposes:[N2 release], wrapper deleted.n1's callback findsIsGcProtected()and re-arms.
n1 comes back holding a JS object whose native half is gone. DisposeValue does neuter the
husk (delete wrapper, then internal field 0 is overwritten), so it is not a dangling
BaseDataWrapper* — but consumers that read the field without checking, Pointer.cpp among
them, would read it as an External and dereference it. ObjC object husks get a per-isolate
tns::ReleasedReason Symbol in the field (tns::MarkReleased: collected, released explicitly
through __releaseNativeCounterpart, teardown, or a receiver lent to JS from -dealloc);
other wrapper types get Undefined. tns::GetValue only reads Externals, so both read as
"no wrapper". The reason is matched by identity, not as a number: URL, URLSearchParams,
URLPattern and MessagePort keep a raw aligned pointer in field 0, which reads back as a Smi
in builds without pointer compression.
This is not fixable by deferring the release or by re-checking liveness after the drain.
Every queued node is rooted by IterateFinalizerHandlesAsRoots() and treated as a strong
retainer for the rest of the cycle, so immediately after the GC every disposed object still
looks alive; the check cannot separate "alive because a referrer revived" from "alive because
it was rooted for its own finalization". Waiting a cycle does not converge either: n1 re-arms
weak, so the next IdentifyDeadFinalizerHandles() finds both unmarked again and re-queues the
same pair.
Nor is it fixable by making GcProtect() a strong root instead of a disposal veto. Disposal
here is driven by whether native still needs the object, not by JS reachability, and that is
precisely what lets a JS↔ObjC cycle collect at all: an unprotected object is released even
though surviving JS still references it. Turning protection into an opaque strong root would
convert every such cycle into a permanent leak.
The real fix is to stop expressing liveness with roots and express it by tracing — CppHeap,
v8::Object::Wrap/Unwrap, TracedReference and cppgc Trace(), which mark through the
embedder graph and so collect cross-heap cycles without resurrection. That is
RESURRECTION_TO_REACHABILITY.md. Note that the intermediate
option is gone: EmbedderRootsHandler::IsRoot(), which used to let an embedder declare a
TracedReference a root per-GC, no longer exists in 14.9 — only ResetRoot/TryResetRoot
remain.
Until then, the husk has defined behaviour: tns::GetValueOrReport() (Helpers) applies
the releasedObjectPolicy runtime config (ns:runtime, docs/ns-builtin-modules.md) on a
missing wrapper — default "report" no-ops the operation and fires the
releasednativeaccess global event with the touch site's stack; "throw" raises a
catchable JS ReferenceError — and every internal-field read that could otherwise see a
neutered field goes through it — Pointer.cpp's methods, ExtVector.cpp toString,
Interop::SetStructPropertyValue (both struct cases), MetadataBuilder::GetStructData and
both struct field accessors, the two InteropTypes.mm argument readers, and the
Reference.cpp accessors (SetValueCallback, GetWrappedPointer, GetDataPair → indexed
get/set, toString). Regression spec: "throws instead of crashing when touching a released
object through a resurrected parent" in GCFinalizerTests.js.
An ObjC object husk reaching native code where an object is expected used to fall through to a
DictionaryAdapter standing in for it (a released UIColor reached UIKit as one and raised
unrecognized selector). The ReleasedReason marker now catches it on those paths, through
tns::ReportReleasedObject() with the same policy: an argument (Interop::WriteValue) becomes
nil or throws before the call (tns::ThrowReleasedObject); a collection element (Interop::ToObject) becomes NSNull; a JS-implemented
method's return value (ArgConverter::SetValue) becomes nil (both report only, since native
code is on the stack); a method or property call on the husk (ArgConverter::Invoke, Proxy
receivers included) always throws. ns:runtime's getWrapperLifetimeStats() counts
resurrections, collections, explicit releases and released-object accesses. Specs:
WrapperLifetimeTests.js.
The app config "wrapperLifetime": { "mode": "rooted" } (WrapperLifetime.{h,mm}) avoids the
hazard instead of reporting it. An adopted wrapper never gets a kFinalizer callback: it is a
strong root while something other than the runtime retains its object and a phantom
(kParameter) weak handle otherwise. Strength is decided by a -retainCount scan in a
major-GC prologue, where flipping weakness is legal, and a wrapper is born strong and made
strong again whenever it crosses the JS/native boundary. A JS-unreachable holder therefore
stays rooted with its whole closure for as long as native code owns it, so nothing it reaches
is queued. Phantom callbacks only queue; the native objects are released later on the
runtime's thread, where JS may run. The extended classes' retain/release swizzle is not
installed in this mode. "scope": "extended" (default) roots only JS-extended instances;
"all" roots every ObjC wrapper except blocks and tagged pointers, at the cost of keeping
JS-referencing native cycles alive (ARC rules: break them with a WeakRef). Specs:
WrapperLifetimeModesTests.js; CI runs the default mode only, so the rooted expectations run
when the TestRunner app config selects "mode": "rooted".
The state-lost warnings (wrapperLifetimeWarnings) watch for resurrecting finalizers and stay
silent in the rooted and canary modes. Under "scope": "extended" in the rooted mode, a plain (not JS-extended) wrapper
is a phantom handle that a scavenge can collect, so JS properties set on plain objects that
native code owns are lost without a warning.
"mode": "canary" (WrapperLifetimeCanary.{h,mm}) is the portable variant, the shape Android and
the Node-API runtimes can implement. A wrapper in scope is a canary: a phantom-weak JS object
that dies with its JS references, releasing the runtime's retain through the same queue.
A masking named interceptor on the instance templates, with only a setter, a deleter and a
definer, mirrors JS properties into a null-prototype state object: each callback copies the
write into the state and declines, so V8 also applies it to the canary. Reads find real own
properties on the canary and never call into C++, so they cost what they cost on a plain
object. Being masking, the callbacks also see names the prototype chain has (a class method
rebound with this.onTap = this.onTap.bind(this), a field called copy, any
Object.defineProperty over a prototype name), and those are state like any other. The
setter classifies the prototype chain itself, because once it declines V8 adds a new name
to the canary without calling the definer: a name that resolves to an inherited accessor (a
native property, a JS getter/setter) or a read-only data member never becomes state. When the
first object on the chain with the name is a native class prototype that still records a
native setter for it, the handler runs that setter itself
(MetadataBuilder::TrySetNativeProperty, the same code as the accessor's setter callback).
Everything else is left to V8: a JS accessor, a read-only member, a native property without a
setter, and a name JS assigned or defined on that prototype, which its own setter and definer
interceptors forget for good. The state is rooted from its first write until the native
object is deallocated (or, with the default death signal below, until its
token is released), and stays the source of truth: a canary built later
for the same object, or the receiver a JS-implemented -dealloc runs with, gets the state's
properties copied onto it with their attributes and accessors. The costs, measured on a
Release simulator build: the handler is installed per template, so every write to any ObjC
wrapper goes through the setter, and V8 looks the name up again after it declines. Under
"extended", a plain wrapper's expando write takes about 64 ns instead of 17 and a native
property store about 200 ns instead of 120. On a canary, where the setter also classifies the
name, an expando write takes about 100 ns. A native property store took about 310 ns instead
of 125 (380 instead of 115 four prototypes up) while the handler left it to V8; running the
setter from the handler brings it from about 324 to 289 ns two prototypes up and from 396 to
324 for a UIButton tag four up (323 to 292 and 392 to 334 under "all", where a plain
UIButton's goes from 322 to 266). Building a canary for an object with state costs
about 330 ns per state property. Instances of JS-extended classes report their own
deallocation: the runtime gives each extended class a -dealloc that marks the instance's
records dying in every isolate, calls the superclass's (which can be a JS one the class
inherits, whose receiver still reads the state), and then retires them. For other objects it is
a compile-time choice (NS_CANARY_DEATH_SIGNAL in WrapperLifetimeCanary.mm): by default a
token associated with the
object reports it from its -dealloc, immediately and on any thread, but the ObjC runtime aborts
the process for a class that forbids associated objects (Swift actors, for one), and there is no
public query for that. The runtime checks the flag objc_setAssociatedObject aborts on
(RW_FORBIDS_ASSOCIATED_OBJECTS in the object's class's class_rw_t, reached through the
objc_debug_class_rw_data_mask libobjc exports for debuggers) before it attaches a token; an
object it flags, or whose class it cannot read, gets no state: its JS properties stay on the
canary and are gone after a replacement, and the weak collections key its wrapper. Code that
calls objc_removeAssociatedObjects on a live object releases the token too, which
retires the state as if the object had died: the next write through the canary starts a new
state from the canary's properties, but if the canary dies before such a write, a canary built
later starts without them. The weak collections' key for the object hangs off that state, so
what they keyed on the object is lost with it: WeakMap and WeakSet lookups miss,
WeakRef.prototype.deref returns undefined, and once the old key is collected the
FinalizationRegistry cleanup for it runs although the object lives. A JS write through the
canary starts a new state but no key; the next set, add, new WeakRef or register on the
object makes a new key, and entries keyed on the old one never come back. This stays a
limitation: objc_removeAssociatedObjects removes every client's associations, and Apple
documents it as not for general use. The alternative keeps an ObjC weak reference in each record
(objc_initWeakOrNil, which declines instead of aborting for classes that refuse weak
references) and sweeps the records after every major collection, so state lingers until then.
An instance of a class that refuses weak references and is not JS-extended gets no state
under it, in the same way. With the default, "scope": "all" stays experimental because that
check reads private runtime layout; "extended" attaches no tokens at all. It cannot be
rooted at canary death instead, because a state reachable only through the canary is garbage in
the same collection. The cost: state that references its own object (a closure over this)
keeps it alive. A canary built after a death is a new object, but === cannot tell: only one
canary lives at a time, and anything still referencing the old one would have kept it alive.
An explicit release is different: __releaseNativeCounterpart drops the object's
Caches::Instances entry but not its state, so if the object lives on, the next native return
of it builds a new canary with the state's properties while JS can still hold the released
one, and === tells them apart. What could notice is whatever keys on the canary without keeping it. The weak collections
don't: in canary mode a builtin (js/weak-collections.js) replaces WeakMap, WeakSet,
WeakRef and FinalizationRegistry with subclasses that key an in-scope native object (a
canary: not a plain object under "extended", a tagged pointer, a block, or an object of a class
refusing weak references or forbidding associated objects) by an opaque, frozen key held by its state, so entries and targets live
exactly as long as the native object, and WeakRef.prototype.deref returns the live canary, a new
one, or undefined once the object is gone. Lookups never create that key, and a Proxy around a
native object stays a key of its own. The cost is the other side of the same rooting: a WeakMap
value that references its native key keeps the key, its state and so the native object alive for
as long as the map lives, where in the other modes the entry would be collectable. Native #private fields are branded on the canary and do not carry over. Other
limits: Object.freeze, seal and preventExtensions throw on a canary (V8 refuses them on
objects with interceptors); index-keyed properties are not mirrored and die with the canary;
a write through an object whose prototype is a canary lands on that object, since
interceptors only see writes made through their own object. Class fields need the V8 fixes
in v8-buildscripts#13: before them, define-semantics fields reach the definer with inverted
attributes (the state keeps them read-only, hidden and undeletable) and, once their
initializer is warm, bypass it entirely (the field stays on the canary and is gone after a
replacement); v8::Object::CreateDataProperty bypasses it the same way.
Both modes leak what resurrection used to break early, so NativeScriptLeakProbe.framework
(debug builds only; the runtime reaches it through LeakProbe.{h,mm} and LeakProbeSPI.h)
finds JS ↔ native cycles: ns:runtime's getWrapperClassCounts() (live wrappers and states per
class) and findLeakCycles({ strict }), which builds an embedder graph into a heap snapshot
(wrapped objects, what they own through strong ivars and collection or block storage, and the
runtime's cross-heap edges) and runs a trial deletion with -retainCount as the outside-owner
count. Debug builds also log class growth on memory warnings and answer Darwin notifications;
see "Leak diagnostics" in docs/ns-builtin-modules.md. Specs: WrapperLifetimeLeaksTests.js.
Two facts worth knowing when reasoning about which objects can husk:
Pointer/interop.allocobjects never husk at runtime —Caches::PointerInstancesholds them behind strong persistents, so their finalizers cannot fire. Struct instances never husk either: their wrapper and bytes live in an ArrayBuffer backing store held by the struct object, so the GC frees them only once nothing (resurrected or not) reaches it.References are held only by their own weak finalizer handle and do husk.- Only the TypeScript
__extendspath installs the retain/release swizzles that driveGcProtect(); a class from plain.extend()is never protected, so its instances are disposed rather than resurrected when natively retained.
- Runs. The TestRunner suite is green against the patched V8 — 904 tests, 0 failures, 0 errors, 11 skipped — including the GC tests named at the end of the next section.
- Compiles. Full V8 build for
arm64-iphonesimulatorat 14.9.207.39, exit 0, no warnings in the patched files. - Applies cleanly to pristine 14.9.207.39.
- Public API surface compiles: a standalone TU using
SetWeak(..., kFinalizer),Get()inside the callback, and both the re-arm and reset paths passesclang++ -fsyntax-only -std=c++20. - Adds no clang-format violations (mark-compact.cc's 30 are pre-existing).
- No exhaustive switch over
WeakCallbackTypeexists outsideNode::MakeWeak, so adding the enum value breaks no other translation unit.
The runtime suite passes against the patched V8, which drives the resurrection path in anger — see "Worker instance should not be garbage collected if the worker thread is alive" below. Everything in this section is narrower: it needs a V8 run under specific flags, and the suite's default configuration reaches none of it.
- Re-running the marking closure after
EnterProcessGlobalAtomicPause(). The closure is asserted empty at that point and this patch pushes new roots and re-drives it. TheCHECK(IsCppHeapMarkingFinished(...))after the second drain is the tripwire. Run under--stress-incremental-markingand--stress-concurrent-marking. Highest-value test. - Resurrect-then-rearm, end to end. A finalizer that re-arms N times then resets, across
repeated
--expose-gcmajor GCs, under--verify-heap. Confirms the callback site, the un-zapped slot throughMakeWeak'sCHECK_NE(object_, kGlobalHandleZapValue), and theCHECK_WITH_MSGcontract. - Resurrected object reaching a cppgc object. Give a resurrected wrapper a JS property chain to a cppgc-managed wrapper and confirm it is not swept. This is invariant 1's test; it is the failure mode with no loud assertion.
- Young-generation path. A finalizer handle on a young object: confirm scavenge promotes it
rather than finalizing, and that
IncrementNodesDiedInNewSpaceaccounting stays sane. - Nested GC inside a finalizer callback. Allocate heavily in the callback; confirm no double-invocation and no collection of the object under inspection.
TestRunner/app/tests/GCFinalizerTests.js is the acceptance gate for the patch as the runtime
uses it. The Worker wrapper no longer depends on resurrection: a running worker's JS object is a
strong root until its thread ends (WorkerWrapper::RootWorkerObject), so the shared test
"Worker instance should not be garbage collected if the worker thread is alive" passes through
rooting and never reaches the resurrection branch — it must not be read as evidence that a
re-ported patch works. ObjectManager's refuse-and-re-weaken branch remains only as a fallback.
Every V8 bump requires re-checking the four invariants above, since three of them are about where the block sits relative to phases that upstream reorders freely. This is intermediate scaffolding with a real carrying cost — it is cheaper than a faithful revert, not free.