Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions bench/ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions ffi/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 6 additions & 10 deletions ffi/runtime/rt.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion ffi/src/dart.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
9 changes: 4 additions & 5 deletions ffi/src/go.rs
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,6 @@ const TAKEN: &[&str] = &[
"ErrBorrowed",
"ErrClosed",
"Handle_",
"NewHandle_",
"LiftBytes_",
"BytesBuf_",
"GoCall_",
Expand Down Expand Up @@ -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!(
Expand All @@ -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"
)
Expand Down
55 changes: 42 additions & 13 deletions quest/m1/ffi-speed/object-ownership.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,50 @@
# [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).
- 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.
- 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.
- 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.

## Related

- [Shared borrows](/quest/m1/ffi-speed/shared-borrow.md) - rewrites the same handle word
18 changes: 8 additions & 10 deletions quest/m1/ffi-speed/ready-await.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<fn>_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
`<fn>_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