Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
231334e
chore(quest): claim quest/m1/ffi-speed/object-ownership.md
kixelated Nov 15, 2026
a4d8f5f
perf(ffi): one allocation for a Go object and its handle, and no aren…
kixelated Nov 15, 2026
f291b8f
docs(quest): object-ownership records the nursery decision
kixelated Nov 15, 2026
6a62c29
chore(quest): claim quest/m1/ffi-speed/object-ownership.md
kixelated Nov 15, 2026
f813d19
Merge commit '6a62c29335fb61465dba3bb43b824e8e1d94cb74' into quest/m1…
kixelated Nov 15, 2026
354c244
perf(ffi): Go objects closed soon after their return skip the GC's re…
kixelated Nov 15, 2026
bdcb3aa
perf(ffi): Dart objects closed soon after their return skip the colle…
kixelated Nov 15, 2026
3e6c60e
Merge origin/main
kixelated Nov 15, 2026
8dbb44a
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-speed/ob…
kixelated Nov 15, 2026
635663a
perf(ffi): a Go Close of a checked object no call holds drops and fre…
kixelated Nov 15, 2026
29e47ed
docs(ffi): the nursery in the Go and Dart object docs and the benchma…
kixelated Nov 15, 2026
4cdf117
style(ffi): rustfmt
kixelated Nov 15, 2026
f0b1f08
style(ffi): rustfmt, and restore what another rustfmt touched
kixelated Nov 15, 2026
591c7b5
test(ffi): a Dart u64 since lossless types
kixelated Nov 15, 2026
262472f
fix(ffi): a Dart checked object counts its call holds and is closed b…
kixelated Nov 15, 2026
2398692
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-speed/ob…
kixelated Nov 16, 2026
b7d50fd
fix(ffi): Go reads the header's contract through C
kixelated Nov 16, 2026
18450d1
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-speed/ob…
kixelated Nov 16, 2026
8127c4b
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-speed/ob…
kixelated Nov 16, 2026
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
11 changes: 9 additions & 2 deletions bench/ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -405,8 +405,15 @@ frame path:
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
an `_Arena` (136 fewer). Since kixel-ai/rust2#838, an object closed within 64 returns
of its own skips the registration: each Go P and each Dart isolate holds its last 64
returned objects in a nursery, registering only one pushed out unclosed, and a checked
object's close drops and frees in one crossing. Measured 2026-11-15 on **nixos** at a
load average of 4 to 24, 8 rounds alternating with main at `72880f48`, median wall ns:
Go's object return fell from 254 to 174 and Dart's from 225 to 96, Go's ready read from
833 to 728 and Dart's from 1,020 to 786, and Dart's woken read from 2,930 to 2,274.
What Go has left is mostly its two cgo crossings, the call and the close, and the pool
that finds its P's nursery. 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
Expand Down
34 changes: 22 additions & 12 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -978,8 +978,13 @@ reads a go.mod.
would, and returns an error matching `rt.ErrBorrowed` instead while a call on another
goroutine borrows the value, as Rust refuses that drop, leaving the value to a later
`Close()`. Of any other type, `Close()` frees the handle, and returns an error matching
`rt.ErrBorrowed` while a call holds it. A second `Close()` does nothing, and one never
closed is freed once the GC collects it, through `runtime.AddCleanup`. A call that meets
`rt.ErrBorrowed` while a call holds it; one no call holds, as soon after its return,
drops and frees in one crossing. A second `Close()` does nothing. A returned object waits
in a nursery of the last 64 its P returned, where `Close()` frees it without the GC's
registration (`runtime.AddCleanup` and its `Stop`), which costs more than the rest of a
return and close. One never closed is registered once pushed out, by 64 later returns or
with its nursery once the GC drops that from its `sync.Pool`, and freed once the GC
collects it after. A call that meets
a closed object, as its receiver or anywhere in its arguments, returns an error matching
`rt.ErrClosed`, so every such call returns an `error`; `String()` and `GoString()`,
which return none, return the error's text. A `self` method, or passing the object by
Expand Down Expand Up @@ -1116,12 +1121,16 @@ the library's own URI, mapped to the library by a build hook or by `--native-ass
declares or a data enum's variant class, are kept apart as Kotlin's are. The glue's C
names are `<prefix>_dart_`, with a `_` more for each C name of the export already there.
- **Objects** are final classes owning their handle. Of a checked type, `close()` drops
the value through Rust's own `_drop`, as Rust's `drop` would: a call after it throws a
`StateError` as for a value moved out, and a `close()` while a call borrows the value,
from a closure that call runs, throws one instead, as Rust refuses that drop. Of any
other type, `close()` frees the handle, and throws while a call holds it. A second
`close()` does nothing, and the handle itself is freed once the garbage collector finds
the object unreachable, through a finalizable handle of Dart's C API. Any call that meets
the value through Rust's own `_drop`, as Rust's `drop` would, and frees the handle in
the same crossing, and a `close()` while a call borrows the value, from a closure that
call runs, throws a `StateError` instead, as Rust refuses that drop. Of any other type,
`close()` frees the handle, and throws while a call holds it. A second `close()` does
nothing. A returned object waits in the isolate's nursery of the last 64 returned, where
`close()` frees it without the garbage collector's registration (a finalizable handle of
Dart's C API), which costs more than the rest of a return and close. One never closed is
registered once 64 later returns push it out, and freed once the garbage collector finds
it unreachable after; one still in the nursery when the isolate exits is freed then. Any
call that meets
a closed object, as its receiver or anywhere in its arguments, throws a `StateError`
before Rust sees it. A `self` method, or passing the object by value, moves its value
out. `Clone` is `clone()`, and a `pub`
Expand Down Expand Up @@ -1344,7 +1353,7 @@ just ffi shapes # round-trip every sampled type shape in every language but KN
nix develop .#android --command just ffi android # the Kotlin test, shrunk by R8, on the Android device adb reaches
nix develop .#bench --command just ffi bench # the binding benchmark: bench/ffi/README.md's cases from Rust, and through the export from C, C++, Kotlin, Python, Swift, Go, and Dart
nix develop .#bench --command just ffi codspeed # after bench-build, each single-threaded case once under CodSpeed's CPU simulation, as the CodSpeed workflow runs it
nix develop .#sanitize --command just ffi sanitize # api's C and C++ scripts under ASan and TSan, and its C ABI under Miri
nix develop .#sanitize --command just ffi sanitize # api's C and C++ scripts under ASan and TSan, its Go under the race detector, and its C ABI under Miri
```

The `api` fixture covers each rule once, and re-exports the `dep` fixture's types, which
Expand Down Expand Up @@ -1380,7 +1389,8 @@ It runs with nixpkgs' Swift on Linux, and nightly with Apple's on macOS.
way, plus a context done before the call, a deadline, and a handle closed during a call,
checks that bytes cross both ways, that a `Bytes` keeps Rust's buffer while only a sub-view
or a reader reaches it and that the GC frees it once none does, that the GC frees an object
never closed, and that each kind of call meeting a closed object, including one racing
never closed once 64 later returns push it out of its nursery, that each object of many
goroutines' returns, closes, and drops is freed once, and that each kind of call meeting a closed object, including one racing
`Close`, returns `rt.ErrClosed`, and breaks
each runtime check, which must panic with its message; a runtime package from another
build must fail its contract check. The `target` test exports a package for the host, for wasm32, and for both into one
Expand All @@ -1404,8 +1414,8 @@ feature breaks the API twice for each kind of break, once in an item only wasm32
error matching `fixtures/lock/expected.txt`.
`just ffi sanitize`, run nightly, rebuilds the `api` export with std under AddressSanitizer
and then ThreadSanitizer, runs `tests/api.c` and `tests/api.cpp` against it, and matches
their output to the native transcript; it then drives the C ABI from `tests/miri/api.rs`
under Miri with strict provenance.
their output to the native transcript; it runs `tests/api.go` under Go's race detector;
and it drives the C ABI from `tests/miri/api.rs` under Miri with strict provenance.
moq's crates export through `target/moq-ffi`, an empty library on each that `just ffi moq`
writes in place of moq-ffi's remainder. The export serves the host and each target
`just ffi moq-api` staged in `target/moq-api` from the same moq sources, and fails on a
Expand Down
21 changes: 21 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1806,6 +1806,27 @@ impl Logger {
}
}

/// A [`Logger`] its `&mut self` method makes checked, so a binding's close drops it through
/// Rust, running its implementation's close inside that drop.
pub struct Journal {
sink: Box<dyn Log>,
}

impl Journal {
pub fn new(sink: Box<dyn Log>) -> Self {
Self { sink }
}

/// Log to `sink` from now on, dropping the implementation before it.
pub fn redirect(&mut self, sink: Box<dyn Log>) {
self.sink = sink;
}

pub fn write(&self, line: &str) -> bool {
self.sink.log(0, line)
}
}

#[cfg(not(target_arch = "wasm32"))]
/// A thread logging a line to a foreign implementation, which [`LogThread::join`] waits on.
pub struct LogThread {
Expand Down
4 changes: 2 additions & 2 deletions ffi/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ shapes:
android:
cargo test --locked --test fixtures -- --ignored --exact api_android

# Run the api fixture's C and C++ scripts under AddressSanitizer and ThreadSanitizer, and its glue's C ABI under Miri, in the sanitize shell: nix develop .#sanitize.
# Run the api fixture's C and C++ scripts under AddressSanitizer and ThreadSanitizer, its Go script under Go's race detector, and its glue's C ABI under Miri, in the sanitize shell: nix develop .#sanitize.
sanitize:
cargo test --locked --test fixtures -- --ignored --exact api_asan api_tsan api_miri
cargo test --locked --test fixtures -- --ignored --exact api_asan api_tsan api_go_race api_miri

# Apply formatters without changing program behavior.
fix:
Expand Down
33 changes: 33 additions & 0 deletions ffi/runtime/dart.rs
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,39 @@ pub unsafe fn disown(own: *mut c_void, object: *mut c_void) {
unsafe { (api().unfinalize)(own, object) }
}

/// The slots of a nursery of `len` objects, which Dart fills: `len`, then each object's
/// handle, then the C function freeing it, the handle null while the slot is out. Once the
/// garbage collector finds `object`, the nursery, unreachable, as when its isolate exits,
/// each handle still in a slot is freed.
///
/// # Safety
/// Called from Dart in its isolate, with `object` a handle of the Dart object, which writes
/// only handles the function beside each frees, and only while reachable.
pub unsafe fn nursery(object: *mut c_void, len: usize) -> *mut *mut c_void {
unsafe extern "C" fn finalize(_: *mut c_void, slots: *mut c_void) {
let slots = slots.cast::<*mut c_void>();
// SAFETY: `nursery` made `slots`, whose first word is its length.
let len = unsafe { *slots } as usize;
// SAFETY: as above, nothing writes it once the nursery is unreachable.
let slots = unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(slots, 1 + 2 * len)) };
for i in 0..len {
let raw = slots[1 + i];
if !raw.is_null() {
// SAFETY: Dart's contract: each handle beside the function that frees it.
let free = unsafe { std::mem::transmute::<*mut c_void, unsafe extern "C" fn(*mut c_void)>(slots[1 + len + i]) };
// SAFETY: as above, and this frees each at most once, as no Dart object owns it.
unsafe { free(raw) };
}
}
}
let mut slots = vec![std::ptr::null_mut::<c_void>(); 1 + 2 * len].into_boxed_slice();
slots[0] = len as *mut c_void;
let slots = Box::into_raw(slots).cast::<*mut c_void>();
// SAFETY: the caller's contract.
unsafe { own(object, slots.cast(), finalize) };
slots
}

/// An isolate: its port, and the calls into it other threads wait on. One lives for each
/// isolate that loads the library, and is never freed, since nothing tells Rust an
/// isolate exited.
Expand Down
123 changes: 105 additions & 18 deletions ffi/runtime/rt.dart
Original file line number Diff line number Diff line change
Expand Up @@ -782,57 +782,141 @@ final class _Callback extends ffi.Struct {
external ffi.Pointer<ffi.Void> data;
}

/// What an object owns: its handle, or one Rust lends for a call, which Rust frees. An owned
/// one of a value Rust checks is Rust's alone to account: [close] drops the value as Rust's
/// own drop does, failing while a call borrows it, a call after it throws as Rust's check
/// of a moved value does, and the handle is freed once the garbage collector finds this
/// unreachable. Any other counts its calls: [close] frees it then, throwing while a call
/// holds it, and a call after it throws.
/// What an object owns: its handle, or one Rust lends for a call, which Rust frees. Each
/// call holds it, so the handle is freed only once no call does. An owned one of a value
/// Rust checks is Rust's to account: [close] drops the value as Rust's own drop does,
/// failing while a call borrows it, and frees the handle with it unless a call holds it.
/// Any other: [close] frees it then, throwing while a call holds it. A call after either
/// throws. One returned waits in the isolate's [_Nursery], where a close frees it without
/// the garbage collector, which frees it only once pushed out unclosed.
abstract base class _Object implements ffi.Finalizable {
final ffi.Pointer<ffi.Void> _raw;

/// The owner's hold until closed, and one for each call, of a counted one.
/// The owner's hold until closed, and one for each call.
int _holds = 1;
bool _closed = false;
final bool _owned;

/// Whether it counts its calls, rather than Rust.
final bool _counted;
/// Whether Rust checks its borrows, so its close drops the value through Rust.
final bool _checked;

/// The garbage collector's hold of an owned one's handle, until freed.
/// The garbage collector's hold of an owned one's handle, from when the nursery pushed it
/// out until freed.
ffi.Pointer<ffi.Void> _own = ffi.nullptr;

_Object(this._raw, bool owned, bool checked) : _owned = owned, _counted = !(owned && checked);
/// Its slot in the nursery while there, else -1.
int _slot = -1;

_Object(this._raw, bool owned, bool checked) : _owned = owned, _checked = owned && checked;

String get _type;

/// Free the handle and detach its finalizer.
void _free();
/// Free an owned one's handle, and take back the garbage collector's hold of it.
void _free() {}

/// Give the garbage collector a hold of the handle, as the nursery pushes it out open.
void _register() {}

/// Drop the value of one Rust checks, throwing [StateError] if a call borrows it.
void _drop() {}
/// Drop the value of one Rust checks, then, if `free`, free its handle and take back the
/// garbage collector's hold of it, in one crossing: throwing [StateError], changing
/// nothing, if a call borrows it.
void _close(bool free) {}

ffi.Pointer<ffi.Void> _hold() {
if (!_counted) return _raw;
if (_closed) throw StateError('$_type is closed');
_holds++;
return _raw;
}

void _release() {
if (_counted && --_holds == 0 && _owned) _free();
if (--_holds == 0 && _owned) {
_leave();
_free();
}
}

/// Take it out of the nursery, returning whether it was there: before its free, which
/// may run Dart that returns objects into the nursery meanwhile.
bool _leave() {
final slot = _slot;
if (slot < 0) return false;
_slot = -1;
_n.nursery.leave(slot);
return true;
}

/// Close it as [_Object] says; again, it does nothing.
void close() {
if (!_counted) return _drop();
if (_closed) return;
if (_checked) {
// Closed before Rust drops the value, which may run Dart that reaches it meanwhile.
_closed = true;
// A call holding it, from a callback or one waiting on a worker, may not have
// borrowed the value in Rust yet: the handle outlives its hold, so Rust's check
// refuses it.
final alone = _holds == 1;
final nursed = alone && _leave();
try {
_close(alone);
} catch (_) {
_closed = false;
// Still open, and out of the nursery, so the garbage collector's.
if (nursed) _register();
rethrow;
}
if (alone) {
_holds = 0;
} else {
_release();
}
return;
}
if (_holds != 1) throw StateError('$_type: a handle is already borrowed');
_closed = true;
_release();
}
}

/// How many of the latest objects returned the nursery holds: one dropped unclosed is freed
/// only once this many more were returned, so it bounds what a dropped object keeps of
/// Rust's.
const _nurseryLen = 64;

/// The latest objects returned, oldest at [_next] once full: a close takes one out without
/// the garbage collector's hold of its handle, which costs more than the rest of a return
/// and close together, and one pushed out still open takes that hold then. Rust keeps a copy
/// of each slot's handle and the C function freeing it, and frees what is still in them once
/// the garbage collector finds the nursery unreachable, as when the isolate exits.
final class _Nursery {
final List<_Object?> _held = List<_Object?>.filled(_nurseryLen, null);
int _next = 0;

/// What Rust keeps: the length, then each slot's handle, then each one's free function,
/// null while the slot is out.
late final ffi.Pointer<ffi.Pointer<ffi.Void>> _slots = _dartNursery(this, _nurseryLen);

/// Hold `object`, owned, whose handle `free` frees.
void push(_Object object, ffi.Pointer<ffi.Void> free) {
final i = _next;
_next = i + 1 == _nurseryLen ? 0 : i + 1;
final old = _held[i];
if (old != null) {
old._slot = -1;
old._register();
}
_held[i] = object;
object._slot = i;
final slots = _slots;
slots[1 + i] = object._raw;
slots[1 + _nurseryLen + i] = free;
}

void leave(int slot) {
_held[slot] = null;
_slots[1 + slot] = ffi.nullptr;
}
}

/// Native memory each call lowers its values into, as a stack: a call takes what it
/// needs from the top and gives it back once it returns, so a call Rust makes into Dart
/// meanwhile takes and gives back above it.
Expand Down Expand Up @@ -1057,6 +1141,9 @@ final class _Native {
/// queued meanwhile, and the call reads it before any other can run, and a failure
/// clears it.
late final ffi.Pointer<ffi.Int32> status = _dartAlloc(4).cast<ffi.Int32>()..value = 0;

/// The latest objects returned.
late final _Nursery nursery = _Nursery();
late final isolate.RawReceivePort _port;
late final ffi.Pointer<ffi.Void> home;

Expand Down
Loading