diff --git a/ffi/README.md b/ffi/README.md index 9ccd13ec8..2a293f73f 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -71,6 +71,7 @@ export's, and adds nothing; another crate's type is refused. | a generic function or method, at each instance `instances` names | that instance in place of the rules below, at each instance of its type; one whose bounds fail, or that nothing exported reaches, is refused | | a `pub` field of an object | a getter returning a copy | | a `pub` trait | a callback interface: a table of C functions and their data | +| a type parameter or `impl` bounded by `Fn`, `FnMut`, or `FnOnce`, which no lifetime bound or return lets outlive the call | a C function and its `void *` data, which Rust calls only during the call; any other closure is refused | | `fn` and inherent `pub` methods | functions named through their type | | `Result` | `bool f(..., T *out, E *err)` | | a returned tuple `(A, B)` | one out pointer each: `void f(..., A *out0, B *out1)` | @@ -119,6 +120,11 @@ refused, and the census counts why. - **Callbacks** are a struct of a table and its data. Rust calls `free` once it drops the implementation, and may call the others from any thread. A callback takes scalars and buffers lent for the call, and returns a scalar. +- **Closures** lent for a call are a function and its data, which Rust calls only during + the call, from any thread. One takes what a callback takes, and objects by reference, + each lent as a handle to the value where it is for that call: C borrows it no further + than Rust lent it, and moving out of it, freeing it, or keeping a borrow past the call + aborts. - **The contract** is a hash of the header's declarations, its docs included: the header defines it as `_CONTRACT`, and `_contract()` returns it from the library built with the header. A binding checks the two match before any other call, so a header @@ -173,4 +179,5 @@ moq's crates export through `target/moq-ffi`, an empty library on each that `jus writes in place of moq-ffi's remainder. `moq/moq.c` publishes and subscribes to a moq-net track in one process, polling each read, scopes an origin to moq-pattern's patterns and hands it to a client to publish, polls its driver until the origin's last owner drops, reads an OpusHead into hang's catalog through moq-mux, -and publishes a binary track the catalog lists. +publishes a binary track the catalog lists, and reads the catalog lent to C through +`catalog::Producer::mutate`. diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index 77436b4e2..74b6e07b7 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -100,6 +100,14 @@ fn main() { let mut last = registry.last().unwrap().clone(); let _ = last.add(10); println!("last {} lent {}", registry.last().unwrap().get(), last.get()); + // A closure lent for the call edits the first counter through a handle. + let edited = registry.edit(|counter| { + let _ = counter.add(5); + counter.edited() && counter.get() == 6 + }); + println!("edit {edited} {}", registry.first.get()); + println!("walk {}", api_lib::walk(3, |cursor| cursor.at() * 2)); + println!("offset {}", api_lib::offset(|| 7, 3)); let name = Name::owned("a".to_string()); let mut joined = name.join(&Name::owned("b".to_string())); @@ -148,6 +156,11 @@ fn main() { println!("write {}", logger.write("hi")); drop(logger); println!("dropped"); + let kept = api_lib::filter(vec![1, 2, 3, 4], |level, line| { + println!("filter {level} {line}"); + level > 2 + }); + println!("filtered {kept}"); let channel = Channel::new(); let count = Arc::new(Count(AtomicUsize::new(0))); @@ -196,6 +209,7 @@ fn main() { tally.bump(); println!("tally {} {}", tally.bump(), tally == tally); println!("both {}", api_lib::bump_both(&tally, &tally)); + println!("peek {}", api_lib::peek(&tally, |tally| tally.bump())); let area = api_lib::grow(&dep::Area::new(Size { width: 2, height: 3 }), 1); let size = area.size(); diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index 52f703f29..37f5d19ee 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -114,6 +114,12 @@ impl Counter { } } + /// Whether this is the counter [`Registry::edit`] lends, by its address, which a handle + /// lent for the call keeps. + pub fn edited(&self) -> bool { + std::ptr::from_ref(self) as usize == EDITING.load(std::sync::atomic::Ordering::Relaxed) + } + /// Consumes the counter. pub fn into_label(self, at: Option) -> Label { Label { @@ -176,8 +182,21 @@ impl Registry { pub fn push(&mut self, counter: Counter) { self.last = Some(counter); } + + /// The first counter lent to `edit` for the call, returning what `edit` does: a closure + /// called only during the call, which C lends as a function. + pub fn edit(&mut self, edit: impl FnOnce(&mut Counter) -> bool) -> bool { + EDITING.store( + std::ptr::from_ref(&self.first) as usize, + std::sync::atomic::Ordering::Relaxed, + ); + edit(&mut self.first) + } } +/// The address of the counter [`Registry::edit`] lends. +static EDITING: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0); + /// A name that may borrow its text: its only generic parameter is a lifetime, so a /// handle holds `Name<'static>`, which borrows nothing. #[derive(Clone, Debug, PartialEq)] @@ -389,6 +408,15 @@ pub fn emit(log: impl Log, lines: Vec) -> u32 { lines.iter().filter(|&&n| log.log(n, &format!("line {n}"))).count() as u32 } +/// Each line to `keep` on another thread, returning how many it kept: a lent closure may +/// run on any thread until the call returns. +pub fn filter(lines: Vec, mut keep: impl FnMut(u8, &str) -> bool + Send) -> u32 { + std::thread::scope(|scope| { + let kept = scope.spawn(move || lines.iter().filter(|&&n| keep(n, &format!("line {n}"))).count()); + kept.join().expect("the thread finishes") as u32 + }) +} + /// Holds a foreign implementation as a trait object, dropping it with itself. pub struct Logger { sink: Box, @@ -499,6 +527,32 @@ pub fn bump_both(a: &Tally, b: &Tally) -> u32 { a.bump() + b.bump() } +/// What `by` returns, plus `by_data`: a closure taking nothing, whose data C names apart. +pub fn offset(by: impl Fn() -> u32, by_data: u32) -> u32 { + by() + by_data +} + +/// A position, which C reaches only as [`walk`] lends it. +pub struct Cursor { + at: u64, +} + +impl Cursor { + pub fn at(&self) -> u64 { + self.at + } +} + +/// A cursor at each of `0..steps` lent shared to `visit`, summing what it returns. +pub fn walk(steps: u64, mut visit: impl FnMut(&Cursor) -> u64) -> u64 { + (0..steps).map(|at| visit(&Cursor { at })).sum() +} + +/// The tally lent shared to `peek` for the call, on one thread, as it is not `Sync`. +pub fn peek(tally: &Tally, peek: impl FnOnce(&Tally) -> u32) -> u32 { + peek(tally) +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 59ce309f8..8069a33cc 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -24,6 +24,11 @@ fixtures/reject/src/lib.rs:192:1: rust2-ffi: cannot export fn `lend`: Waker outs fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:207:2: rust2-ffi: fn `reject_fixture::Limit::max` and field `reject_fixture::Limit::max` are both `reject_limit_max` in C fixtures/reject/src/lib.rs:199:2: note: field `reject_fixture::Limit::max` is here +fixtures/reject/src/lib.rs:213:1: rust2-ffi: cannot export fn `spawn`: closure kept past the call `impl FnOnce() + Send + 'static`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:218:1: rust2-ffi: cannot export fn `later`: closure kept past the call `impl FnOnce()`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:223:1: rust2-ffi: cannot export fn `twice`: closure bound `std::clone::Clone`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:229:1: rust2-ffi: cannot export fn `both`: closure type taken twice `F`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:235:1: rust2-ffi: cannot export fn `read`: lent object that borrows `&Text<'_>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:26:1: rust2-ffi: cannot export fn `borrowing`: borrowing future from a function that is not async; exclude it in the config to leave it out fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:36:1: rust2-ffi: instance `Opaque` in the config exports nothing: `reject_fixture::Opaque` takes no type arguments diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs index 45b7bd75f..9872e826b 100644 --- a/ffi/fixtures/reject/src/lib.rs +++ b/ffi/fixtures/reject/src/lib.rs @@ -208,3 +208,30 @@ impl Limit { self.max.max(1) } } + +/// A closure kept past the call, as a `'static` bound lets it be. +pub fn spawn(task: impl FnOnce() + Send + 'static) { + std::thread::spawn(task); +} + +/// A closure the future holds past the call. +pub async fn later(task: impl FnOnce()) { + task() +} + +/// A closure bound by more than C's function can meet. +pub fn twice(f: impl Fn() + Clone) { + f.clone()(); + f() +} + +/// One closure type for two parameters, which C's two functions cannot be. +pub fn both(a: F, b: F) { + a(); + b() +} + +/// An object lent only for as long as it borrows, which a handle's `'static` outlives. +pub fn read(f: impl FnOnce(&Text<'_>)) { + f(&Text("")) +} diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index cae25bc64..af176bc38 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -409,7 +409,6 @@ exclude = [ "catalog::Producer::json_snapshot", "catalog::Producer::json_stream", "catalog::Producer::modify", - "catalog::Producer::mutate", "catalog::Producer::stats", "catalog::Producer::text", "catalog::Producer::track", diff --git a/ffi/moq/moq.c b/ffi/moq/moq.c index 80079a231..00ff4d782 100644 --- a/ffi/moq/moq.c +++ b/ffi/moq/moq.c @@ -1,7 +1,7 @@ /* moq's exported C API against the real library: a broadcast's track, published and * subscribed to in one process, with every read polled as a future, and an origin. * moq-pattern, moq-clock, moq-tokio, hang, and moq-mux export into the same library, and - * each names the others' types. + * each names the others' types, and the catalog is lent to C for a call. * * It needs no runtime: the waker counts wakes, and each poll that must wait is polled * again after the write that wakes it. */ @@ -35,6 +35,21 @@ static int is(moq_buf buf, const char *s) { return same; } +/* The catalog `mutate` lends for its call, which lists the binary track: counts it in + * data. */ +static void lists_state(void *data, moq_hang_catalog *catalog) { + moq_buf json; + moq_hang_error *hang_err = NULL; + CHECK(moq_hang_catalog_to_json(catalog, &json, &hang_err)); + for (size_t i = 0; i + 5 <= json.len; i++) { + if (memcmp(json.ptr + i, "state", 5) == 0) { + (*(int *)data)++; + break; + } + } + moq_buf_free(json); +} + static int wakes = 0; static void wake(void *data) { @@ -262,6 +277,9 @@ int main(void) { moq_track_producer_free(state); CHECK(is(moq_binary_snapshot_name(snapshot), "state")); CHECK(moq_binary_snapshot_update(snapshot, str("latest"), &mux_err)); + int listed_state = 0; + CHECK(moq_catalog_producer_mutate(catalog, lists_state, &listed_state, &mux_err)); + CHECK(listed_state == 1); moq_binary_snapshot_free(snapshot); moq_catalog_producer_free(catalog); moq_broadcast_producer_free(publisher); diff --git a/ffi/runtime/rt.rs b/ffi/runtime/rt.rs index 65e0fc37a..f2b34e6a1 100644 --- a/ffi/runtime/rt.rs +++ b/ffi/runtime/rt.rs @@ -1,5 +1,5 @@ -//! The runtime every export shares: buffers, handles, wakers, and futures across the -//! C ABI. rust2-ffi copies it beside the generated code. +//! The runtime every export shares: buffers, handles, lent functions, wakers, and futures +//! across the C ABI. rust2-ffi copies it beside the generated code. //! //! A broken contract across the ABI (a null or consumed handle, a handle borrowed in a //! way Rust's rules forbid, invalid UTF-8, a future polled after it finished) aborts with @@ -7,7 +7,7 @@ use std::cell::UnsafeCell; use std::ffi::c_void; -use std::mem::ManuallyDrop; +use std::mem::MaybeUninit; use std::ops::{Deref, DerefMut}; use std::pin::Pin; use std::sync::Arc; @@ -217,7 +217,9 @@ const TAKEN: usize = usize::MAX - 1; pub struct Object { state: AtomicUsize, depth: UnsafeCell, - value: UnsafeCell>, + /// The value a lent handle points at, where Rust lent it, or null if it owns `value`. + lent: *mut T, + value: UnsafeCell>, } /// This thread's id for [`Object::borrow_local`]: the address of a thread local, which no @@ -242,11 +244,20 @@ impl Object { Arc::into_raw(Arc::new(Self { state: AtomicUsize::new(0), depth: UnsafeCell::new(0), - value: UnsafeCell::new(ManuallyDrop::new(value)), + lent: std::ptr::null_mut(), + value: UnsafeCell::new(MaybeUninit::new(value)), })) .cast() } + /// The value: its own, or the one it was lent. + fn value(&self) -> *mut T { + match self.lent.is_null() { + true => self.value.get().cast(), + false => self.lent, + } + } + /// # Safety /// `handle` is null or a live handle of this type. unsafe fn get<'a>(handle: *const c_void, what: &str) -> &'a Self { @@ -371,6 +382,46 @@ impl Object { } } + /// Lend `value` to C as a handle while `f` runs, shared as `&T` lends it. + pub fn lend(value: &T, what: &str, f: impl FnOnce(*const c_void) -> R) -> R + where + T: Sync, + { + Self::lending(std::ptr::from_ref(value).cast_mut(), 1, 0, what, f) + } + + /// Lend a value that is not `Sync` shared, as [`Self::lend`], on this thread alone. + pub fn lend_local(value: &T, what: &str, f: impl FnOnce(*const c_void) -> R) -> R { + Self::lending(std::ptr::from_ref(value).cast_mut(), thread(), 1, what, f) + } + + /// Lend `value` exclusively, as `&mut T` lends it. + pub fn lend_mut(value: &mut T, what: &str, f: impl FnOnce(*const c_void) -> R) -> R { + Self::lending(std::ptr::from_mut(value), 0, 0, what, f) + } + + /// Lend the value at `ptr` to C as a handle while `f` runs, holding the borrow `state` + /// and `depth` describe, if any, so C borrows it no further than Rust lent it. C may + /// neither move it out, nor free the handle, nor keep a borrow past `f`. + fn lending(ptr: *mut T, state: usize, depth: usize, what: &str, f: impl FnOnce(*const c_void) -> R) -> R { + let object = Arc::new(Self { + state: AtomicUsize::new(state), + depth: UnsafeCell::new(depth), + lent: ptr, + value: UnsafeCell::new(MaybeUninit::uninit()), + }); + // A second count, which a free by C would take, so the handle outlives it. + let spare = Arc::clone(&object); + let result = f(Arc::as_ptr(&object).cast()); + match Arc::strong_count(&object) { + 2 if object.state.load(Ordering::Acquire) == state => {} + 1 => fail(what, "a lent handle was freed"), + _ => fail(what, "a lent handle is still borrowed"), + } + drop(spare); + result + } + /// Move the value out, leaving the handle to be freed. /// /// # Safety @@ -378,6 +429,9 @@ impl Object { pub unsafe fn take(handle: *const c_void, what: &str) -> T { // SAFETY: the caller's contract. let object = unsafe { Self::get(handle, what) }; + if !object.lent.is_null() { + fail(what, "a lent handle's value cannot move out"); + } if let Err(state) = object .state .compare_exchange(0, TAKEN, Ordering::Acquire, Ordering::Relaxed) @@ -388,7 +442,7 @@ impl Object { } } // SAFETY: TAKEN excludes every other access, and the value is never read again. - unsafe { ManuallyDrop::take(&mut *object.value.get()) } + unsafe { (*object.value.get()).assume_init_read() } } /// Release the caller's handle. @@ -405,9 +459,9 @@ impl Object { impl Drop for Object { fn drop(&mut self) { - if *self.state.get_mut() != TAKEN { - // SAFETY: the last reference is gone and the value was never taken. - unsafe { ManuallyDrop::drop(self.value.get_mut()) }; + if self.lent.is_null() && *self.state.get_mut() != TAKEN { + // SAFETY: the last reference is gone, and the value is its own and never taken. + unsafe { self.value.get_mut().assume_init_drop() }; } } } @@ -420,7 +474,7 @@ impl Deref for Shared<'_, T> { type Target = T; fn deref(&self) -> &T { // SAFETY: a shared borrow is held. - unsafe { &*self.object.value.get() } + unsafe { &*self.object.value() } } } @@ -438,7 +492,7 @@ impl Deref for Local<'_, T> { type Target = T; fn deref(&self) -> &T { // SAFETY: this thread holds the value shared. - unsafe { &*self.object.value.get() } + unsafe { &*self.object.value() } } } @@ -461,14 +515,14 @@ impl Deref for Exclusive<'_, T> { type Target = T; fn deref(&self) -> &T { // SAFETY: the exclusive borrow is held. - unsafe { &*self.object.value.get() } + unsafe { &*self.object.value() } } } impl DerefMut for Exclusive<'_, T> { fn deref_mut(&mut self) -> &mut T { // SAFETY: the exclusive borrow is held. - unsafe { &mut *self.object.value.get() } + unsafe { &mut *self.object.value() } } } @@ -486,7 +540,7 @@ impl Deref for SharedArc { type Target = T; fn deref(&self) -> &T { // SAFETY: a shared borrow is held. - unsafe { &*self.object.value.get() } + unsafe { &*self.object.value() } } } @@ -504,14 +558,14 @@ impl Deref for ExclusiveArc { type Target = T; fn deref(&self) -> &T { // SAFETY: the exclusive borrow is held. - unsafe { &*self.object.value.get() } + unsafe { &*self.object.value() } } } impl DerefMut for ExclusiveArc { fn deref_mut(&mut self) -> &mut T { // SAFETY: the exclusive borrow is held. - unsafe { &mut *self.object.value.get() } + unsafe { &mut *self.object.value() } } } @@ -572,6 +626,26 @@ impl Drop for Foreign { } } +/// The data of a function C lends for a call, which Rust only passes back to it. +#[derive(Clone, Copy)] +pub struct Data(*mut c_void); + +// SAFETY: the lent function's contract: it may be called from any thread. +unsafe impl Send for Data {} +// SAFETY: as above. +unsafe impl Sync for Data {} + +impl Data { + pub fn new(data: *mut c_void) -> Self { + Self(data) + } + + /// The pointer, through a method so a closure captures `Data` whole, not its field. + pub fn get(self) -> *mut c_void { + self.0 + } +} + /// Writes a finished future's result through the poll's out pointers, one per value it /// returns, and its error pointer, returning the poll. The poll that finishes the future /// calls it, so it never crosses threads. diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 4504f1628..5e7de9108 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -50,6 +50,10 @@ pub enum Ty { Out(Box), /// A pointer the callee only reads through: a value's receiver. In(Box), + /// A function lent for the call, taking its data first: what it takes and returns. + Fn(Vec, Box), + /// The data a lent function takes, which Rust only passes back to it. + Data, } /// A C function: its name, parameters, and return type. @@ -271,6 +275,7 @@ impl<'a> Abi<'a> { constant: false, }, Type::Callback(i, _) => Ty::Struct(self.callback(*i)), + Type::Closure(params, ret) => Ty::Fn(params.iter().map(|p| self.ty(p)).collect(), Box::new(self.ty(ret))), Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => Ty::Struct(self.range(ty)), Type::Tuple(_) => unreachable!("a tuple is only returned, through out parameters"), } @@ -325,7 +330,18 @@ impl<'a> Abi<'a> { }, _ => self.ty(¶m.ty), }; - params.push((escape(¶m.name), ty)); + let name = escape(¶m.name); + if let Type::Closure(..) = param.ty { + // Named apart from every parameter of the function, which C requires. + let mut data = format!("{name}_data"); + while function.params.iter().any(|p| escape(&p.name) == data) { + data.push('_'); + } + params.push((name, ty)); + params.push((data, Ty::Data)); + continue; + } + params.push((name, ty)); } let mut outs = Vec::new(); match &function.ok { @@ -502,6 +518,10 @@ impl<'a> Abi<'a> { } Type::Ref(_, inner) | Type::Box(inner) => stack.push(inner), Type::Tuple(elements) => stack.extend(elements), + Type::Closure(params, ret) => { + stack.extend(params); + stack.push(ret); + } Type::Range(_) | Type::Bound(_) => { ranges.insert(self.range(ty), ty.clone()); } diff --git a/ffi/src/c.rs b/ffi/src/c.rs index 72d4eb9c1..da479cdfd 100644 --- a/ffi/src/c.rs +++ b/ffi/src/c.rs @@ -78,6 +78,13 @@ impl Header<'_> { Ty::Poll => space(&self.abi.rt("poll")), Ty::Out(inner) => self.decl(inner, &format!("*{name}")), Ty::In(inner) => format!("const {}", self.decl(inner, &format!("*{name}"))), + Ty::Fn(params, ret) => { + let params: Vec = std::iter::once("void *data".to_string()) + .chain(params.iter().map(|p| self.decl(p, ""))) + .collect(); + self.decl(ret, &format!("(*{name})({})", params.join(", "))) + } + Ty::Data => format!("void *{name}"), } } @@ -384,6 +391,8 @@ impl Header<'_> { .call .params .iter() + // A lent function's data follows it, and is no parameter of its own. + .filter(|(_, ty)| *ty != Ty::Data) .zip(by_value) .filter(|((_, ty), by_value)| *by_value && matches!(ty, Ty::Handle { constant: false, .. })) .map(|((name, _), _)| format!("`{name}`")) @@ -394,6 +403,24 @@ impl Header<'_> { moved.join(" and ") )); } + for param in &function.params { + let Type::Closure(params, _) = ¶m.ty else { + continue; + }; + let name = abi::escape(¶m.name); + let at = (export.call.params.iter()) + .position(|(n, _)| *n == name) + .expect("a C parameter for each"); + let data = &export.call.params[at + 1].0; + docs.push_str(&format!( + "\n\nRust calls `{name}` with `{data}` only during the call, from any thread." + )); + if params.iter().any(|p| matches!(p.base(), Type::Object(_))) { + docs.push_str(&format!( + "\nA handle it lends lives only for that call of `{name}`: free none, nor move out of one." + )); + } + } self.out.push_str(&comment(docs.trim(), "")); if let Some((handle, poll, free)) = &export.future { self.line(format!("typedef struct {handle} {handle};")); diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 22ebcd2a0..4728df24a 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -166,8 +166,8 @@ struct Collector<'tcx> { /// Items the walk left out, and why: `excluded` or `doc(hidden)`. left_out: rustc_data_structures::fx::FxHashMap, /// The type parameters of the function being mapped that take a foreign - /// implementation, with the callback each takes. - impls: std::cell::RefCell, usize)>>, + /// implementation or a lent closure, with the type each takes. + impls: std::cell::RefCell, Type)>>, bytes: Option, /// `std::ops::Bound`, and `std::ops::RangeBounds`, which names it. bound: Option, @@ -956,6 +956,12 @@ impl<'tcx> Collector<'tcx> { if let Some(err) = &function.err { returns(api, err, &mut reached); } + // A closure's objects are lent to C for each call of it. + for param in &function.params { + if let Type::Closure(params, _) = ¶m.ty { + params.iter().for_each(|ty| returns(api, ty, &mut reached)); + } + } } } reached.retain(|&i| !held[i]); @@ -1366,11 +1372,7 @@ impl<'tcx> Collector<'tcx> { let (clause, _) = clause.skip_norm_wip(); if let Some(trait_pred) = clause.as_trait_clause() { let tr = trait_pred.def_id(); - let auto = [sym::Send, sym::Sync] - .iter() - .any(|&item| tcx.is_diagnostic_item(item, tr)) - || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); - if !auto { + if !marker(tcx, tr) { errs.push(why("supertrait", tcx.def_path_str(tr))); } } @@ -1641,6 +1643,13 @@ impl<'tcx> Collector<'tcx> { _ if i < count => {} GenericArgKind::Lifetime(_) => {} GenericArgKind::Const(_) => errs.push(why("const generic", "")), + // The parameter stays, and `ty` maps it to the closure. + GenericArgKind::Type(param) if let Some(closure) = self.closure(def_id, param, &base) => { + match closure { + Ok(closure) => self.impls.borrow_mut().push((param, closure)), + Err(why) => errs.push(why), + } + } GenericArgKind::Type(param) => match self.choose(def_id, param, &base) { Ok(ty) => args[i] = ty.into(), // The parameter stays, and `ty` maps it to the foreign implementation. @@ -1648,7 +1657,9 @@ impl<'tcx> Collector<'tcx> { construct: "callback bound", .. }) if let Some(callback) = self.foreign(def_id, param) => { - self.impls.borrow_mut().push((param, callback)); + self.impls + .borrow_mut() + .push((param, Type::Callback(callback, Dyn::Impl))); } Err(why) => errs.push(why), }, @@ -1802,6 +1813,106 @@ impl<'tcx> Collector<'tcx> { } } + /// The closure a type parameter takes, if an `Fn` trait bounds it: one the callee calls + /// only during the call, which C lends as a function. A closure that may outlive the + /// call, by a lifetime bound or by what the function returns, is refused. + fn closure(&self, def_id: DefId, param: Ty<'tcx>, base: &[ty::GenericArg<'tcx>]) -> Option> { + let tcx = self.tcx; + let clauses = tcx.clauses_of(def_id).instantiate(tcx, tcx.mk_args(base)).clauses; + let clauses: Vec<_> = clauses.iter().map(|clause| clause.skip_norm_wip()).collect(); + let output = tcx.lang_items().fn_once_output(); + let mut inputs = None; + let mut ret = None; + let mut kept = false; + let mut other = Vec::new(); + // Whether a bound on another type names it, such as `T: From`. + let mentions = |clause: ty::Clause<'tcx>| { + let args: Vec> = match (clause.as_trait_clause(), clause.as_projection_clause()) { + (Some(pred), _) => pred.skip_binder().trait_ref.args.to_vec(), + (_, Some(pred)) => (pred.skip_binder().projection_term.args.iter()) + .chain(pred.skip_binder().term.as_type().map(Into::into)) + .collect(), + _ => Vec::new(), + }; + args.iter().any(|arg| arg.walk().any(|arg| arg == param.into())) + }; + for &clause in &clauses { + if let Some(pred) = clause.as_trait_clause() + && pred.self_ty().skip_binder() == param + { + let tr = pred.def_id(); + if tcx.fn_trait_kind_from_def_id(tr).is_some() { + inputs = Some(pred.map_bound(|pred| pred.trait_ref.args.type_at(1))); + } else if !marker(tcx, tr) { + other.push(tcx.def_path_str(tr)); + } + } else if let Some(pred) = clause.as_projection_clause() + && pred.skip_binder().projection_term.self_ty() == param + && Some(pred.skip_binder().projection_term.expect_projection_def_id()) == output + { + ret = tcx.instantiate_bound_regions_with_erased(pred).term.as_type(); + } else if let Some(pred) = clause.as_type_outlives_clause() + && pred.skip_binder().0 == param + { + kept = true; + } else if mentions(clause) { + other.push(clause.to_string()); + } + } + let inputs = inputs?; + // The lifetimes the closure is generic over, which erasing loses. + let bound = inputs.skip_binder(); + let inputs = tcx.instantiate_bound_regions_with_erased(inputs); + let sig = tcx.fn_sig(def_id).instantiate(tcx, tcx.mk_args(base)).skip_norm_wip(); + // An `async fn`'s future, or a returned `impl Trait`, captures it. + kept |= sig.skip_binder().output().walk().any(|arg| arg == param.into()); + if kept { + return Some(Err(why("closure kept past the call", param.to_string()))); + } + // Each parameter makes its own closure, which one type parameter cannot name twice. + if sig + .skip_binder() + .inputs() + .iter() + .filter(|&&input| input == param) + .count() + > 1 + { + return Some(Err(why("closure type taken twice", param.to_string()))); + } + if !other.is_empty() { + return Some(Err(why("closure bound", other.join(" + ")))); + } + let (ty::Tuple(inputs), ty::Tuple(bound)) = (inputs.kind(), bound.kind()) else { + return Some(Err(why("closure signature", inputs.to_string()))); + }; + let mut params = Vec::new(); + for (input, bound) in inputs.iter().zip(bound.iter()) { + // A handle holds its object at `'static`, which one borrowing for the call isn't. + if let ty::Ref(_, inner, _) = bound.kind() + && inner.has_escaping_bound_vars() + { + return Some(Err(why("lent object that borrows", bound.to_string()))); + } + match self.ty(input, Pos::Param) { + // An object is lent as a handle for the call. + Ok(ty) + if foreign_arg(&ty) || matches!(&ty, Type::Ref(_, inner) if matches!(**inner, Type::Object(_))) => + { + params.push(ty) + } + Ok(_) => return Some(Err(why("closure signature", input.to_string()))), + Err(why) => return Some(Err(why)), + } + } + let ret = match ret.map(|ret| self.ty(ret, Pos::Return)) { + Some(Ok(ret)) if foreign_return(&ret) => ret, + Some(Err(why)) => return Some(Err(why)), + _ => return Some(Err(why("closure signature", param.to_string()))), + }; + Some(Ok(Type::Closure(params, Box::new(ret)))) + } + /// The callback a type parameter takes a foreign implementation of: one bounded by a /// single exported trait, and otherwise only by what that implementation meets. fn foreign(&self, def_id: DefId, param: Ty<'tcx>) -> Option { @@ -1815,13 +1926,9 @@ impl<'tcx> Collector<'tcx> { continue; } let tr = bound.def_id(); - let met = [sym::Send, sym::Sync] - .iter() - .any(|&item| tcx.is_diagnostic_item(item, tr)) - || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); match self.trait_decl(tr) { Some(Decl::Callback(i)) if callback.is_none() => callback = Some(*i), - _ if met => {} + _ if marker(tcx, tr) => {} _ => return None, } } @@ -2262,7 +2369,7 @@ impl<'tcx> Collector<'tcx> { ty::Slice(_) | ty::Str => return Err(why("unsized type", ty.to_string())), ty::Dynamic(..) => return Err(why("trait object", ty.to_string())), ty::Param(_) => match self.impls.borrow().iter().find(|(param, _)| *param == ty) { - Some((_, callback)) if pos == Pos::Param => Type::Callback(*callback, Dyn::Impl), + Some((_, taken)) if pos == Pos::Param => taken.clone(), _ => return Err(why("type parameter", ty.to_string())), }, ty::Closure(..) | ty::FnDef(..) | ty::FnPtr(..) => return Err(why("function value", "")), @@ -2418,6 +2525,15 @@ fn docs(tcx: TyCtxt<'_>, def_id: DefId) -> String { lines.join("\n").trim().to_string() } +/// Whether `tr` is `Send`, `Sync`, or `Sized`, which a foreign implementation or a lent +/// closure meets. +fn marker(tcx: TyCtxt<'_>, tr: DefId) -> bool { + [sym::Send, sym::Sync] + .iter() + .any(|&item| tcx.is_diagnostic_item(item, tr)) + || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)) +} + /// Whether `ty`, the type `def_id` at some arguments, implements the std trait `item`. fn implements<'tcx>(tcx: TyCtxt<'tcx>, ty: Ty<'tcx>, def_id: DefId, item: rustc_span::Symbol) -> bool { let Some(tr) = tcx.get_diagnostic_item(item) else { diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 2f95aaee2..4fe597ab4 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -148,6 +148,7 @@ impl Gen<'_> { Type::Duration => "::std::time::Duration".to_string(), Type::Option(inner) => format!("Option<{}>", self.rust(inner)), Type::Ref(Mutability::Not, inner) => format!("&{}", self.rust(inner)), + Type::Ref(Mutability::Mut, inner) => format!("&mut {}", self.rust(inner)), Type::Record(i) => generic(&api.records[*i].path, 0, &api.records[*i].args), Type::Enum(i) => generic(&api.enums[*i].path, 0, &api.enums[*i].args), Type::Object(i) => generic(&api.objects[*i].path, api.objects[*i].lifetimes, &api.objects[*i].args), @@ -174,6 +175,17 @@ impl Gen<'_> { Ty::Waker => "rt::Waker".to_string(), Ty::Out(inner) => format!("*mut {}", self.rs(inner)), Ty::In(inner) => format!("*const {}", self.rs(inner)), + Ty::Fn(params, ret) => { + let params: Vec = std::iter::once("*mut c_void".to_string()) + .chain(params.iter().map(|p| self.rs(p))) + .collect(); + format!( + "Option {}>", + params.join(", "), + self.rs(ret) + ) + } + Ty::Data => "*mut c_void".to_string(), } } @@ -214,12 +226,49 @@ impl Gen<'_> { false => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), }, Type::Callback(i, form) => abi::dyn_wrap(*form, &format!("Foreign_{}({e})", self.abi.callback(*i))), + Type::Closure(params, ret) => self.closure(params, ret, e), Type::Range(_) => format!("{e}.lift()"), Type::Bound(_) | Type::Bounds(_) => format!("{e}.lift(w)"), Type::Tuple(_) => unreachable!("a tuple is never taken"), } } + /// The Rust closure calling the function C lends as `e`, with its data `e_data`, which + /// lends each object the closure takes as a handle for that call. + fn closure(&self, params: &[Type], ret: &Type, e: &str) -> String { + let typed: Vec = (params.iter().enumerate()) + .map(|(n, ty)| format!("c{n}: {}", self.rust(ty))) + .collect(); + // Each object the closure takes, and how it is lent. + let lent = |ty: &Type| match ty { + Type::Ref(m, inner) => match (&**inner, m) { + (&Type::Object(i), Mutability::Mut) => Some((i, "lend_mut")), + (&Type::Object(i), Mutability::Not) if self.abi.api.objects[i].sync => Some((i, "lend")), + (&Type::Object(i), Mutability::Not) => Some((i, "lend_local")), + _ => None, + }, + _ => None, + }; + let args: Vec = std::iter::once("data.get()".to_string()) + .chain(params.iter().enumerate().map(|(n, ty)| match lent(ty) { + Some(_) => format!("h{n}"), + None => self.view(ty, &format!("c{n}")), + })) + .collect(); + let mut call = format!("unsafe {{ f({}) }}", args.join(", ")); + for (n, ty) in params.iter().enumerate().rev() { + if let Some((i, lend)) = lent(ty) { + call = format!("rt::Object::<{}>::{lend}(c{n}, w, |h{n}| {call})", self.object_path(i)); + } + } + format!( + "{{\n\t\tlet f = {e}.unwrap_or_else(|| rt::fail(w, \"a function is null\"));\n\t\tlet data = rt::Data::new({e}_data);\n\t\tmove |{}| -> {} {{\n\t\t\tlet result = {call};\n\t\t\t{}\n\t\t}}\n\t}}", + typed.join(", "), + self.rust(ret), + self.lift(ret, "result"), + ) + } + /// How a call borrows object `i` shared: across threads if it is `Sync`, else on one. fn shared(&self, i: usize) -> &'static str { match self.abi.api.objects[i].sync { @@ -263,7 +312,7 @@ impl Gen<'_> { Type::Record(i) => format!("lower_{}({e})", self.abi.record(*i)), Type::Enum(i) => format!("lower_{}({e})", self.abi.enumeration(*i)), Type::Object(_) => format!("rt::Object::new({e})"), - Type::Callback(..) => unreachable!("a callback is never returned"), + Type::Callback(..) | Type::Closure(..) => unreachable!("a callback is never returned"), Type::Waker => unreachable!("a waker is never returned"), Type::Range(_) => format!("rt::Range::lower({e})"), Type::Bound(_) => format!("rt::Bound::lower({e})"), @@ -888,8 +937,13 @@ impl Gen<'_> { } } } - for (n, (param, (_, c_ty))) in function.params.iter().zip(c_params).enumerate() { + for (n, param) in function.params.iter().enumerate() { + let (_, c_ty) = c_params.next().expect("a C parameter for each"); params.push(format!("p{n}: {}", self.rs(c_ty))); + if let Type::Closure(..) = param.ty { + let (_, data) = c_params.next().expect("a lent function's data"); + params.push(format!("p{n}_data: {}", self.rs(data))); + } let (stmt, arg) = self.arg(¶m.ty, &format!("p{n}"), &format!("a{n}"), future); stmts.push(stmt); args.push(arg); diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index 559f4010a..bddc63c72 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -251,6 +251,9 @@ pub enum Type { Object(usize), /// A foreign implementation of a callback trait, in the form the parameter takes. Callback(usize, Dyn), + /// A closure the callee calls only during the call, as a foreign function: what it + /// takes, then what it returns. + Closure(Vec, Box), /// `std::ops::Range` of an integer. Range(Int), /// `std::ops::Bound` of an integer. diff --git a/ffi/tests/api.c b/ffi/tests/api.c index 2fd889327..be2cdd1e6 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -43,6 +43,48 @@ static void log_free(void *data) { printf("freed\n"); } +/* A lent closure: adds data's amount to the counter lent for the call. */ +static bool edit(void *data, api_counter *counter) { + api_counter_add(counter, *(const uint64_t *)data, NULL, NULL); + return api_counter_edited(counter) && api_counter_get(counter) == 6; +} + +/* Lent closures borrowing their object shared: one `Sync`, one not. */ +static uint32_t seven(void *data) { + (void)data; + return 7; +} + +static uint64_t visit(void *data, const api_cursor *cursor) { + (void)data; + return api_cursor_at(cursor) * 2; +} + +static uint32_t peek_tally(void *data, const api_tally *tally) { + (void)data; + return api_tally_bump(tally); +} + +/* A lent closure, which Rust calls on another thread: keeps levels above data's. */ +static bool keep_line(void *data, uint8_t level, api_buf line) { + printf("filter %u %.*s\n", level, (int)line.len, (const char *)line.ptr); + return level > *(const uint8_t *)data; +} + +/* Breaks a lent handle's contract: frees it, or moves its value out. */ +static bool free_lent(void *data, api_counter *counter) { + (void)data; + api_counter_free(counter); + return false; +} + +static bool move_lent(void *data, api_counter *counter) { + (void)data; + api_label label = api_counter_into_label(counter, (api_option_point){0}); + api_label_free(&label); + return false; +} + /* A bound, as Rust's Debug prints it. */ static void print_bound(api_bound_u64 bound) { switch (bound.kind) { @@ -149,6 +191,13 @@ static int script(void) { (unsigned long long)api_counter_get(last)); api_counter_free(lent); api_counter_free(last); + uint64_t by = 5; + bool edited = api_registry_edit(registry, edit, &by); + first = api_registry_first(registry); + printf("edit %s %llu\n", edited ? "true" : "false", (unsigned long long)api_counter_get(first)); + api_counter_free(first); + printf("walk %llu\n", (unsigned long long)api_walk(3, visit, NULL)); + printf("offset %u\n", api_offset(seven, NULL, 3)); api_registry_free(registry); /* A type generic only over lifetimes is a handle to its 'static form. */ @@ -235,6 +284,8 @@ static int script(void) { printf("write %s\n", api_logger_write(logger, str("hi")) ? "true" : "false"); api_logger_free(logger); printf("dropped\n"); + uint8_t threshold = 2; + printf("filtered %u\n", api_filter(lines, keep_line, &threshold)); api_channel *channel = api_channel_new(); api_waker waker = {.wake = wake, .drop = drop, .data = NULL}; @@ -295,6 +346,7 @@ static int script(void) { uint32_t count = api_tally_bump(tally); printf("tally %u %s\n", count, api_tally_eq(tally, tally) ? "true" : "false"); printf("both %u\n", api_bump_both(tally, tally)); + printf("peek %u\n", api_peek(tally, peek_tally, NULL)); api_tally_free(tally); /* Another export's types, which this export's function takes and returns. */ @@ -390,6 +442,12 @@ static int broken(const char *which) { api_channel_recv_poll(recv, waker, &payload); } else if (strcmp(which, "enum") == 0) { api_greet(str("x"), (api_shape)2); + } else if (strcmp(which, "lent") == 0 || strcmp(which, "lent moved") == 0) { + api_registry *registry = api_registry_new(api_counter_new(str("c"), 0)); + api_registry_edit(registry, strcmp(which, "lent") == 0 ? free_lent : move_lent, NULL); + } else if (strcmp(which, "null") == 0) { + api_registry *registry = api_registry_new(api_counter_new(str("c"), 0)); + api_registry_edit(registry, NULL, NULL); } else if (strcmp(which, "bound") == 0) { api_count((api_bounds_u64){.start = {.kind = (api_bound)3}}); } diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 7d8ee85fc..6da207ce0 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -106,6 +106,12 @@ fn api() { ), ("enum", "api_greet: an enum value is invalid"), ("bound", "api_count: a bound's kind is invalid"), + ("lent", "api_registry_edit: a lent handle was freed"), + ( + "lent moved", + "api_counter_into_label: a lent handle's value cannot move out", + ), + ("null", "api_registry_edit: a function is null"), ] { let output = Command::new(&exe).arg(case).output().unwrap(); assert!(!output.status.success(), "{case} did not abort"); diff --git a/quest/m1/ffi-export/README.md b/quest/m1/ffi-export/README.md index 721d58776..649e0ca2c 100644 --- a/quest/m1/ffi-export/README.md +++ b/quest/m1/ffi-export/README.md @@ -49,7 +49,6 @@ Every generator on the C ABI: - [Paths without a lifetime](/quest/m1/ffi-export/paths.md) - moq's owned `Path` exports, and its excludes go - [Instances the config can't name yet](/quest/m1/ffi-export/instance-keys.md) - `&T` keys, `IntoIterator` as a `Vec`, `serde_json::Value`, and `Catalog<()>` -- [Closures lent for the call](/quest/m1/ffi-export/lent-closures.md) - a callback borrowed for one call, as `modify`'s `Guard` needs - [moq-clock's C names once it moves into kio](/quest/m1/ffi-export/crates.md) - `moq_now` and `moq_origin` become the clock's, after moq moves it into `kio::clock` - [Sessions on moq-tokio](/quest/m1/ffi-export/session-tokio.md) - bindings connect and accept with one call, the library running moq-tokio inside - [Sessions on sans-IO QUIC](/quest/m1/ffi-export/session-quic.md) - bindings move UDP datagrams and drive the session's poll themselves diff --git a/quest/m1/ffi-export/lent-closures.md b/quest/m1/ffi-export/lent-closures.md deleted file mode 100644 index 1dd945fab..000000000 --- a/quest/m1/ffi-export/lent-closures.md +++ /dev/null @@ -1,19 +0,0 @@ -# [M] Closures lent for the call - -## Goal - -The exporter exports a function that takes a closure it calls only during the call, as a -C callback with a context pointer, so moq's `catalog::Producer` can be changed through a -lent closure (`mutate`) where `modify` returns a borrowing `Guard` the C ABI can't hold. - -## Plan - -Left out of [#126](https://github.com/kixelated/rust2/pull/126); decided with the -maintainer on 2026-10-27 to plan it. - -- A closure the callee keeps past the call stays refused; only a lent one exports. -- A panic or an error in the callback must not unwind across the C ABI. -- Decide whether `mutate` is moq's API or the exporter's rewrite of `modify`; moq's own - change belongs in moq's tree. - -Public API: the exporter's C ABI for callbacks.