Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
aa7f0c0
chore(quest): claim quest/m1/ffi-export/not-send.md
kixelated Nov 15, 2026
d8260bf
feat(ffi)!: types and futures that are not Send export, checked by th…
kixelated Nov 15, 2026
06ee571
test(ffi): run the not-Send C checks under the sanitizers, and the le…
kixelated Nov 15, 2026
5f2cd00
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/n…
kixelated Nov 15, 2026
c48bff3
fix(ffi): pin futures holding or making values that are not Send, and…
kixelated Nov 15, 2026
d3422dc
fix(ffi): a poll's future holds the waiter it makes, so is not Send w…
kixelated Nov 15, 2026
fb3c3b8
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/n…
kixelated Nov 15, 2026
3a94b59
fix(ffi): home a maker whose optional handles are absent, and serve w…
kixelated Nov 15, 2026
77f8e0f
fix(ffi): drop what a thread's exit drops queue, and test cross-home …
kixelated Nov 15, 2026
c674cd4
fix(ffi): wake a home when a closed or lent handle lets go of its record
kixelated Nov 16, 2026
94a868b
docs(ffi): only a returned value that is not Send stays on its home
kixelated Nov 16, 2026
72b3532
test(ffi): a pending future made with its optional local absent or pr…
kixelated Nov 16, 2026
0853c7a
test(ffi): the transcript makes and bumps locals, against native Rust
kixelated Nov 16, 2026
0830259
test(ffi): the transcript awaits local_or_new_later with and without …
kixelated Nov 16, 2026
8d1e671
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/n…
kixelated Nov 16, 2026
9c567e4
docs(quest): follow-ups for an exclusive lend and a drain on an idle …
kixelated Nov 16, 2026
2bf914d
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/n…
kixelated Nov 16, 2026
c236373
docs(quest): the drain quest leaves Kotlin's and Swift's own values out
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
55 changes: 49 additions & 6 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ public path names, or an error taken by value, is held by value as an opaque han
| a struct whose fields are all `pub`, not `#[non_exhaustive]`, which map, with no `Drop` of its own | a record: a struct, copied across |
| an enum with variants whose fields map, with no `Drop` of its own | a C enum without fields, or a struct of a tag and a union |
| any other type that is `Copy` and `Send`, with no padding under any order of its fields, such as moq's `Timestamp` or `stats::Traffic` | an opaque value: a struct of its bytes, copied across, which only Rust makes, reads, or changes; its `pub` fields are a getter and a setter, and a `&mut self` method writes back the caller's copy alone, one returning a future or a `Result` refused, since a language raising the error would lose the change; one no export returns is left out, since C could never make one |
| any other type, if `Send` | an object: an opaque handle to an `Arc`, freed with `_free`; one that is `Copy`, such as std's `Instant`, whose padding a `rustc` may place anywhere, is copied out of its handle where Rust takes it by value, and a closure neither takes nor returns one by value |
| any other type | an object: an opaque handle to an `Arc`, freed with `_free`; one that is `Copy`, such as std's `Instant`, whose padding a `rustc` may place anywhere, is copied out of its handle where Rust takes it by value, and a closure neither takes nor returns one by value; one that is not `Send`, such as kio's `clock::Entered`, stays on the thread that made it, as [the C ABI](#the-c-abi)'s threads say |
| a type whose only generic parameters are lifetimes, such as `Path<'a>` | an object holding its `'static` form |
| a generic type, at each instance it infers | that instance as any other type, with each method whose impl and own bounds it meets; any other instance is refused |
| a `pub` field of an object or opaque value | a getter returning a copy, and a setter assigning in place, as `x.field = value` does |
Expand Down Expand Up @@ -292,6 +292,28 @@ where it was while its file is unchanged.
while a getter's copy is C's own: a nested field is got, set, and set back. A type
whose C++ copies share one value has `_borrowed`, true while a call or future borrows
it, so moving it out would fail.
- **Threads**: a value that is not `Send`, an object or a future, stays on the thread that
made it, which alone borrows, moves, polls, or drops it. A future is such a value if it
holds one, as a poll function's holds its receiver and parameters, or makes one, as its
output, which its last poll makes on its thread. A call or poll on another
fails with `<PREFIX>_STATUS_NOT_SEND` before any Rust code runs, so such a future's poll
takes a trailing `status` too. A `_free` or `_drop` elsewhere drops nothing there: it
queues the drop to the value's thread, which runs it at its next check of one of its
values or as it exits. One freed once its thread exited leaks, printing why, since
nothing may drop it. A function that makes such a value, taking none or only in an
`Option`, has a twin `<name>_homed` of the same signature, as do its future's start,
`<name>_start_homed`, and `Default`'s, `<T>_default_homed`: with no such value passed,
it runs on a home, a thread Rust owns, which the value then stays on, and each later
call on it, from any thread, runs there while the caller waits, as does a call on a
value that is not `Send` it returns; with one passed, it runs as the function does. The first present of
a call's receiver and its parameters that are handles of such values, bare or in an
`Option`, sends it to that value's home, if it lives on one; a value made on a thread
the caller owns is not sent, so a call on it from another thread fails its check. Values from different homes, or one
nested in a list or a record, are not sent: the call runs on the first's home, where
any other fails its check with `<PREFIX>_STATUS_NOT_SEND`. A home waiting on a call into
Dart, or on another home, runs meanwhile what that call asks of its own values. A
binding whose threads move calls the twins: Go and Dart for every such value, Kotlin
and Swift for such a future made from none, which a pool's thread then polls.
- **Opaque values** are `typedef struct <T> { uintN_t opaque[n]; } <T>;`, the bytes of a
`Copy` type with private fields, in units of its alignment up to 8 bytes: C copies one
as any struct, and passes `&self` as a `const <T> *` and `&mut self`, a field's setter
Expand Down Expand Up @@ -447,7 +469,9 @@ packages place it in.
No export keeps a view or reference past its call, so none carries
`[[clang::lifetime_capture_by]]`; the first that does adds it.
- **Checks**: a call passes no `status`, so a borrow or move Rust's rules refuse aborts
with its message, naming the function, as C's does with a NULL one.
with its message, naming the function, as C's does with a NULL one: so does a use or
poll of a value that is not `Send` on another thread than the one that made it, and
one destroyed on another drops on its own thread at its next call or as it exits.
- **Sharing** stands in for `clone` where no call can tell the two apart but by counting
an `Arc`'s or `Rc`'s clones, which the exporter decides at compile time. A type's copies share when it is `Clone`; `Sync`,
since one that is not is borrowed on one thread at a time, which copies on two threads
Expand Down Expand Up @@ -552,7 +576,12 @@ the rest cross encoded.
once the GC collects it, on a daemon thread a phantom reference queue feeds. A `self`
method, or passing the object by value, moves its value out and closes it once the call
returns. `Clone` is `clone()`, `PartialEq` is `equals`, and `Hash` is `hashCode`, Rust's
hash folded as `Long.hashCode` folds it, or 0 without one.
hash folded as `Long.hashCode` folds it, or 0 without one. A value that is not `Send`
throws an `IllegalStateException` when used on another thread than the one that made
it, and closed or collected on another, it drops on its own at its next call or as it
exits. A future that is not `Send` made from none lives on a home, so a coroutine a
dispatcher resumes on any thread polls it; one a value's method makes stays on that
value's thread.
A field is a `val`, `firstGet`, and its setter a function, `firstSet(value)`, named as
the C ones, since setting an object moves it in and closes its handle, which an
assignment would hide.
Expand Down Expand Up @@ -698,7 +727,10 @@ caller imports it with no ignores.
since setting an object moves it in and closes it, which an assignment would hide.
- **Checks**: a borrow or move Rust's rules refuse raises, naming the function and the rule,
before any Rust code runs, so the call changed nothing: `ValueError` for a value moved out, or a lent object that outlived the one it
borrows from, as for a closed object, and `RuntimeError` for any other.
borrows from, as for a closed object, and `RuntimeError` for any other, as for a value
that is not `Send` used on another thread than the one that made it. Freed on another,
as the collector or the last reference there frees it, such a value drops on its own
thread at its next call or as it exits.
- **Records** are slotted dataclasses, compared by their fields, a float by IEEE `==` even
against itself, as Rust does, and **enums** an `Enum`
of upper-case members, or for one with data a class of a dataclass per variant,
Expand Down Expand Up @@ -810,7 +842,14 @@ value of a Rust type crosses as one Swift type that holds it exactly, and back u
holds until it returns, and moving its value out closes it, after which a call throws. A
field is a computed property, `firstGet`, and its setter a function, `firstSet(value)`,
named as the C ones, since setting an object moves it in, which an assignment would hide.
An object is `Sendable`, since Rust checks each borrow at run time.
An object is `Sendable` where Rust lets it cross threads, checking each borrow at run
time: a class if its type is `Send` and `Sync`, since its holders share it, and a
noncopyable struct if `Send`, since it only moves. A record, enum, or tuple struct is
`Sendable` only if each handle it holds is, so Swift's compiler keeps the others on one
task, and a use on another thread anyway, as after a suspension that resumed elsewhere,
throws a `CheckError`. A type thrown as an error is `Sendable` unchecked, since
`Swift.Error` requires it. A future that is not `Send` made from none lives on a home, so
any executor awaits it.
- **Checks**: a borrow or move Rust's rules refuse at run time, such as a borrow of a value
that is not `Sync` on a second thread, throws a `CheckError`, holding the function and
the rule, before any Rust code runs, so the call changed nothing. So every function whose objects can fail a check `throws`, and a
Expand Down Expand Up @@ -954,6 +993,9 @@ reads a go.mod.
and returns it beside the value, so the call allocates nothing for it: cgo moves to the
heap any Go local whose address C gets, since C may call back into Go, which can move the
goroutine's stack.
- **Threads**: a goroutine moves between threads, so a value that is not `Send` is made on
a home, a thread Rust owns, which runs each call on it, from any goroutine, while the
goroutine's thread waits, and drops it there once closed or collected.
- **Records** are structs, and **plain enums** an `int32` type with a constant per
variant (`ShapeSquare`). An enum with data is an interface each variant's struct
implements (`EventMoved{V0: p}`), sealed so only the package's do; its methods are the
Expand Down Expand Up @@ -1177,7 +1219,8 @@ the library's own URI, mapped to the library by a build hook or by `--native-ass
future's poll and `cancel()` included, runs on a thread of its own, acting as the
caller's for the handles it borrows, while the isolate's thread runs what Rust calls
into Dart meanwhile. Any other call runs on the isolate's thread, since nothing it waits
on can call into Dart.
on can call into Dart. An isolate may move between threads, so a value that is not
`Send` is made on a home, a thread Rust owns, which runs each call on it.
- **The contract** is checked at the first call, before any other: a Dart file and a
library from different builds throw a `StateError`.

Expand Down
21 changes: 21 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1063,6 +1063,27 @@ fn main() {
"farther hop {}",
api::farther_hop(Pair { left: near, right: far }).get()
);
// A value that is not `Send`, all on this thread: a handle to a local's count, and a
// local made from none.
let local = api::Local::new();
let shared = api::local_or_new(Some(&local));
let bumped = local.bump();
println!("local {bumped} {}", shared.bump());
println!("local fresh {}", api::local_or_new(None).bump());
println!("local either {}", api::bump_either(None, &shared));
println!("local later {}", finish(api::local_or_new_later(Some(&local))).bump());
println!("local later fresh {}", finish(api::local_or_new_later(None)).bump());
}

/// `future`'s output, polled on this thread until it is ready.
fn finish<F: std::future::Future>(future: F) -> F::Output {
let mut future = pin!(future);
let mut cx = Context::from_waker(Waker::noop());
loop {
if let Poll::Ready(output) = future.as_mut().poll(&mut cx) {
return output;
}
}
}

/// A path no Rust string spells: on Unix, bytes that are not UTF-8; on Windows, a lone
Expand Down
174 changes: 174 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1914,6 +1914,180 @@ impl Tallies {
}
}

impl Tally {
/// Counts once its future, which holds an `Rc` across a yield and so is not `Send`, is
/// polled a second time: what a binding polling on a pool runs on a home.
pub async fn bump_later(&self) -> u32 {
let held = std::rc::Rc::new(());
yielded(0).await;
drop(held);
self.bump()
}
}

/// A count its handles share through an `Rc`, so not `Send`: it stays on the thread that
/// made it, which alone calls, polls, and drops it, as each method checks.
pub struct Local {
count: std::rc::Rc<std::cell::Cell<u32>>,
thread: std::thread::ThreadId,
}

impl Default for Local {
fn default() -> Self {
Self::new()
}
}

impl Local {
pub fn new() -> Self {
Self {
count: std::rc::Rc::new(std::cell::Cell::new(0)),
thread: std::thread::current().id(),
}
}

/// Counts once, on its own thread.
pub fn bump(&self) -> u32 {
self.here();
self.count.set(self.count.get() + 1);
self.count.get()
}

/// Another handle to the same count.
pub fn share(&self) -> Local {
self.here();
Local {
count: self.count.clone(),
thread: self.thread,
}
}

/// Counts once its future, which is not `Send`, is polled a third time.
pub async fn later(&self) -> u32 {
yielded(0).await;
self.bump()
}

/// What `f` returns, called on this local's thread, where it may use the local again.
pub fn visit(&self, f: impl Fn() -> u32) -> u32 {
self.here();
f()
}

/// Counts once, as a poll: its future holds the local, so is not `Send` either.
pub fn poll_count(&self, cx: &mut std::task::Context<'_>) -> std::task::Poll<u32> {
let _ = cx;
std::task::Poll::Ready(self.bump())
}

/// Which thread it lives on, numbered from 1 in the order each first asked.
pub fn thread_number(&self) -> u64 {
self.here();
static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
thread_local!(static NUMBER: u64 = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed));
NUMBER.with(|number| *number)
}

/// Whether this runs on its own thread, which every use of it must.
pub fn on_own_thread(&self) -> bool {
std::thread::current().id() == self.thread
}

fn here(&self) {
assert!(self.on_own_thread(), "a Local is used off its own thread");
}
}

/// Equal to another handle to the same count.
impl PartialEq for Local {
fn eq(&self, other: &Self) -> bool {
self.here();
std::rc::Rc::ptr_eq(&self.count, &other.count)
}
}

impl Eq for Local {}

/// Hashed by the count it shares, as its equality compares.
impl std::hash::Hash for Local {
fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
self.here();
std::rc::Rc::as_ptr(&self.count).hash(state);
}
}

impl Drop for Local {
fn drop(&mut self) {
// A drop elsewhere would panic, which aborts through the C ABI.
self.here();
LOCALS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
}
}

static LOCALS: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);

/// How many locals have dropped, each on its own thread.
pub fn locals_dropped() -> u32 {
LOCALS.load(std::sync::atomic::Ordering::Relaxed)
}

/// A handle to `local`'s count if there is one, else a new local: made where `local`
/// stays, or, with none, wherever a local made from nothing would be.
pub fn local_or_new(local: Option<&Local>) -> Local {
local.map_or_else(Local::new, Local::share)
}

/// `local_or_new` after a yield: a future that is not `Send`, made where `local` stays,
/// or, with none, wherever a local made from nothing would be.
pub async fn local_or_new_later(local: Option<&Local>) -> Local {
yielded(0).await;
local_or_new(local)
}

/// The first local's count bumped if there is one, else the second's.
pub fn bump_either(first: Option<&Local>, second: &Local) -> u32 {
first.unwrap_or(second).bump()
}

/// A new local, made after a yield: the future is `Send`, but its output is not, so it is
/// made where the future is polled.
pub async fn local_after() -> Local {
yielded(0).await;
Local::new()
}

/// `n` doubled after a yield, through an `Rc` it holds across it: a future that is not
/// `Send`, though nothing it takes is not.
pub async fn local_later(n: u32) -> u32 {
let n = std::rc::Rc::new(n);
yielded(0).await;
*n * 2
}

/// What a poll registers that is not `Send`, as `Waiter` is but through an `Rc`: a future
/// polling with one keeps it between polls, so is not `Send` either.
pub struct LocalWaiter(std::rc::Rc<Waker>);

impl LocalWaiter {
pub fn new(waker: Waker) -> Self {
Self(std::rc::Rc::new(waker))
}

/// `n` at once: a poll of the waiter it is a method of, which exports as a future
/// making and keeping it.
pub fn poll_ready(&self, n: u32) -> Poll<u32> {
let _ = &self.0;
Poll::Ready(n)
}
}

/// `n` tripled at once: a poll through a waiter that is not `Send`, which exports as a
/// future making and keeping it.
pub fn poll_tripled(waiter: &LocalWaiter, n: u32) -> Poll<u32> {
let _ = &waiter.0;
Poll::Ready(n * 3)
}

static DROPPED: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);

/// A level its clones share through an `Arc`, with no `&mut self` method: a clone no call
Expand Down
Loading