From 231334ef959a53fbdeed66ed0cf841ca545f7dd2 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 14 Nov 2026 21:50:30 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m1/ffi-speed/object-ownership.md Quest-Claim: 1d8c38851c77762d From a4d8f5f0600e81b072e5ae61dfd86225995045f7 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 14 Nov 2026 23:16:29 -0800 Subject: [PATCH 2/3] perf(ffi): one allocation for a Go object and its handle, and no arena in a Dart close Profile Go's and Dart's object return: most of it is each runtime's per-object registration with its collector. Allocate a Go object with its handle, whose cleanup then frees the raw handle directly, and drop the `_Arena` a Dart checked close made for nothing. Rewrite the quest to the nursery that would skip the registration, pending a maintainer decision, and unblock ready-await. Co-Authored-By: Claude Opus 5.5 --- bench/ffi/README.md | 16 +++++-- ffi/justfile | 3 ++ ffi/runtime/rt.go | 16 +++---- ffi/src/dart.rs | 2 +- ffi/src/go.rs | 9 ++-- quest/m1/ffi-speed/object-ownership.md | 59 ++++++++++++++++++++------ quest/m1/ffi-speed/ready-await.md | 18 ++++---- 7 files changed, 81 insertions(+), 42 deletions(-) diff --git a/bench/ffi/README.md b/bench/ffi/README.md index 198622533..6f2bf92f0 100644 --- a/bench/ffi/README.md +++ b/bench/ffi/README.md @@ -371,9 +371,19 @@ frame path: [Copy values](#copy-values): what remains is each language's call and, in Kotlin and Python, an object of its own. 2. **Ownership of a returned object.** An object return costs C 25 ns, but Go 263 and - Dart 242, ten times C: each new Go object registers `runtime.AddCleanup` and each Dart - one a `NativeFinalizer`, beside a handle allocation. Kotlin's 137 ns wall (210 CPU) is a phantom - reference linked and unlinked under one global lock. Every returned frame, group, and future pays it. + Dart 242, ten times C, and most of the difference is each runtime's per-object + registration with its collector. Profiled 2026-11-14 on **nixos** with `perf`, for an + object returned and closed: Go spends 39% of it in `runtime.AddCleanup` and the + `Cleanup.Stop` its `Close` makes, a third in its three cgo crossings (the call, the + value's drop, the handle's free), and a tenth in the collector's own threads. Dart's + `Dart_NewFinalizableHandle`, its crossing, and the collector finalizing it cost 1,600 + instructions an object, three quarters of it: without them, a return and close took + 62 to 65 ns against 176 to 245. Since kixel-ai/rust2#828, a Go object and its handle + are one allocation (70 fewer instructions) and a Dart close drops the value without + an `_Arena` (136 fewer). [Batched ownership](../../quest/m1/ffi-speed/object-ownership.md) + would take the registration off objects closed soon after their return. Kotlin's + 137 ns wall (210 CPU) is a phantom reference linked and unlinked under one global lock. + Every returned frame, group, and future pays it. 3. **A woken read.** C's 427 ns is Rust's 329 plus a future's crossings. Kotlin's 1.6 us and Dart's 1.8 us add their event loops; Go's 5.1 us and Swift's 5.7 us wall (16.6 us CPU) are a goroutine or `Task` and a cross-thread wake per read, and Python's 6.9 us is diff --git a/ffi/justfile b/ffi/justfile index da1468d63..6f514371a 100644 --- a/ffi/justfile +++ b/ffi/justfile @@ -468,6 +468,9 @@ moq-export checkout="": (moq-write checkout) *) lib=libmoq.so ;; esac cargo build --locked --quiet --release --manifest-path "$out/Cargo.toml" --features python + # Cargo links the output to its build of the same features, which a rerun's last move + # left here, and mv refuses to move a file onto itself. + rm -f "$out/python/$lib" mv "$out/target/release/$lib" "$out/python/$lib" # The library the C programs link, and the shared one Kotlin and Dart load. cargo build --locked --quiet --release --manifest-path "$out/Cargo.toml" --features kotlin,dart 2>&1 | tee target/moq-build.log diff --git a/ffi/runtime/rt.go b/ffi/runtime/rt.go index dd8a482c9..5e14c1257 100644 --- a/ffi/runtime/rt.go +++ b/ffi/runtime/rt.go @@ -75,12 +75,13 @@ type Handle_ struct { Cleanup runtime.Cleanup } -// NewHandle_ is a handle of raw, which free frees, or nil for one Rust lends, and drop -// drops the value of, or nil for one Rust does not check. -func NewHandle_(raw unsafe.Pointer, free func(unsafe.Pointer), drop func(unsafe.Pointer) error, name string) *Handle_ { - h := &Handle_{raw: raw, free: free, drop: drop, name: name} +// Init makes h a handle of raw, which free frees, or nil for one Rust lends, and drop +// drops the value of, or nil for one Rust does not check. The generated packages allocate +// it with the object owning it, which each call holding it then keeps reachable: so once +// the GC collects the object, no call holds the handle, and its cleanup frees it at once. +func (h *Handle_) Init(raw unsafe.Pointer, free func(unsafe.Pointer), drop func(unsafe.Pointer) error, name string) { + h.raw, h.free, h.drop, h.name = raw, free, drop, name h.state.Store(held_) - return h } // Hold is the handle, held until Release, or nil once closed. @@ -150,11 +151,6 @@ func (h *Handle_) Moved() { h.abandon() } -// Collected frees an owned handle the GC collected the object of, once no call holds it. -func (h *Handle_) Collected() { - h.abandon() -} - // abandon gives up the owner's hold, freeing it once no call holds it. func (h *Handle_) abandon() { for { diff --git a/ffi/src/dart.rs b/ffi/src/dart.rs index 919085536..400462ca4 100644 --- a/ffi/src/dart.rs +++ b/ffi/src/dart.rs @@ -1751,7 +1751,7 @@ impl<'a> Gen<'a> { let what = format!("{c}_drop"); let f = self.served_fn(&what, vec![owner.clone(), Ty::Out(Box::new(Ty::Status))], Ty::Void); body.push(format!( - "\t@override\n\tvoid _drop() {{\n\t\tfinal a_ = _Arena();\n\t\ttry {{\n\t\t\tfinal s_ = _n.status;\n\t\t\t{f}(_n.home, _raw, s_);\n\t\t\t_status(s_.value, '{what}');\n\t\t}} finally {{\n\t\t\ta_.end();\n\t\t}}\n\t}}\n" + "\t@override\n\tvoid _drop() {{\n\t\tfinal s_ = _n.status;\n\t\t{f}(_n.home, _raw, s_);\n\t\t_status(s_.value, '{what}');\n\t}}\n" )); } self.traits(&ty, &c, object.traits, &mut body, &mut members); diff --git a/ffi/src/go.rs b/ffi/src/go.rs index fc738acc7..65e89706e 100644 --- a/ffi/src/go.rs +++ b/ffi/src/go.rs @@ -357,7 +357,6 @@ const TAKEN: &[&str] = &[ "ErrBorrowed", "ErrClosed", "Handle_", - "NewHandle_", "LiftBytes_", "BytesBuf_", "GoCall_", @@ -2037,7 +2036,6 @@ impl<'a> Gen<'a> { let (_, local) = self.named(&ty); let name = self.qualified(&ty); let handle = self.qualify(Packages::RT, "Handle_"); - let new = self.qualify(Packages::RT, "NewHandle_"); let (drop, dropping) = match self.abi.checked[i] { true => ( format!( @@ -2053,10 +2051,11 @@ impl<'a> Gen<'a> { format!( "func free_{c}(p unsafe.Pointer) {{\n\tC.{c}_free((*C.{c})(p))\n}}\n\n\ {drop}\ - // own_{c} owns a handle Rust returned, or is nil for none.\n\ - func own_{c}(raw *C.{c}) *{name} {{\n\tif raw == nil {{\n\t\treturn nil\n\t}}\n\tv := &{name}{{Handle_: {new}(unsafe.Pointer(raw), free_{c}, {dropping}, \"{local}\")}}\n\tv.Handle_.Cleanup = runtime.AddCleanup(v, (*{handle}).Collected, v.Handle_)\n\treturn v\n}}\n\n\ + // own_{c} owns a handle Rust returned, or is nil for none: the object and its handle\n\ + // in one allocation, whose cleanup frees the handle.\n\ + func own_{c}(raw *C.{c}) *{name} {{\n\tif raw == nil {{\n\t\treturn nil\n\t}}\n\to := &struct {{\n\t\tv {name}\n\t\th {handle}\n\t}}{{}}\n\to.h.Init(unsafe.Pointer(raw), free_{c}, {dropping}, \"{local}\")\n\to.v.Handle_ = &o.h\n\to.h.Cleanup = runtime.AddCleanup(&o.v, free_{c}, unsafe.Pointer(raw))\n\treturn &o.v\n}}\n\n\ // lend_{c} is a handle Rust lends for a call, which it frees itself.\n\ - func lend_{c}(raw *C.{c}) *{name} {{\n\treturn &{name}{{Handle_: {new}(unsafe.Pointer(raw), nil, nil, \"{local}\")}}\n}}\n\n\ + func lend_{c}(raw *C.{c}) *{name} {{\n\to := &struct {{\n\t\tv {name}\n\t\th {handle}\n\t}}{{}}\n\to.h.Init(unsafe.Pointer(raw), nil, nil, \"{local}\")\n\to.v.Handle_ = &o.h\n\treturn &o.v\n}}\n\n\ // holdOption_{c} is v's handle, held until the call returns, or nil for none.\n\ func holdOption_{c}(a_ *arena_, v *{name}) *C.{c} {{\n\tif v == nil {{\n\t\treturn nil\n\t}}\n\treturn (*C.{c})(a_.hold(v.Handle_, v))\n}}\n\n" ) diff --git a/quest/m1/ffi-speed/object-ownership.md b/quest/m1/ffi-speed/object-ownership.md index ebe67c0e5..77d47295b 100644 --- a/quest/m1/ffi-speed/object-ownership.md +++ b/quest/m1/ffi-speed/object-ownership.md @@ -1,21 +1,54 @@ -# [M] Cheaper returned-object ownership in Go and Dart +# [L] Returned objects closed early skip the collector in Go and Dart ## Goal A [rust2-ffi](/ffi/README.md) Go or Dart binding returns an object for close to what C -pays. [The binding benchmark](/bench/ffi/README.md) measures an object return at 263 ns -in Go and 242 in Dart against C's 25, and every returned frame, group, and future pays it. +pays when the caller closes it soon after. [The binding benchmark](/bench/ffi/README.md) +measures an object return at 263 ns in Go and 242 in Dart against C's 25, and every +returned frame, group, and future pays it. Ownership stays automatic: a dropped object is still freed without a call from the user. ## Plan -- Profile first: split the cost between the handle allocation, Go's `runtime.AddCleanup`, - Dart's `Dart_NewFinalizableHandle`, and the crossing, and fix what dominates. -- Two candidates this quest first listed are already how the code works, found by the - 2026-11-12 audit: Dart objects use `Dart_NewFinalizableHandle` with a size of 0 - (`ffi/runtime/dart.rs`), and Go registers one cleanup with the handle as its argument - (`ffi/src/go.rs`'s `own_`). So take candidates from the profile. One left: allocate the - wrapper and its handle together, so a return allocates once. -- Explicit `Close` stays, and the cleanup stays as the backstop; dropping it is refused, - since a missed `Close` would leak. -- Re-measure the bench's object return and stamped write. +- The profile ([the benchmark's README](/bench/ffi/README.md#what-a-call-spends), item 2) + puts most of the cost in each runtime's per-object registration with its collector: Go's + `runtime.AddCleanup` and the `Cleanup.Stop` its `Close` makes take 39% of a return and + close, and Dart's `Dart_NewFinalizableHandle`, its crossing, and its finalization take + three quarters (1,600 instructions). Without the registration, Dart's return and close + took 62 to 65 ns against 176 to 245. kixel-ai/rust2#828 took what it could without + deferring the registration: one allocation for a Go object and its handle, and no + `_Arena` in a Dart close. +- Rejected, measured: Dart's `NativeFinalizer.attach` without `detach` (770 to 1,070 ns + a return), Go's `runtime.SetFinalizer` (13% fewer instructions to register and clear + than `AddCleanup` and `Stop`, but it runs every free on one goroutine and keeps each + object a collection longer), and leaving Go's cleanup registered at `Close` (290 to 450 + ns a return against 120, in a microbenchmark). +- Recommended: a nursery of the last 64 objects returned, which only registers an object + with the collector once it leaves the nursery still open. A `close` of an object in the + nursery frees its handle at once, with a checked value's drop in the same crossing, and + it never registers. Explicit `Close` stays, and the registration stays as the backstop. + - Dart: one ring in the isolate's `_n`, holding its objects, whose oldest is registered + as today when a return pushes it out. A checked object's handle is then freed at + `close`, so its calls check a closed flag in Dart, as a counted one's do (one load a + call). One finalizable handle on the ring frees what it still holds at isolate exit. + - Go: a ring per P, through a `sync.Pool` as `lending_` pools byte batches. Each + object points at its ring and the ring at its objects, so one `AddCleanup` on the ring + frees its open slots once all of them are unreachable, as when the pool drops it. A + compare-and-swap on the object's slot decides between its `Close` and its eviction. +- Re-measure the bench's object return and ready read, and check by drop counts in + `ffi/tests` that an object dropped in the nursery is freed once evicted and collected. + +## Waiting + +- Maintainer: accept the later free the nursery brings? An object dropped without `Close` + is freed only after up to 64 more returns, or in Go once its ring's other objects are + unreachable too, rather than at the next collection. Options: (a) the nursery as + planned (recommended: it takes Dart's object return from about 200 ns to about 65, and + Go's by about 110 ns, while a closed object never waits); (b) keep today's per-object + registration and delete this quest; (c) flush the nursery on a timer each event-loop + turn instead of by count (rejected: a timer each turn costs more than it saves when a + turn returns one object, as a woken read does). + +## Related + +- [Shared borrows](/quest/m1/ffi-speed/shared-borrow.md) - rewrites the same handle word diff --git a/quest/m1/ffi-speed/ready-await.md b/quest/m1/ffi-speed/ready-await.md index a8b577aa2..65f6ec52c 100644 --- a/quest/m1/ffi-speed/ready-await.md +++ b/quest/m1/ffi-speed/ready-await.md @@ -3,20 +3,18 @@ ## Goal A [rust2-ffi](/ffi/README.md) Swift, Go, or Dart await of a future ready at its first -poll costs close to C's, once [returned-object ownership](/quest/m1/ffi-speed/object-ownership.md) -is out of the way. Since `_start` made a ready call one crossing and one allocation, -[the binding benchmark](/bench/ffi/README.md)'s ready read costs C 126 ns over its write, +poll costs close to C's, apart from the returned object's ownership, which +[returned-object ownership](/quest/m1/ffi-speed/object-ownership.md) owns. Since +`_start` made a ready call one crossing and one allocation, [the binding benchmark](/bench/ffi/README.md)'s ready read costs C 126 ns over its write, Rust 93, and Swift 289, Go 414, and Dart 522. Less the returned frame's ownership, Swift's await still adds about 150 ns over C's, Go's 100, and Dart's 180. ## Plan -- Profile each language's ready path from the generated call to the result, after - object-ownership lands so its share is gone: Swift's `async` entry and `Native.start`, - Go's escaped out-pointers and error check, and Dart's `_Call` and `_Arena`. +- Profile each language's ready path from the generated call to the result, setting the + returned frame's ownership apart (its split is in + [the benchmark's README](/bench/ffi/README.md#what-a-call-spends), item 2): Swift's + `async` entry and `Native.start`, Go's escaped out-pointers and error check, and Dart's + `_Call` and `_Arena`. - Fix what dominates in the generator or runtime, with no API change. - Re-measure the ready read interleaved with the commit before, CPU first. - -## Required - -- [Returned-object ownership](/quest/m1/ffi-speed/object-ownership.md) - removes Go's and Dart's ownership share of the ready read, so the profile shows only the await's From f291b8f301d6f80b060272ed4215fa8098344671 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sun, 15 Nov 2026 01:54:57 -0800 Subject: [PATCH 3/3] docs(quest): object-ownership records the nursery decision Co-Authored-By: Claude Opus 5.5 --- quest/m1/ffi-speed/object-ownership.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/quest/m1/ffi-speed/object-ownership.md b/quest/m1/ffi-speed/object-ownership.md index 77d47295b..c3ff744fb 100644 --- a/quest/m1/ffi-speed/object-ownership.md +++ b/quest/m1/ffi-speed/object-ownership.md @@ -23,7 +23,8 @@ Ownership stays automatic: a dropped object is still freed without a call from t than `AddCleanup` and `Stop`, but it runs every free on one goroutine and keeps each object a collection longer), and leaving Go's cleanup registered at `Close` (290 to 450 ns a return against 120, in a microbenchmark). -- Recommended: a nursery of the last 64 objects returned, which only registers an object +- Settled by the maintainer (2026-11-15, kixel-ai/rust2#828): a nursery of the last 64 + objects returned, which only registers an object with the collector once it leaves the nursery still open. A `close` of an object in the nursery frees its handle at once, with a checked value's drop in the same crossing, and it never registers. Explicit `Close` stays, and the registration stays as the backstop. @@ -35,20 +36,15 @@ Ownership stays automatic: a dropped object is still freed without a call from t object points at its ring and the ring at its objects, so one `AddCleanup` on the ring frees its open slots once all of them are unreachable, as when the pool drops it. A compare-and-swap on the object's slot decides between its `Close` and its eviction. + - The later free is accepted: an object dropped without `Close` is freed only after up + to 64 more returns, or in Go once its ring's other objects are unreachable too, + rather than at the next collection. Rejected: keeping today's per-object + registration and deleting this quest; flushing the nursery each event-loop turn (a + timer each turn costs more than it saves when a turn returns one object, as a woken + read does). - Re-measure the bench's object return and ready read, and check by drop counts in `ffi/tests` that an object dropped in the nursery is freed once evicted and collected. -## Waiting - -- Maintainer: accept the later free the nursery brings? An object dropped without `Close` - is freed only after up to 64 more returns, or in Go once its ring's other objects are - unreachable too, rather than at the next collection. Options: (a) the nursery as - planned (recommended: it takes Dart's object return from about 200 ns to about 65, and - Go's by about 110 ns, while a closed object never waits); (b) keep today's per-object - registration and delete this quest; (c) flush the nursery on a timer each event-loop - turn instead of by count (rejected: a timer each turn costs more than it saves when a - turn returns one object, as a woken read does). - ## Related - [Shared borrows](/quest/m1/ffi-speed/shared-borrow.md) - rewrites the same handle word