diff --git a/ffi/README.md b/ffi/README.md index 6bc8d6871..2b01eed39 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -104,6 +104,7 @@ public path names, or an error taken by value, is held by value as an opaque han | a type parameter or `impl` taken by value and bounded by `Future` or `IntoFuture`, whose every bound `Pin + Send>>` meets, as kio's `clock::timeout` takes, or taken as `Pin<&mut F>` by a poll, as kio's `Waiter::poll_future` takes | `_foreign_future`: a future of `()` C implements, which Rust takes as that type, or which the future the poll makes owns and pins; a future of another output is refused | | a type parameter or `impl` bounded by `Read` and `Seek` alone, behind `&mut`, which no lifetime bound or return lets outlive the call, as moq-mux's `container::mp4::repair` takes | `_foreign_reader`: a `read` and a `seek` C implements and their data, lent for the call; any other reader is refused | | `fn` and inherent `pub` methods | functions named through their type | +| an object's `Deref` to an exported type, followed as far as the chain reaches | the target's `pub` methods and fields, a record's too, on the object, as auto-deref finds them: a method the object or a nearer target has, exported or not, hides a method, and a field a field; a `&mut self` method or a setter only while every `Deref` on the way is a `DerefMut`; and the config names each by the object's path | | a `()` parameter of a function, not of a callback's method | nothing: C passes no argument for it | | `Result` | `bool f(..., T *out, E *err)`; an `E` of another crate that implements `Display`, such as `anyhow::Error` or `io::Error`, is `String`, its message | | a returned tuple `(A, B)` | one out pointer each: `void f(..., A *out0, B *out1)` | @@ -170,7 +171,15 @@ alone, or an object's `pub` field holds, bare or as an `Option`'s `Some`: that o on each use, on one thread at a time where the receiver is not `Sync`. A handle outlives every call, so every lifetime an object takes is `'static`, as is every lifetime that must outlive one; any other lifetime is the call's. A signature may not lend C's borrow for one that is `'static`, but for a -`&str` or `&[u8]`, which Rust interns, nor return an object that borrows. A parameter is a reference +`&str` or `&[u8]`, which Rust interns, nor return an object that borrows, but for an +exclusive lend: a `&mut self` method of an object returning an object, bare or as a +`Result`'s `Ok`, that borrows the receiver's lifetime alone and is not `Copy`, as a lock's +guard does, which its handle holds with the receiver's exclusive borrow; a copy would +carry the borrow past it. Each of its `Clone`, `PartialEq`, `Hash`, `Debug`, `Display`, +`Deref`, and `DerefMut` must hold at every lifetime, as the binding calls them on the +`'static` form, and its `Deref` target must name no lifetime. So must each of the +method's own bounds naming the receiver's lifetime, as the binding's lend gives the call a +borrow of any lifetime. A parameter is a reference only at its top or as `Some` of an `Option`, lent as the reference alone is, so `Option<&T>` is a null or borrowed handle, a null or viewed buffer, or an option of a value, and not inside a `Box` or any other type. A `&mut` of a value, but a `str` or a @@ -341,6 +350,17 @@ where it was while its file is unchanged. shared and fails with `_STATUS_OUTLIVED` once it was since borrowed exclusively, moved out, or freed, which Rust's borrow checker would refuse. Borrowing a lent handle exclusively, or moving it out, fails with `_STATUS_LENT`, as Rust lent it. +- **Exclusive lends**, a `&mut self` method's returned object that borrows its receiver, + such as a guard, are owned handles that hold the receiver borrowed exclusively until the + value drops: by `_drop`, by `_free` of the last handle, or by a call it moves into, as + `commit(self)` does, which gives the borrow back once the call returns. Until then the + receiver fails each call with `_STATUS_EXCLUSIVE` or `_STATUS_BORROWED`, + and its `_free` leaves the value to the lend. A clone shares the borrow, which the last + copy gives back. A call that could keep the value past it or carry its borrow out fails + with `_STATUS_LENT`, as does a move into anything but a plain call: one taking an + object whose lifetime is `'static`, or ties it to another argument or the return, itself + or through the signature's bounds, and a field's getter or setter where the field holds + what borrows. - **Interned strings**: a `&str` or `&[u8]` a function needs for `'static`, as `Path::from_static` and `CertificateDer::from_slice` do, is leaked once per distinct content and reused for every later equal one, so a caller passing ever-new strings grows the set without bound. diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index fdb301600..f273b57c1 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -736,6 +736,44 @@ fn main() { let tallies = api::Tallies::new(); tallies.first().bump(); println!("tallied {}", tallies.first().bump()); + // A draft borrowing its ledger exclusively, through which its sheet's members are + // reached by `Deref` and `DerefMut`. + let mut ledger = api::Ledger::new(); + let mut draft = ledger.edit().unwrap(); + draft.title = "minutes".to_string(); + draft.write("first"); + println!( + "draft {} {} {} {}", + draft.title, + draft.lines(), + draft.describe(), + draft.edited() + ); + println!("committed {}", draft.commit()); + println!("ledger {} {}", ledger.title(), ledger.published()); + let draft = ledger.edit().unwrap(); + println!("read {} {}", draft.lines(), draft.edited()); + drop(draft); + let mut draft = ledger.edit().unwrap(); + draft.write("second"); + drop(draft); + println!("dropped {}", ledger.published()); + println!("receipt {}", ledger.receipt().count()); + // Members a `Deref` reaches: past an unexported target, beside a method of the same + // name, and a field a method's path shares. + let mut marker = api::Marker::new("m", 3, 5); + marker.y = 7; + println!( + "forwarded {} {} {} {} [{}] [{}]", + api::Pad::::wide().title(), + api::Layered::new().lines(), + marker.x, + marker.y, + api::Pad::::small().describe(), + api::Pad::::wide().describe() + ); + ledger.seal(); + println!("sealed {}", ledger.edit().err().unwrap()); println!("chunks {:?}", api::chunks(b"abcde", 2)); let mut counters = api::counters(vec!["x".to_string(), "y".to_string()]); let names: Vec = counters.iter().map(|c| format!("{} {}", c.name(), c.get())).collect(); diff --git a/ffi/fixtures/api/ffi.toml b/ffi/fixtures/api/ffi.toml index c446752df..27026dcd6 100644 --- a/ffi/fixtures/api/ffi.toml +++ b/ffi/fixtures/api/ffi.toml @@ -5,13 +5,19 @@ # `field@` leaves out a field alone where a method takes its path, as `Retry`'s and # `Slot`'s do, and `Retry::jitter` and `field@Retry::jitter` leave out a refused method # and its field. `Slot` has no such method, so its path alone names its field. A -# function instance is left out by its path, as `depth_past` at `polar::Point` is. Swift +# function instance is left out by its path, as `depth_past` at `polar::Point` is, and a +# method a `Deref` forwards by the object's, as `Pad::lines` is. A forwarded field +# sharing its path with a method is `field@`, as `Pad`'s `title` is, so `Marker::x` +# leaves out its method alone, as `Marker::y` does its function without `self`. Swift # refuses `among`, so the census takes its exclude. exclude = [ "among", "Copied", "Layer", "Node::next", + "Marker::x", + "Marker::y", + "Pad::lines", "Pair::swap", "Queued", "Rooted", @@ -19,6 +25,7 @@ exclude = [ "Scoped", "Slot::value", "Retry::jitter", + "field@Pad::title", "field@Retry::delay", "field@Retry::jitter", "field@Slot::value", diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index bcfa58631..5976027ed 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -741,6 +741,409 @@ impl Registry { /// The address of the counter [`Registry::edit`] lends. static EDITING: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0); +/// A sheet a [`Draft`] edits in place: [`Ledger::edit`] lends the ledger exclusively until +/// the draft drops, as moq-mux's `catalog::Producer::modify` lends its catalog. +#[derive(Default)] +pub struct Ledger { + sheet: Mutex, + published: u32, + sealed: bool, +} + +impl Ledger { + pub fn new() -> Self { + Self::default() + } + + /// A draft of the sheet, which borrows this ledger exclusively until it drops: fails + /// once sealed. + pub fn edit(&mut self) -> Result, Error> { + if self.sealed { + return Err(Error::Overflow); + } + Ok(Draft { + sheet: self.sheet.lock().expect("a draft never panics holding the lock"), + published: &mut self.published, + edited: false, + }) + } + + /// How many drafts published an edit. + pub fn published(&self) -> u32 { + self.published + } + + /// The sheet's title, read through its lock. + pub fn title(&self) -> String { + self.sheet + .lock() + .expect("a draft never panics holding the lock") + .title + .clone() + } + + /// Refuses every later draft. + pub fn seal(&mut self) { + self.sealed = true; + } + + /// What this ledger published, which borrows it exclusively while any copy of the + /// receipt lives, as a `&mut self` method's borrowing return does in Rust. + pub fn receipt(&mut self) -> Receipt<'_> { + Receipt(&self.published) + } + + /// A receipt from a method bounded on its own borrow, by a trait that holds at every + /// lifetime, so the lend still exports. + pub fn noted<'a>(&'a mut self) -> Receipt<'a> + where + &'a mut Self: noted::Noted<'a>, + { + Receipt(&self.published) + } + + /// Files `item` beside what the ledger published, generic over what counts itself. + pub fn file(&mut self, item: T) -> Filed<'_, T> { + Filed { + published: &self.published, + item, + } + } + + pub fn slip(&mut self) -> Slip<'_> { + Slip { + receipt: Receipt(&self.published), + global: Receipt(&7), + here: std::marker::PhantomData, + } + } +} + +mod noted { + /// Implemented for a borrow of a ledger of any lifetime. + pub trait Noted<'a> {} + + impl<'a> Noted<'a> for &'a mut super::Ledger {} +} + +/// A receipt kept on the thread that took it: `Clone` and not `Send`, with a field that +/// borrows what the slip borrows, so reading it would carry the ledger's borrow out, and +/// one that borrows only what lives as long as the program. +#[derive(Clone)] +pub struct Slip<'a> { + pub receipt: Receipt<'a>, + pub global: Receipt<'static>, + here: std::marker::PhantomData>, +} + +impl Slip<'_> { + pub fn count(&self) -> u32 { + self.receipt.count() + } +} + +/// What a [`Ledger`] published, borrowed from it: `Send` and `Clone`, unlike a [`Draft`]. +pub struct Receipt<'a>(&'a u32); + +/// Bounded by what always holds, so proving `Receipt<'a>: Clone` asks nothing of `'a`. +impl<'a> Clone for Receipt<'a> +where + Receipt<'a>: 'a, +{ + fn clone(&self) -> Self { + Self(self.0) + } +} + +impl Receipt<'_> { + pub fn count(&self) -> u32 { + *self.0 + } +} + +/// What a [`Draft`] derefs to: a title, and the lines written under it. +#[derive(Clone, Debug, Default)] +pub struct Sheet { + pub title: String, + lines: Vec, +} + +impl Sheet { + pub fn new() -> Self { + Self::default() + } + + /// How many lines it holds. + pub fn lines(&self) -> u32 { + self.lines.len() as u32 + } + + /// Adds a line. + pub fn write(&mut self, line: &str) { + self.lines.push(line.to_string()); + } + + /// The sheet in a word, which a draft's own `describe` shadows, as in Rust. + pub fn describe(&self) -> String { + format!("sheet {}", self.title) + } +} + +/// An edit of a [`Ledger`]'s sheet, reached through `Deref` and `DerefMut`, and published +/// once it commits or drops if a `DerefMut` marked it, as moq-mux's `catalog::Guard` does. +/// Not `Send`, as the lock it holds is not. +pub struct Draft<'a> { + sheet: std::sync::MutexGuard<'a, Sheet>, + published: &'a mut u32, + edited: bool, +} + +impl Draft<'_> { + /// Whether a `DerefMut` marked it, which a read through `Deref` does not. + pub fn edited(&self) -> bool { + self.edited + } + + /// The draft in a word, shadowing its sheet's. + pub fn describe(&self) -> String { + format!("draft of {} lines", self.sheet.lines()) + } + + /// Publishes the edit, if any, returning how many the ledger published: the drop then + /// publishes nothing. + pub fn commit(mut self) -> u32 { + self.publish(); + *self.published + } + + fn publish(&mut self) { + if std::mem::take(&mut self.edited) { + *self.published += 1; + } + } +} + +impl std::ops::Deref for Draft<'_> { + type Target = Sheet; + + fn deref(&self) -> &Sheet { + &self.sheet + } +} + +impl std::ops::DerefMut for Draft<'_> { + fn deref_mut(&mut self) -> &mut Sheet { + self.edited = true; + &mut self.sheet + } +} + +impl Drop for Draft<'_> { + fn drop(&mut self) { + self.publish(); + } +} + +/// Whether `draft` is marked: it must live as long as the program, which a draft +/// [`Ledger::edit`] lends never does, so passing one fails, as Rust refuses it. +pub fn lasting(draft: &Draft<'static>) -> bool { + draft.edited +} + +/// What `receipt` counts: its bound lets it live as long as the program, so passing one a +/// [`Ledger`] lends fails, as Rust refuses it. +pub fn stored<'a: 'static>(receipt: Receipt<'a>) -> u32 { + receipt.count() +} + +/// What `receipt` counts, through a bound that holds for any lifetime, so a [`Ledger`]'s +/// lent receipt moves in, and the ledger is free once it returns. +pub fn tallied<'a>(receipt: Receipt<'a>) -> u32 +where + Receipt<'a>: Clone, +{ + receipt.clone().count() +} + +/// An item filed with a ledger, whose `Clone` asks that it outlive its borrow, as it always +/// does: an instance's erased lifetime stands beside the lend's. +pub struct Filed<'a, T> { + published: &'a u32, + item: T, +} + +impl<'a, T: Clone> Clone for Filed<'a, T> +where + Filed<'a, T>: 'a, +{ + fn clone(&self) -> Self { + Self { + published: self.published, + item: self.item.clone(), + } + } +} + +impl Filed<'_, T> { + pub fn count(&self) -> u32 { + *self.published + self.item.clone().total() + } +} + +/// What counts itself, implemented only for a receipt that lives as long as the program. +pub trait Totaled { + fn total(self) -> u32; +} + +impl Totaled for Receipt<'static> { + fn total(self) -> u32 { + self.count() + } +} + +/// What `totaled` counts: the instance a binding calls takes a receipt that lives as long +/// as the program, so passing one a [`Ledger`] lends fails. +pub fn summed_up(totaled: T) -> u32 { + totaled.total() +} + +/// What `receipt` counts: its bound implies it lives as long as the program, as `Any`'s +/// does, so passing one a [`Ledger`] lends fails too. +pub fn erased<'a>(receipt: Receipt<'a>) -> u32 +where + Receipt<'a>: std::any::Any, +{ + receipt.count() +} + +/// A sheet with a tag, which derefs to the sheet: only `Pad` has a `describe` of its +/// own, which hides the sheet's, while `Pad`'s is the sheet's, as in Rust. +pub struct Pad { + sheet: Sheet, + tag: T, +} + +impl std::ops::Deref for Pad { + type Target = Sheet; + + fn deref(&self) -> &Sheet { + &self.sheet + } +} + +impl Pad { + pub fn small() -> Self { + Self { + sheet: Sheet::new(), + tag: 1, + } + } + + pub fn describe(&self) -> String { + format!("pad {}", self.tag) + } +} + +impl Pad { + pub fn wide() -> Self { + Self { + sheet: Sheet::new(), + tag: 2, + } + } + + pub fn tag(&self) -> u16 { + self.tag + } + + /// A method named as the sheet's field, which hides no field: `title` still reaches the + /// sheet's, as Rust's field access does. + pub fn title(&self) -> u16 { + self.tag + } +} + +mod layers { + /// Between a layered sheet and its sheet: no path from the crate root names it, so it + /// does not export, yet its `describe` hides the sheet's, as in Rust. + pub struct Middle(pub(crate) super::Sheet); + + impl Middle { + pub fn describe(&self) -> String { + "middle".to_string() + } + } + + impl std::ops::Deref for Middle { + type Target = super::Sheet; + + fn deref(&self) -> &super::Sheet { + &self.0 + } + } +} + +/// A sheet behind a layer, which forwards what the layer does not hide. +pub struct Layered(layers::Middle); + +impl Layered { + pub fn new() -> Self { + Self(layers::Middle(Sheet::new())) + } +} + +impl std::ops::Deref for Layered { + type Target = layers::Middle; + + fn deref(&self) -> &layers::Middle { + &self.0 + } +} + +/// A named point, which derefs mutably to a record, whose fields it reaches. +pub struct Marker { + point: Point, + label: String, +} + +impl Marker { + pub fn new(label: &str, x: i32, y: i32) -> Self { + Self { + point: Point { x, y }, + label: label.to_string(), + } + } + + pub fn label(&self) -> String { + self.label.clone() + } + + /// A method sharing its path with the point's field, which the config leaves out alone. + pub fn x(&self) -> i32 { + self.point.x + } + + /// A function without `self` sharing its path with the point's field, which the config + /// leaves out alone too. + pub fn y() -> i32 { + 0 + } +} + +impl std::ops::Deref for Marker { + type Target = Point; + + fn deref(&self) -> &Point { + &self.point + } +} + +impl std::ops::DerefMut for Marker { + fn deref_mut(&mut self) -> &mut Point { + &mut self.point + } +} + /// 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)] diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 3b0db43b9..81a490da3 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -58,13 +58,18 @@ fixtures/reject/src/lib.rs:1336:1: rust2-ffi: cannot export fn `keep_object`: 's fixtures/reject/src/lib.rs:1341:1: rust2-ffi: cannot export fn `bound_object`: 'static borrow `&mut jni::Env<'a>`; 'static borrow `jni::objects::JObject<'a>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:1341:21: note: `'a` is `'static`, as a handle outlives every call fixtures/reject/src/lib.rs:1341:21: note: `'a` is `'static`, as a handle outlives every call +fixtures/reject/src/lib.rs:1365:2: rust2-ffi: cannot export method `Slot::view`: returned object that borrows `SlotView<'_, u8>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:1371:2: rust2-ffi: cannot export method `Slot::peek`: returned object that borrows `SlotView<'_, u8>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:1423:2: rust2-ffi: cannot export method `Slot::hold`: returned object that borrows `SlotHold<'a>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:1431:2: rust2-ffi: cannot export method `Slot::tag`: returned object that borrows `SlotTag<'_>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:1436:2: rust2-ffi: cannot export method `Slot::lens`: returned object that borrows `SlotLens<'_>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:1441:2: rust2-ffi: cannot export method `Slot::peer`: returned object that borrows `SlotPeer<'_>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:145:2: rust2-ffi: cannot export method `Link::session`: borrowed return that is not Clone `tls::held::Handoff`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:162:1: rust2-ffi: cannot export fn `measure`: foreign type `tls::held::Local`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:167:1: rust2-ffi: cannot export instance `Cell>`: type argument `std::vec::Vec`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:167:1: rust2-ffi: cannot export instance `Cell`: type argument `tls::held::Cert`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:16: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:170:1: rust2-ffi: cannot export fn `sealed`: refused type `reject::Cell`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:187:2: rust2-ffi: cannot export method `Slot::lock`: returned object that borrows `SlotGuard<'_, u8>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:199:1: rust2-ffi: cannot export fn `echo`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:204:1: rust2-ffi: cannot export fn `blame`: borrowing output of a future from a function that is not async `std::result::Result>`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:209:1: rust2-ffi: cannot export fn `relay`: borrowing output of a future from a function that is not async `&str`; exclude it in the config to leave it out diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs index d9f75ba6c..49841affc 100644 --- a/ffi/fixtures/reject/src/lib.rs +++ b/ffi/fixtures/reject/src/lib.rs @@ -183,7 +183,7 @@ impl Slot { Self(0) } - /// A guard that borrows its handle, which a new handle would outlive. + /// A guard that borrows its handle exclusively, which its own handle holds: exported. pub fn lock(&mut self) -> SlotGuard<'_, u8> { SlotGuard(&mut self.0) } @@ -1341,3 +1341,134 @@ pub fn keep_object(env: &mut jni::Env, object: jni::objects::JObject<'static>) - pub fn bound_object<'a: 'static>(env: &mut jni::Env<'a>, object: jni::objects::JObject<'a>) -> bool { env.get_raw().is_null() && object.is_null() } + +/// A view sharing its slot's borrow, which a copy carries. +#[derive(Clone, Copy)] +pub struct SlotView<'a, T>(&'a T); + +impl SlotView<'static, u8> { + /// A view of a constant, which keeps the view reachable without its slot. + pub fn fixed() -> Self { + Self(&7) + } +} + +impl SlotView<'_, T> { + pub fn get(&self) -> T { + *self.0 + } +} + +impl Slot { + /// A view that borrows its handle shared, which a new handle would outlive: only a + /// `&mut self` method's borrowing object holds its receiver's borrow. + pub fn view(&self) -> SlotView<'_, u8> { + SlotView(&self.0) + } + + /// A view that borrows its handle exclusively, but whose copies would carry the borrow + /// past the one handle that holds it. + pub fn peek(&mut self) -> SlotView<'_, u8> { + SlotView(&self.0) + } +} + +/// A tag whose `Clone` is implemented for `'static` alone, which a clone through a handle +/// would call on a value whose borrow is shorter. +pub struct SlotTag<'a>(&'a mut u8); + +impl Clone for SlotTag<'static> { + fn clone(&self) -> Self { + SlotTag(Box::leak(Box::new(*self.0))) + } +} + +/// A lens whose `Deref` is implemented for `'static` alone. +pub struct SlotLens<'a>(&'a mut u8); + +impl std::ops::Deref for SlotLens<'static> { + type Target = u8; + + fn deref(&self) -> &u8 { + self.0 + } +} + +/// A peer that derefs to a view of the same borrow, whose own traits the export does not +/// prove at the lend's lifetime. +pub struct SlotPeer<'a>(SlotView<'a, u8>, &'a mut u8); + +impl<'a> std::ops::Deref for SlotPeer<'a> { + type Target = SlotView<'a, u8>; + + fn deref(&self) -> &SlotView<'a, u8> { + &self.0 + } +} + +/// A hold with no trait at all, which the lend's own bound keeps refused. +pub struct SlotHold<'a>(&'a mut u8); + +mod pin { + /// Implemented for a `'static` borrow of a slot alone, which a callee bounded by it + /// could keep. + pub trait StaticOnly<'a> {} + + impl StaticOnly<'static> for &'static mut super::Slot {} +} + +impl Slot { + /// Refused: its bound holds only for a `'static` borrow of the slot, which the lend's + /// borrow is not. + pub fn hold<'a>(&'a mut self) -> SlotHold<'a> + where + &'a mut Self: pin::StaticOnly<'a>, + { + SlotHold(&mut self.0) + } + + /// Refused: its tag's `Clone` holds only for `'static`. + pub fn tag(&mut self) -> SlotTag<'_> { + SlotTag(&mut self.0) + } + + /// Refused: its lens's `Deref` holds only for `'static`. + pub fn lens(&mut self) -> SlotLens<'_> { + SlotLens(&mut self.0) + } + + /// Refused: its peer's `Deref` target names the lend's lifetime. + pub fn peer(&mut self) -> SlotPeer<'_> { + let Slot(value) = self; + let view: &u8 = Box::leak(Box::new(*value)); + SlotPeer(SlotView(view), value) + } +} + +impl SlotTag<'static> { + /// A tag of its own, which keeps the type reachable without a slot. + pub fn fixed() -> Self { + SlotTag(Box::leak(Box::new(0))) + } +} + +impl SlotHold<'static> { + /// A hold of its own, which keeps the type reachable without a slot. + pub fn fixed() -> Self { + SlotHold(Box::leak(Box::new(0))) + } +} + +impl SlotLens<'static> { + /// A lens of its own, which keeps the type reachable without a slot. + pub fn fixed() -> Self { + SlotLens(Box::leak(Box::new(0))) + } +} + +impl SlotPeer<'static> { + /// A peer of its own, which keeps the type reachable without a slot. + pub fn fixed() -> Self { + SlotPeer(SlotView(&0), Box::leak(Box::new(0))) + } +} diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index 3206e638b..a432af51a 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -47,6 +47,7 @@ exclude = [ "rustls::ConfigBuilder", "rustls::ConfigBuilder", "rustls::client::Resumption::store", + "rustls::client::danger::DangerousClientConfig::cfg", "tokio::server::Request::within", "tokio::tls::Serve::resolver", ] diff --git a/ffi/moq/moq.c b/ffi/moq/moq.c index e579448e2..f8c906407 100644 --- a/ffi/moq/moq.c +++ b/ffi/moq/moq.c @@ -413,6 +413,30 @@ int main(void) { int listed_stats = 0; CHECK(moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, NULL)); CHECK(listed_stats == 1); + /* The same field through `modify`'s guard, a handle holding the catalog borrowed + * exclusively until the guard commits or drops: a call on the catalog meanwhile fails + * before any Rust code runs. A commit publishes the cleared field, and a drop the + * restored one. */ + moq_mux_catalog_Guard_Extra *guard = NULL; + CHECK(moq_mux_catalog_Producer_Extra_modify(catalog, &guard, &mux_err, NULL)); + moq_hang_catalog_Stats *guarded = moq_mux_catalog_Guard_Extra_stats_get(guard, NULL); + moq_hang_catalog_Stats *want = moq_hang_catalog_Stats_new(str("stats")); + CHECK(guarded != NULL && moq_hang_catalog_Stats_eq(guarded, want, NULL)); + moq_hang_catalog_Stats_free(guarded); + moq_status held = 0; + moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, &held); + CHECK(held == MOQ_STATUS_BORROWED); + moq_mux_catalog_Guard_Extra_stats_set(guard, NULL, NULL); + CHECK(moq_mux_catalog_Guard_Extra_commit(guard, &mux_err, NULL)); + moq_mux_catalog_Guard_Extra_free(guard); + CHECK(moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, NULL)); + CHECK(listed_stats == 1); + CHECK(moq_mux_catalog_Producer_Extra_modify(catalog, &guard, &mux_err, NULL)); + moq_mux_catalog_Guard_Extra_stats_set(guard, want, NULL); + moq_hang_catalog_Stats_free(want); + moq_mux_catalog_Guard_Extra_free(guard); + CHECK(moq_mux_catalog_Producer_Extra_mutate(catalog, lists_stats, &listed_stats, &mux_err, NULL)); + CHECK(listed_stats == 2); /* A JSON track the catalog lists, published through moq-mux's generic `json_snapshot` * at a JSON document, and a section C parses from text, set in the lent catalog and * read back as text. Its track has a timescale, since every write is stamped. */ diff --git a/ffi/moq/moq.py b/ffi/moq/moq.py index 5d2efe18d..ecb89ae3a 100644 --- a/ffi/moq/moq.py +++ b/ffi/moq/moq.py @@ -199,6 +199,19 @@ def count(lent): producer.mutate(count) expect(read == 1, "mutate lends the catalog once") + # The same catalog through `modify`'s guard, a handle holding the producer borrowed + # exclusively until it commits: a call on the producer meanwhile raises before any Rust + # code runs. + guard = producer.modify() + expect(guard.to_json().startswith("{"), "a guard reads the catalog it derefs to") + try: + producer.mutate(count) + expect(False, "a call on a producer its guard borrows raises") + except RuntimeError: + pass + guard.commit() + producer.mutate(count) + expect(read == 2, "a committed guard gives its producer back") # A JSON track the catalog lists, published through moq-mux's generic `json_snapshot` at # a JSON document, and a section Python parses from text, set in the lent catalog and diff --git a/ffi/runtime/rt.rs b/ffi/runtime/rt.rs index ff32a1560..9b4d66f1e 100644 --- a/ffi/runtime/rt.rs +++ b/ffi/runtime/rt.rs @@ -1024,6 +1024,36 @@ pub struct Object { /// For a value that is not `Send`, the thread it stays on, which alone borrows, moves, /// or drops it. owner: Option>, + /// For a value a call returned borrowing another handle's value exclusively, that borrow, + /// given back only once the value dropped, wherever it drops. Touched only by what + /// holds the value as [`TAKEN`], or by the last reference's drop. + loan: UnsafeCell>, + /// Whether `loan` started out holding a borrow, so moving the value out fails but into a + /// call that ends the value with the borrow: never changes. + held: bool, +} + +/// An exclusive borrow of another handle's value, which a value Rust returned borrowing it +/// holds: given back once the last value sharing it drops, as clones of a borrowing value +/// share their borrow in Rust. +#[derive(Clone)] +pub struct Loan(#[expect(dead_code, reason = "held for its drop")] Arc); + +impl ExclusiveArc { + /// The value, borrowed for as long as the loan it becomes lives. + /// + /// # Safety + /// What the returned reference lends outlives neither this nor the [`Loan`] it becomes. + pub unsafe fn lend<'a>(&mut self) -> &'a mut T { + self.changed = true; + // SAFETY: the exclusive borrow is held, for as long as the caller's contract says. + unsafe { &mut *self.object.value() } + } + + /// This borrow, held by the value a call returned borrowing it. + pub fn loan(self) -> Loan { + Loan(Arc::new(self)) + } } /// A value that is not `Send`, held by a handle that keeps it on the thread that made it: @@ -1187,6 +1217,37 @@ impl Object { epoch: AtomicUsize::new(0), lender: None, owner, + loan: UnsafeCell::new(None), + held: false, + })) + .cast() + } + + /// A new handle owning `value`, which holds `loan`, the exclusive borrow of another + /// handle's value it was returned borrowing: given back once `value` drops, and never + /// carried out with the value but by a call that ends it, as [`Self::reserve_ending`] + /// lets one. + pub fn holding(value: T, loan: Option) -> *const c_void + where + T: 'static, + { + Self::holding_by(value, loan, None) + } + + fn holding_by(value: T, loan: Option, owner: Option>) -> *const c_void + where + T: 'static, + { + Arc::into_raw(Arc::new(Self { + borrow: Borrow::new(0), + depth: UnsafeCell::new(0), + lent: std::ptr::null_mut(), + value: UnsafeCell::new(MaybeUninit::new(value)), + epoch: AtomicUsize::new(0), + lender: None, + owner, + held: loan.is_some(), + loan: UnsafeCell::new(loan), })) .cast() } @@ -1208,6 +1269,8 @@ impl Object { epoch: AtomicUsize::new(0), lender: Some(lender), owner, + loan: UnsafeCell::new(None), + held: false, })) .cast() } @@ -1371,10 +1434,17 @@ impl Object { } } - /// Take the value from no borrow to `to`, as an exclusive borrow or a move does. + /// Take the value from no borrow to `to`, as an exclusive borrow or a move does. A value + /// holding an exclusive lend moves out only as `ending` lets it, as the call it moves + /// into then ends it with the lend. fn acquire_from_zero(&self, to: usize) -> Result<(), Status> { + self.acquire_ending(to, false) + } + + fn acquire_ending(&self, to: usize, ending: bool) -> Result<(), Status> { self.own()?; - if self.lender.is_some() || (matches!(to, TAKEN | RESERVED) && !self.lent.is_null()) { + let moved = matches!(to, TAKEN | RESERVED); + if self.lender.is_some() || (moved && (!self.lent.is_null() || (self.held && !ending))) { return Err(Status::Lent); } self.borrow.take(&TABLE, to) @@ -1514,6 +1584,8 @@ impl Object { epoch: AtomicUsize::new(0), lender: None, owner, + loan: UnsafeCell::new(None), + held: false, }); // A second count, which a free by C would take, so the handle outlives it. let spare = Arc::clone(&object); @@ -1564,6 +1636,45 @@ impl Object { Ok(()) } + /// [`Self::reserve`] for a call the value ends in, as its lifetimes name nothing else + /// the call takes or returns: a value holding an exclusive lend may move out into it, + /// and [`Self::end`] gives the lend back once the call returns. + /// + /// # Safety + /// As [`Self::reserve`]. + pub unsafe fn reserve_ending<'a>(handle: *const c_void, takes: &mut Takes<'a>, what: &str) -> Result<(), Status> { + // SAFETY: the caller's contract. + let object = unsafe { Self::get(handle, what) }; + object.acquire_ending(RESERVED, true)?; + // SAFETY: as in `reserve`. + takes.push(unsafe { &*::std::ptr::addr_of!(object.borrow) }); + Ok(()) + } + + /// Give back the exclusive lend a value moved out by [`Self::reserve_ending`] held, now + /// that the call it moved into returned, and the value with it. + /// + /// # Safety + /// `handle` is a live handle of this type whose value such a call moved out. + pub unsafe fn end(handle: *const c_void) { + // SAFETY: the caller's contract: TAKEN excludes every other use of the loan. + drop(unsafe { (*(*handle.cast::()).loan.get()).take() }); + } + + /// Fail a call whose signature would carry a borrow out of the value, or let the value + /// outlive it, if the value holds an exclusive lend, whose borrow lasts only as long as + /// the value. + /// + /// # Safety + /// `handle` is null or a live handle of this type. + pub unsafe fn unheld(handle: *const c_void, what: &str) -> Result<(), Status> { + // SAFETY: the caller's contract; `held` never changes. + match !handle.is_null() && unsafe { Self::get(handle, what) }.held { + true => Err(Status::Lent), + false => Ok(()), + } + } + /// Borrow a `Copy` value shared until `takes` drops, so [`Self::held`] copies it out /// once the call's moves commit, and no check after them can fail. /// @@ -1659,15 +1770,21 @@ impl Object { } object.epoch.fetch_add(1, Ordering::Release); if object.lent.is_null() { + // SAFETY: TAKEN excludes every other access to the loan. + let loan = unsafe { (*object.loan.get()).take() }; match away { Some(owner) => { - // SAFETY: as below; the value moves out to drop on its own thread. + // SAFETY: as below; the value moves out to drop on its own thread, before + // the lend it holds is given back. let value = unsafe { (*object.value.get()).assume_init_read() }; // SAFETY: the value is the owner's. - unsafe { Dropped::new(value, owner.clone(), Unsent::<()>::named::()) }.send(); + unsafe { Dropped::new((value, loan), owner.clone(), Unsent::<()>::named::()) }.send(); + } + None => { + // SAFETY: TAKEN excludes every other access, and `Drop` skips a taken value. + unsafe { (*object.value.get()).assume_init_drop() }; + drop(loan); } - // SAFETY: TAKEN excludes every other access, and `Drop` skips a taken value. - None => unsafe { (*object.value.get()).assume_init_drop() }, } } Ok(()) @@ -1707,6 +1824,8 @@ impl Object { impl Drop for Object { fn drop(&mut self) { let mut owner = self.owner.take(); + // Given back only once the value dropped, wherever it drops. + let loan = self.loan.get_mut().take(); if self.lent.is_null() && *self.borrow.state.get_mut() != TAKEN { let value = self.value.get_mut(); match owner.take_if(|owner| !owner.is_here()) { @@ -1715,11 +1834,16 @@ impl Drop for Object { // SAFETY: as below; the value moves out to drop there, and nothing reads it here again. let value = unsafe { value.assume_init_read() }; // SAFETY: the value is the owner's. - unsafe { Dropped::new(value, owner, Unsent::<()>::named::()) }.send(); + unsafe { Dropped::new((value, loan), owner, Unsent::<()>::named::()) }.send(); + } + None => { + // SAFETY: the last reference is gone, and the value is its own and never taken. + unsafe { value.assume_init_drop() }; + drop(loan); } - // SAFETY: the last reference is gone, and the value is its own and never taken. - None => unsafe { value.assume_init_drop() }, } + } else { + drop(loan); } // A handle whose value dropped already, as one closed or lent, may hold the last // record of its home but the home's own: letting go wakes the home to see so. @@ -1739,6 +1863,14 @@ impl Object> { Self::owning(Unsent(value), Some(Thread::here())) } + /// [`Self::holding`] of a value that is not `Send`, on this thread. + pub fn holding_unsent(value: T, loan: Option) -> *const c_void + where + T: 'static, + { + Self::holding_by(Unsent(value), loan, Some(Thread::here())) + } + /// [`Self::lent`] of a value that is not `Send`, on this thread. pub fn lent_unsent(value: &T, lender: Lender) -> *const c_void { Self::lent_by(Unsent::from_ref(value), lender, Some(Thread::here())) @@ -1838,6 +1970,14 @@ pub struct Shared<'a, T> { ticket: Ticket, } +impl Shared<'_, T> { + /// The exclusive lend the value holds, for a clone of it to share. + pub fn loan(&self) -> Option { + // SAFETY: the shared borrow excludes the TAKEN that alone changes the hold. + unsafe { (*self.object.loan.get()).clone() } + } +} + impl Deref for Shared<'_, T> { type Target = T; fn deref(&self) -> &T { @@ -1867,6 +2007,14 @@ pub struct Local<'a, T> { ticket: Ticket, } +impl Local<'_, T> { + /// The exclusive lend the value holds, for a clone of it to share. + pub fn loan(&self) -> Option { + // SAFETY: the shared borrow excludes the TAKEN that alone changes the hold. + unsafe { (*self.object.loan.get()).clone() } + } +} + impl Deref for Local<'_, T> { type Target = T; fn deref(&self) -> &T { diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 8f0a91dcf..037e62fda 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -316,6 +316,12 @@ fn checked(api: &Api) -> Vec { if f.lends { lent(api, &f.ok, &mut checked); } + // A handle holding an exclusive lend refuses what would carry the borrow past it. + if f.lends_mut + && let Type::Object(j) = f.ok + { + checked[j] = true; + } } // What an implementation is lent, and what it hands Rust, which moves it out. for method in api.callbacks.iter().flat_map(|c| &c.methods) { @@ -326,6 +332,21 @@ fn checked(api: &Api) -> Vec { checked } +/// Whether an exclusive lend returns each object. +fn held(api: &Api) -> Vec { + let mut held = vec![false; api.objects.len()]; + let functions = (api.records.iter().flat_map(|r| &r.methods)) + .chain(api.enums.iter().flat_map(|e| &e.methods)) + .chain(api.objects.iter().flat_map(|o| &o.methods)) + .chain(&api.functions); + for f in functions.filter(|f| f.lends_mut) { + if let Type::Object(j) = f.ok { + held[j] = true; + } + } + held +} + /// `ty` as a clone of each borrow it holds. fn owned(ty: &Type) -> Type { match ty { @@ -362,6 +383,9 @@ pub struct Abi<'a> { pub arrays: BTreeMap, /// Whether a call can fail a check of each object's handle: see [`checked`]. pub checked: Vec, + /// Whether an exclusive lend returns each object, whose handle may then hold its + /// receiver's borrow. + pub held: Vec, /// Every C name claimed. claims: Vec, /// The C name of each item whose own clashed. @@ -382,6 +406,7 @@ impl<'a> Abi<'a> { tuples: BTreeMap::new(), arrays: BTreeMap::new(), checked: checked(api), + held: held(api), claims: Vec::new(), renames: HashMap::new(), clashes: Vec::new(), @@ -443,6 +468,7 @@ impl<'a> Abi<'a> { renames, clashes: self.clashes.clone(), checked: self.checked.clone(), + held: self.held.clone(), } } diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 4925796eb..38b4fab36 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -1922,6 +1922,9 @@ impl<'tcx> Collector<'tcx> { send: true, collect: false, lends: false, + lends_mut: false, + derefs: 0, + ties: false, access: Access::Parse, instance: None, home: Home::default(), @@ -1974,6 +1977,9 @@ impl<'tcx> Collector<'tcx> { send: true, collect: false, lends: false, + lends_mut: false, + derefs: 0, + ties: false, access: Access::Text, instance: None, home: Home::default(), @@ -2301,6 +2307,10 @@ impl<'tcx> Collector<'tcx> { /// Fill in every declaration, then the functions and constants. fn define(&mut self) { let tcx = self.tcx; + // Each object whose type derefs to another type, which forwards that one's methods. + let mut chains = Vec::new(); + // Each struct record's site, whose fields an object deref'ing to it forwards. + let mut records = rustc_data_structures::fx::FxHashMap::default(); for (def_id, path) in self.items.clone() { let span = tcx.def_span(def_id); let kind = tcx.def_kind(def_id); @@ -2360,6 +2370,9 @@ impl<'tcx> Collector<'tcx> { let args = self.args(&site).expect("settled"); match decl { Some(Decl::Record(index)) => { + if kind == DefKind::Struct { + records.insert(index, site.clone()); + } let variants = self.fields(&site).expect("settled"); let variant = variants.into_iter().next().expect("a struct has a variant"); let (methods, traits) = self.methods(&site); @@ -2399,6 +2412,11 @@ impl<'tcx> Collector<'tcx> { if kind == DefKind::Struct { methods.splice(0..0, self.accessors(&site)); } + let self_ty = self.site_ty(&site); + let chain = self.derefs(self_ty); + if !chain.is_empty() { + chains.push((index, self.member_names(self_ty), self.path_names(self_ty), chain)); + } let shared = traits.clone && self.clone_shares(self.site_ty(&site), def_id); let object = &mut self.api.objects[index]; object.args = args; @@ -2410,6 +2428,183 @@ impl<'tcx> Collector<'tcx> { } } } + for (object, names, paths, chain) in chains { + self.forward(object, names, paths, chain, &records); + } + } + + /// The types `ty` derefs to in turn, as Rust's auto-deref reaches them, each with its key + /// if it has one, how many `Deref`s reach it, and whether each of them is a `DerefMut`. + fn derefs(&self, mut ty: Ty<'tcx>) -> Vec<(Option>, Ty<'tcx>, usize, bool)> { + let tcx = self.tcx; + let lang = tcx.lang_items(); + let (Some(deref), Some(target)) = (lang.deref_trait(), lang.deref_target()) else { + return Vec::new(); + }; + let env = TypingEnv::fully_monomorphized(); + let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); + let implements = |tr: Option, ty: Ty<'tcx>| { + tr.is_some_and(|tr| { + infcx + .type_implements_trait(tr, [ty], param_env) + .must_apply_modulo_regions() + }) + }; + let mut chain = Vec::new(); + let mut mutable = true; + let mut seen = vec![ty]; + for derefs in 1..=tcx.recursion_limit().0 { + if !implements(Some(deref), ty) { + break; + } + mutable &= implements(lang.deref_mut_trait(), ty); + let projection = Ty::new_projection(tcx, ty::IsRigid::No, target, [ty]); + let Ok(next) = tcx.try_normalize_erasing_regions(env, ty::Unnormalized::new_wip(projection)) else { + break; + }; + if seen.contains(&next) { + break; + } + seen.push(next); + ty = next; + // Each, exported or not, as its members hide those of a type past it. + let key = match ty.kind() { + ty::Adt(adt, args) => Some(self.key(adt.did(), *args)), + _ => None, + }; + chain.push((key, ty, derefs, mutable)); + } + chain + } + + /// The names of `ty`'s `pub` inherent functions, with `self` or not, and constants, which + /// share its path with a field of the same name, as `field_key` counts them. + fn path_names(&self, ty: Ty<'tcx>) -> Vec { + let tcx = self.tcx; + let ty::Adt(adt, _) = ty.kind() else { + return Vec::new(); + }; + (tcx.inherent_impls(adt.did()).iter()) + .filter_map(|&imp| Some((imp, self.impl_args(imp, ty)?))) + .flat_map(|(imp, parent)| { + tcx.associated_items(imp) + .in_definition_order() + .map(move |item| (item, parent)) + }) + .filter(|(item, parent)| { + matches!(item.kind, ty::AssocKind::Fn { .. } | ty::AssocKind::Const { .. }) + && tcx.visibility(item.def_id).is_public() + && self.applies(item.def_id, *parent) + }) + .map(|(item, _)| item.name().to_string()) + .collect() + } + + /// The names of `ty`'s `pub` inherent methods, then of its `pub` fields, exported or not, + /// which hide any method or field of the same name a type it derefs to has, as they do in + /// Rust: a method of each inherent impl that applies to `ty`, whose own bounds Rust checks + /// only once it picked the method. A method never hides a field, nor a field a method. + fn member_names(&self, ty: Ty<'tcx>) -> (Vec, Vec) { + let tcx = self.tcx; + let ty::Adt(adt, _) = ty.kind() else { + return (Vec::new(), Vec::new()); + }; + let def_id = adt.did(); + let methods = (tcx.inherent_impls(def_id).iter()) + .filter(|&&imp| self.impl_args(imp, ty).is_some()) + .flat_map(|&imp| tcx.associated_items(imp).in_definition_order()) + .filter(|item| matches!(item.kind, ty::AssocKind::Fn { has_self: true, .. })) + .filter(|item| tcx.visibility(item.def_id).is_public()) + .map(|item| item.name().to_string()) + .collect(); + let mut fields = Vec::new(); + if tcx.def_kind(def_id) == DefKind::Struct { + let all = tcx.adt_def(def_id).non_enum_variant().fields.iter(); + fields.extend(all.filter(|f| f.vis.is_public()).map(|f| f.name.to_string())); + } + (methods, fields) + } + + /// Give object `object` the methods and field accessors of each type it derefs to, as + /// Rust's auto-deref reaches them: each one through `&self`, and through `&mut self` while + /// every `Deref` on the way is a `DerefMut`, unless a nearer type's member takes its name. + /// A target forwards what it exports itself, so its config and refusals hold here too. + fn forward( + &mut self, + object: usize, + mut names: (Vec, Vec), + paths: Vec, + chain: Vec<(Option>, Ty<'tcx>, usize, bool)>, + records: &rustc_data_structures::fx::FxHashMap>, + ) { + let (path, shown) = { + let o = &self.api.objects[object]; + (o.path.clone(), o.shown.clone()) + }; + let mut all = Vec::new(); + for (key, ty, derefs, mutable) in chain { + let members = match key.and_then(|key| self.decls.get(&key).cloned()) { + Some(Decl::Object(u)) => self.api.objects[u].methods.clone(), + Some(Decl::Value(u)) => self.api.records[u].methods.clone(), + // A record's fields cross with it, so reaching them through the object takes + // accessors of their own. + Some(Decl::Record(u)) => { + let mut members = match records.get(&u) { + Some(site) => self.accessors(site), + None => Vec::new(), + }; + members.extend(self.api.records[u].methods.iter().cloned()); + members + } + Some(Decl::Enum(u)) => self.api.enums[u].methods.clone(), + _ => Vec::new(), + }; + let forwarded: Vec = (members.into_iter()) + .filter(|m| { + let hiding = match m.access { + Access::Field { .. } => &names.1, + _ => &names.0, + }; + m.derefs == 0 && !hiding.iter().any(|name| name == m.name()) + }) + .filter(|m| match m.receiver { + Some(Receiver::Ref) => true, + Some(Receiver::Mut) => mutable, + _ => false, + }) + .map(|mut m| { + let name = |p: &Path| p.last().expect("a method has a name").clone(); + m.path = [&path[..], &[name(&m.path)]].concat(); + m.shown = [&shown[..], &[name(&m.shown)]].concat(); + m.derefs = derefs; + m + }) + .collect(); + all.extend(forwarded); + let (methods, fields) = self.member_names(ty); + names.0.extend(methods); + names.1.extend(fields); + } + // The config names a forwarded member by the object's path, as it does the object's + // own: a field by `field@` where the object's function or constant, or a method of a + // type on its chain, shares its path, which then names that item alone. + let mut kept = Vec::new(); + for mut m in all { + let keep = match &mut m.access { + Access::Field { shared, .. } => { + let field = m.path.last().expect("a field has a name"); + *shared = names.0.iter().chain(&paths).any(|name| name == field); + let mut key = m.shown.clone(); + key[1].insert_str(0, "field@"); + !self.exclude(&key) && (*shared || !self.exclude(&m.shown)) + } + _ => !self.exclude(&m.shown), + }; + if keep { + kept.push(m); + } + } + self.api.objects[object].methods.extend(kept); } /// Drop each foreign type's object that no export names, so a crate that only builds @@ -2606,6 +2801,16 @@ impl<'tcx> Collector<'tcx> { } } }; + // A field holding what borrows, as an object of the object's lifetime does, carries + // that borrow out through its getter and in through its setter, unless the field's + // own type names no lifetime but `'static` and no type parameter. + let independent = + (tcx.type_of(field.did).instantiate_identity().skip_norm_wip().walk()).all(|arg| match arg.kind() { + GenericArgKind::Lifetime(region) => region.is_static(), + GenericArgKind::Type(ty) => !matches!(ty.kind(), ty::Param(_)), + GenericArgKind::Const(_) => true, + }); + let ties = !independent && !self.lifetimes(ty).0.is_empty(); match mapped { Ok((get, set)) => { let accessor = |receiver, params, ok, set| Function { @@ -2626,6 +2831,9 @@ impl<'tcx> Collector<'tcx> { send: true, collect: false, lends: false, + lends_mut: false, + derefs: 0, + ties, access: Access::Field { shared, set }, instance: None, home: Home::default(), @@ -3006,23 +3214,90 @@ impl<'tcx> Collector<'tcx> { }; let env = TypingEnv::post_analysis(tcx, def_id); let sig = tcx.fn_sig(def_id).instantiate(tcx, args).skip_norm_wip(); - let (statics, lifetimes, interned) = self.borrows(def_id, sig.skip_binder()); + let has_self = matches!(tcx.def_kind(def_id), DefKind::AssocFn) + && matches!( + tcx.associated_item(def_id).kind, + ty::AssocKind::Fn { has_self: true, .. } + ); + let unbound = sig.skip_binder(); + let exclusive = (self.exclusive(def_id, unbound, has_self)).filter(|®ion| { + // Its lifetimes free, as a call's are: the late-bound ones its own. + let free = tcx.liberate_late_bound_regions(def_id, sig).output(); + let ok = match free.kind() { + ty::Adt(adt, args) if tcx.is_diagnostic_item(sym::Result, adt.did()) => args.type_at(0), + _ => free, + }; + self.lifetime_generic(ok) && self.lend_bounds_hold(def_id, args, region) + }); + let (statics, lifetimes, interned) = self.borrows(def_id, unbound, exclusive); errs.extend(lifetimes); // Whether what it returns borrows: any lifetime in it that is not `'static`. - let borrows = sig.skip_binder().output().walk().any(|arg| match arg.kind() { + let borrows = unbound.output().walk().any(|arg| match arg.kind() { GenericArgKind::Lifetime(region) => !statics.contains(®ion), _ => false, }); + // Whether a lifetime an object it takes holds is `'static`, or is named anywhere else + // in the signature, itself or through the bounds that relate it to another, so the + // value may outlive the call or carry its borrow out. Any other bound naming it ties + // it unless the trait solver proves it with no constraint on a lifetime but one that + // always holds, as `'a: 'a`: so `Receipt<'a>: Clone` does not, while + // `Receipt<'a>: Any`, whose impl needs `'static`, does, as does a bound only an impl + // for one lifetime meets. Each is proved in analysis, as a later mode proves a bound + // modulo every lifetime, with none of the function's own where-clauses, which would + // prove it, and none of what any lifetime outlives. + let outlives = self.outlives(def_id); + let empty = ty::ParamEnv::empty(); + let bounds: Vec> = (tcx.clauses_of(def_id).instantiate(tcx, args).clauses.iter()) + .map(|clause| clause.skip_norm_wip()) + .filter(|clause| clause.as_region_outlives_clause().is_none() && clause.as_type_outlives_clause().is_none()) + .filter(|&clause| { + // An instance's lifetime is the `'static` the glue names it by. + let clause = ty::fold_regions(tcx, clause, |region, _| match region.kind() { + ty::ReErased => tcx.lifetimes.re_static, + _ => region, + }); + let infcx = tcx.infer_ctxt().build(ty::TypingMode::non_body_analysis()); + let ocx = ObligationCtxt::new(&infcx); + ocx.register_obligation(Obligation::new(tcx, ObligationCause::dummy(), empty, clause)); + !(ocx.evaluate_obligations_error_on_ambiguity().no_errors() + && ocx + .resolve_regions(rustc_hir::def_id::CRATE_DEF_ID, empty, []) + .is_empty()) + }) + .collect(); + let ties = (unbound.inputs().iter().enumerate()).any(|(n, &input)| { + self.lifetimes(input).0.into_iter().any(|region| { + let mut related = vec![region]; + let mut i = 0; + while let Some(&at) = related.get(i) { + for &(long, short) in &outlives { + for (from, to) in [(long, short), (short, long)] { + if from == at && !related.contains(&to) { + related.push(to); + } + } + } + i += 1; + } + let names = |ty: Ty<'tcx>| { + ty.walk() + .any(|arg| arg.as_region().is_some_and(|r| related.contains(&r))) + }; + // An instance's lifetime is erased, and the glue names it `'static`. + related + .iter() + .any(|r| r.is_static() || matches!(r.kind(), ty::ReErased)) + || bounds + .iter() + .any(|clause| tcx.any_free_region_meets(clause, |r| related.contains(&r))) + || names(unbound.output()) + || (unbound.inputs().iter().enumerate()).any(|(m, &other)| m != n && names(other)) + }) + }); let names = tcx.fn_arg_idents(def_id); - let has_self = matches!(tcx.def_kind(def_id), DefKind::AssocFn) - && matches!( - tcx.associated_item(def_id).kind, - ty::AssocKind::Fn { has_self: true, .. } - ); // What it returns may borrow an object that is not `Clone` from a `&self` of an // object's alone, whose handle then lends it: Rust lends it only while no exclusive // borrow of the receiver begins, as the handle checks. - let unbound = sig.skip_binder(); let lendable = match unbound.inputs().first().map(|ty| ty.kind()) { Some(&ty::Ref(region, inner, ty::Mutability::Not)) if has_self @@ -3399,6 +3674,11 @@ impl<'tcx> Collector<'tcx> { } } let lends = ok.as_ref().is_ok_and(lent) && !self.is_clone(ok_ty.peel_refs()); + let lends_mut = exclusive.is_some() && !future && !collect && matches!(ok, Ok(Type::Object(_))); + // The borrow `borrows` let through is the lend's, or nothing may hold it. + if exclusive.is_some() && !lends_mut && ok.is_ok() { + errs.push(why("returned object that borrows", unbound.output().to_string())); + } let ok = ok.map_err(|why| errs.push(why)).ok(); let err = match err { Some(Ok(err)) => Some(err), @@ -3438,6 +3718,9 @@ impl<'tcx> Collector<'tcx> { send, collect, lends, + lends_mut, + derefs: 0, + ties, access: Access::Call, instance, home: Home::default(), @@ -3867,7 +4150,7 @@ impl<'tcx> Collector<'tcx> { fn sources(&self, def_id: DefId, target: Ty<'tcx>, outlives: bool) -> Result, bool, DefId)>, Why> { let tcx = self.tcx; let sig = tcx.fn_sig(def_id).instantiate_identity().skip_norm_wip(); - let (statics, ..) = self.borrows(def_id, sig.skip_binder()); + let (statics, ..) = self.borrows(def_id, sig.skip_binder(), None); // Each target, with whether what converts into it must outlive the call, and how // many conversions it is from the parameter. let root = target; @@ -4660,15 +4943,130 @@ impl<'tcx> Collector<'tcx> { .ok() } - /// The lifetimes the export makes `'static`, and why a signature's borrows cannot - /// cross. A handle outlives every call, so it holds the `'static` form of its type: - /// each lifetime an object takes, in the impl's type, an argument, or the return, is - /// `'static`, as is each lifetime that must outlive one. A borrow C lends lives only - /// for the call, so it may take none of them, but a `&str` parameter, which the glue - /// interns; every other lifetime is the call's. Also returns the inputs it interns. - fn borrows(&self, def_id: DefId, sig: ty::FnSig<'tcx>) -> (Vec>, Vec, Vec) { + /// The lifetime of the `&mut self` of an object's that what it returns alone borrows, if + /// any: an object, bare or as a `Result`'s value, whose handle then holds that exclusive + /// borrow until its value drops, as Rust holds it while the object lives. + fn exclusive(&self, def_id: DefId, sig: ty::FnSig<'tcx>, has_self: bool) -> Option> { + let tcx = self.tcx; + let object = |ty: Ty<'tcx>| { + matches!(ty.kind(), ty::Adt(adt, args) + if matches!(self.decl(adt.did(), ty::fold_regions(tcx, *args, |_, _| tcx.lifetimes.re_erased)), Some(Decl::Object(_)))) + }; + let &ty::Ref(region, receiver, ty::Mutability::Mut) = sig.inputs().first()?.kind() else { + return None; + }; + if !has_self || !object(receiver) || region.is_static() { + return None; + } + let names = |ty: Ty<'tcx>| ty.walk().any(|arg| arg.as_region() == Some(region)); + let ok = match sig.output().kind() { + ty::Adt(adt, args) if tcx.is_diagnostic_item(sym::Result, adt.did()) => { + (!names(args.type_at(1))).then(|| args.type_at(0))? + } + _ => sig.output(), + }; + // A copy would carry the borrow without the lend, which only a handle holds. + (object(ok) + && names(ok) + && !sig.inputs()[1..].iter().any(|&input| names(input)) + && !implements( + tcx, + ty::fold_regions(tcx, ok, |_, _| tcx.lifetimes.re_erased), + def_id, + sym::Copy, + )) + .then_some(region) + } + + /// Whether each trait the glue calls on a value of `ty`, its type's `'static` form, holds + /// at every lifetime `ty` names, as do its `Deref` and `DerefMut`, whose target names no + /// lifetime: one implemented for `'static` alone could keep what a value an exclusive + /// lend holds borrows past the lend. Each is proved with no where-clause and no lifetime + /// relation assumed, as a bound of a function is. + fn lifetime_generic(&self, ty: Ty<'tcx>) -> bool { + let tcx = self.tcx; + let lang = tcx.lang_items(); + let empty = ty::ParamEnv::empty(); + let named = [ + sym::Clone, + sym::PartialEq, + sym::Hash, + sym::Debug, + rustc_span::sym::Display, + ]; + let traits: Vec = (named.iter().filter_map(|&name| tcx.get_diagnostic_item(name))) + .chain(lang.deref_trait()) + .chain(lang.deref_mut_trait()) + .collect(); + let trait_ref = |tr: DefId, ty: Ty<'tcx>| match Some(tr) == tcx.get_diagnostic_item(sym::PartialEq) { + true => ty::TraitRef::new(tcx, tr, [ty, ty]), + false => ty::TraitRef::new(tcx, tr, [ty]), + }; + // Whether `tr` holds for `ty`, and whether it does with its lifetimes left free. + let holds = |tr: DefId, ty: Ty<'tcx>, free: bool| { + // An instance's erased lifetime is the `'static` the glue names it by; the + // lend's own stays free. + let ty = ty::fold_regions(tcx, ty, |region, _| match (free, region.kind()) { + (true, ty::ReErased) | (false, _) => tcx.lifetimes.re_static, + (true, _) => region, + }); + let infcx = tcx.infer_ctxt().build(ty::TypingMode::non_body_analysis()); + let ocx = ObligationCtxt::new(&infcx); + ocx.register_obligation(Obligation::new(tcx, ObligationCause::dummy(), empty, trait_ref(tr, ty))); + ocx.evaluate_obligations_error_on_ambiguity().no_errors() + && (!free + || ocx + .resolve_regions(rustc_hir::def_id::CRATE_DEF_ID, empty, []) + .is_empty()) + }; + if traits.iter().any(|&tr| holds(tr, ty, false) && !holds(tr, ty, true)) { + return false; + } + // A target naming no lifetime reaches nothing the lend's borrow does; one naming any + // would need its own traits proved at the lend's lifetime, which the export does not. + let (Some(deref), Some(target)) = (lang.deref_trait(), lang.deref_target()) else { + return true; + }; + if !holds(deref, ty, false) { + return true; + } + let erased = ty::fold_regions(tcx, ty, |_, _| tcx.lifetimes.re_static); + let projection = Ty::new_projection(tcx, ty::IsRigid::No, target, [erased]); + let env = TypingEnv::fully_monomorphized(); + tcx.try_normalize_erasing_regions(env, ty::Unnormalized::new_wip(projection)) + .is_ok_and(|next| !next.walk().any(|arg| arg.as_region().is_some())) + } + + /// Whether each bound of `def_id` at `args` that names the lend's lifetime `region` holds + /// with it free: the glue's lend gives the call a borrow of any lifetime, so a bound only + /// `'static` meets, as `&'static mut Self: Tr` alone would, lets the callee keep the + /// borrow past the lend. Each is proved as `ties` proves a bound, with no where-clause + /// and no lifetime relation assumed. + fn lend_bounds_hold(&self, def_id: DefId, args: ty::GenericArgs<'tcx>, region: ty::Region<'tcx>) -> bool { + let tcx = self.tcx; + let empty = ty::ParamEnv::empty(); + (tcx.clauses_of(def_id).instantiate(tcx, args).clauses.iter()) + .map(|clause| clause.skip_norm_wip()) + .filter(|&clause| tcx.any_free_region_meets(&clause, |r| r == region)) + .all(|clause| { + // An instance's lifetime is the `'static` the glue names it by. + let clause = ty::fold_regions(tcx, clause, |r, _| match r.kind() { + ty::ReErased => tcx.lifetimes.re_static, + _ => r, + }); + let infcx = tcx.infer_ctxt().build(ty::TypingMode::non_body_analysis()); + let ocx = ObligationCtxt::new(&infcx); + ocx.register_obligation(Obligation::new(tcx, ObligationCause::dummy(), empty, clause)); + ocx.evaluate_obligations_error_on_ambiguity().no_errors() + && ocx + .resolve_regions(rustc_hir::def_id::CRATE_DEF_ID, empty, []) + .is_empty() + }) + } + + /// Each `'long: 'short` the bounds of `def_id`'s signature name. + fn outlives(&self, def_id: DefId) -> Vec<(ty::Region<'tcx>, ty::Region<'tcx>)> { let tcx = self.tcx; - // Each `'long: 'short` the signature's bounds name. let mut outlives = Vec::new(); for clause in tcx.clauses_of(def_id).instantiate_identity(tcx).clauses { let clause = clause.skip_norm_wip(); @@ -4685,6 +5083,23 @@ impl<'tcx> Collector<'tcx> { ); } } + outlives + } + + /// The lifetimes the export makes `'static`, and why a signature's borrows cannot + /// cross. A handle outlives every call, so it holds the `'static` form of its type: + /// each lifetime an object takes, in the impl's type, an argument, or the return, is + /// `'static`, as is each lifetime that must outlive one. A borrow C lends lives only + /// for the call, so it may take none of them, but a `&str` parameter, which the glue + /// interns; every other lifetime is the call's. Also returns the inputs it interns. + fn borrows( + &self, + def_id: DefId, + sig: ty::FnSig<'tcx>, + exclusive: Option>, + ) -> (Vec>, Vec, Vec) { + let tcx = self.tcx; + let outlives = self.outlives(def_id); let close = |statics: &mut Vec>| { while let Some(&(long, _)) = outlives .iter() @@ -4757,7 +5172,10 @@ impl<'tcx> Collector<'tcx> { } } close(&mut statics); - if (lent.iter()).any(|(region, n, _)| !interned.contains(n) && statics[returned..].contains(region)) { + // But for the receiver an exclusive lend borrows, which the returned handle holds. + if (lent.iter()).any(|(region, n, _)| { + !interned.contains(n) && Some(*region) != exclusive && statics[returned..].contains(region) + }) { errs.push(why("returned object that borrows", sig.output().to_string())); } (statics, errs, interned) @@ -5174,6 +5592,9 @@ impl<'tcx> Collector<'tcx> { send: true, collect: false, lends: false, + lends_mut: false, + derefs: 0, + ties: false, access: Access::Const, instance: None, home: Home::default(), diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index a9632beea..aee7abca0 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -401,6 +401,7 @@ impl Crate<'_> { contract, dependency: dependency(&facade.root()), lends: false, + holding: Cell::new(false), on: On::ALL, out: String::new(), checking: Cell::new(false), @@ -575,6 +576,9 @@ struct Gen<'a> { /// Whether the function being written returns a borrow lent from its receiver's /// handle, which `lender` holds. lends: bool, + /// Whether the value being lowered is what an exclusive lend returns, whose handle + /// holds the receiver's borrow `a_self_loan` holds. + holding: Cell, /// The targets of the item being written, which compile what names its Rust types. on: On, out: String, @@ -1198,6 +1202,13 @@ impl Gen<'_> { Held::Arc => format!("rt::Object::new(rt::Opaque::new({e}))"), Held::Value => format!("rt::Object::new(rt::Owned::new({e}))"), }, + Type::Object(i) if self.holding.get() => { + let holding = match self.abi.api.objects[*i].send { + true => "holding", + false => "holding_unsent", + }; + format!("rt::Object::{holding}({e}, Some(a_self_loan.loan()))") + } Type::Object(i) => self.new_object(*i, e), Type::Callback(..) | Type::Closure(..) => unreachable!("a callback is never returned"), Type::Waker => format!("rt::Waker::lower({e})"), @@ -1449,14 +1460,15 @@ impl Gen<'_> { away(function, ¶ms, &held) }; if traits.clone { - let body = wrap( - status, - handle, - &format!( - "let this = {this};\n\t{}", - self.new_object(i, &format!("<{path} as ::std::clone::Clone>::clone({deref}this)")) - ), - ); + let clone = format!("<{path} as ::std::clone::Clone>::clone({deref}this)"); + // A clone of a value holding an exclusive lend shares it, as Rust's clones of a + // borrowing value share their borrow. + let clone = match (self.abi.held[i], send) { + (true, true) => format!("rt::Object::holding({clone}, this.loan())"), + (true, false) => format!("rt::Object::holding_unsent({clone}, this.loan())"), + (false, _) => self.new_object(i, &clone), + }; + let body = wrap(status, handle, &format!("let this = {this};\n\t{clone}")); let away = away(&format!("{name}_clone"), &["this"]); self.export(format!( "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_clone(this: {handle}{param}) -> {handle} {{\n\tlet w = \"{name}_clone\";\n\t{away}{body}\n}}\n" @@ -2314,11 +2326,16 @@ impl Gen<'_> { Type::Unit => format!("let _ = result;\n\t{ready}"), _ => format!("let v = result;\n\t{write_ok}\n\t{ready}"), }, - Some(err) => format!( - "match result {{\n\t\tOk(v) => {{\n\t\t\tlet _ = &v;\n\t\t\t{write_ok}\n\t\t\t{ready}\n\t\t}}\n\t\tErr(e) => {{\n\t\t\tunsafe {{ rt::write::<{}>(err.cast(), || {}) }};\n\t\t\t{error}\n\t\t}}\n\t}}", - rs(&self.abi.ty(err)), - self.lower(err, "e") - ), + Some(err) => { + // What an exclusive lend fails with holds no borrow. + let holding = self.holding.replace(false); + let lowered = self.lower(err, "e"); + self.holding.set(holding); + format!( + "match result {{\n\t\tOk(v) => {{\n\t\t\tlet _ = &v;\n\t\t\t{write_ok}\n\t\t\t{ready}\n\t\t}}\n\t\tErr(e) => {{\n\t\t\tunsafe {{ rt::write::<{}>(err.cast(), || {lowered}) }};\n\t\t\t{error}\n\t\t}}\n\t}}", + rs(&self.abi.ty(err)), + ) + } } } @@ -2349,6 +2366,8 @@ impl Gen<'_> { let mut moves = Vec::new(); let mut stmts = Vec::new(); let mut releases = Vec::new(); + // What gives back the exclusive lend each value a call ends held, once it returns. + let mut ended = Vec::new(); let mut sort = |ty: &Type, (reserve, stmt, _): &(String, String, String)| match (reserve.is_empty(), self.checks(ty)) { (false, _) => { @@ -2372,9 +2391,45 @@ impl Gen<'_> { Receiver::Mut => Type::Ref(Mutability::Mut, Box::new(Type::Object(*i))), Receiver::Owned => Type::Object(*i), }; - let made = self.arg(&ty, "this", "a_self", future); + let made = match receiver { + // The receiver's exclusive borrow, kept alive past the call by the + // handle it returns, as Rust keeps it while that value lives. + Receiver::Mut if function.lends_mut => { + let (_, borrow) = self.borrow(*i, Mutability::Mut, "this", true); + let pass = match self.abi.api.objects[*i].send { + true => "a_self", + false => "&mut **a_self", + }; + ( + String::new(), + format!( + "let mut a_self_loan = {borrow};\n\tlet a_self = unsafe {{ a_self_loan.lend() }};" + ), + pass.to_string(), + ) + } + Receiver::Owned if self.ends(function, *i) => { + ended.push(format!( + "unsafe {{ rt::Object::<{}>::end(this) }};", + self.object_path(*i) + )); + self.ending(*i, "this", "a_self") + } + _ => self.arg(&ty, "this", "a_self", future), + }; + if function.ties && self.abi.held[*i] { + sort( + &Type::Object(*i), + &(String::new(), self.unheld(*i, "this"), String::new()), + ); + } sort(&ty, &made); - args.push(made.2); + // Through each `Deref` to the type whose method it is, as Rust's auto-deref. + let deref = match receiver { + Receiver::Mut => "::std::ops::DerefMut::deref_mut", + _ => "::std::ops::Deref::deref", + }; + args.push((0..function.derefs).fold(made.2, |pass, _| format!("{deref}({pass})"))); if function.holds && *receiver != Receiver::Owned { held.push("a_self".to_string()); } @@ -2482,7 +2537,39 @@ impl Gen<'_> { if function.holds && lent { held.push(format!("a{n}")); } - let made = self.arg(¶m.ty, &format!("p{n}"), &format!("a{n}"), future); + // A handle an exclusive lend may have returned, as C passes one: by value, + // borrowed, or as `Some` of either. + let top = match ¶m.ty { + Type::Option(inner) => inner, + ty => ty, + }; + let held_object = match top { + Type::Ref(_, inner) => match **inner { + Type::Object(j) => Some(j), + _ => None, + }, + Type::Object(j) => Some(*j), + _ => None, + } + .filter(|&j| self.abi.held[j]); + if let Some(j) = held_object + && function.ties + { + sort( + &Type::Object(j), + &(String::new(), self.unheld(j, &format!("p{n}")), String::new()), + ); + } + let made = match (¶m.ty, held_object) { + (Type::Object(j), Some(_)) if self.ends(function, *j) => { + ended.push(format!( + "unsafe {{ rt::Object::<{}>::end(p{n}) }};", + self.object_path(*j) + )); + self.ending(*j, &format!("p{n}"), &format!("a{n}")) + } + _ => self.arg(¶m.ty, &format!("p{n}"), &format!("a{n}"), future), + }; if !made.0.is_empty() && let Some(release) = self.release(¶m.ty, &format!("p{n}")) { @@ -2587,13 +2674,20 @@ impl Gen<'_> { Some((_, owner_type)) => format!("<{}>::{}", self.rust(owner_type), function.name()), None => self.path(&function.path), }; + let mut turbofish = String::new(); if let Some(instance) = function.instance.as_ref().filter(|i| !i.args.is_empty()) { let args: Vec = (instance.args.iter()) .map(|ty| ty.as_ref().map_or_else(|| "_".to_string(), |ty| self.rust(ty))) .collect(); - callee = format!("{callee}::<{}>", args.join(", ")); + turbofish = format!("::<{}>", args.join(", ")); + callee = format!("{callee}{turbofish}"); } let call = match function.access { + // A method of the type the receiver derefs to, which the glue need not name: its + // receiver is that type's already, whose inherent method a call finds first. + Access::Call if function.derefs > 0 => { + format!("({}).{}{turbofish}({})", args[0], function.name(), args[1..].join(", ")) + } Access::Call => format!("{callee}({})", args.join(", ")), Access::Field { set: false, .. } => format!("&({}).{}", args[0], function.name()), Access::Field { set: true, .. } => format!("({}).{} = {}", args[0], function.name(), args[1]), @@ -2757,11 +2851,14 @@ impl Gen<'_> { params.extend(outs); let ret = rs(&export.call.ret); self.lends = function.lends; + self.holding.set(function.lends_mut); let finish = match function.err { Some(_) => self.finish(function, &function.ok, ("v", "true", "false")), None => self.finish(function, &function.ok, ("", "", "")), }; self.lends = false; + self.holding.set(false); + let ended: String = ended.iter().map(|end| format!("\n\t{end}")).collect(); let call = match (function.collect, &function.err, &function.access) { // An iterator's items, all taken now. (true, ..) => format!("::std::iter::Iterator::collect::<::std::vec::Vec<_>>({call})"), @@ -2791,13 +2888,43 @@ impl Gen<'_> { "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> {ret} {{\n\tlet w = \"{name}\";\n\tlet _ = w;\n\t{}{}\n}}\n", params.join(", "), away(&name, ¶ms), - wrap(status, &ret, &format!("{body}\n\tlet result = {call};{pending}{writes}\n\t{finish}")) + wrap(status, &ret, &format!("{body}\n\tlet result = {call};{ended}{pending}{writes}\n\t{finish}")) )); if export.homed { self.export(homed(&name, ¶ms, &ret, &unsent)); } } + /// Whether a call of `function` ends a value of object `i` it takes by value at its top: + /// none of the value's lifetimes names anything else in its signature, so the value, and + /// any exclusive lend it holds, cannot outlive a synchronous call. + fn ends(&self, function: &Function, i: usize) -> bool { + self.abi.held[i] && !function.ties && !function.future && function.access == Access::Call + } + + /// An argument of object `i` taken by value from its handle `c`, which may hold an + /// exclusive lend, as [`Self::arg`] makes one: the call it moves into gives the lend back + /// once it returns, as `end` does. + fn ending(&self, i: usize, c: &str, local: &str) -> (String, String, String) { + let reserve = self.checked(&format!( + "unsafe {{ rt::Object::<{}>::reserve_ending({c}, takes, w) }}", + self.object_path(i) + )) + ";"; + self.reserved.set(true); + let lifted = self.lift(&Type::Object(i), c, "true"); + self.reserved.set(false); + (reserve, format!("let {local} = {lifted};"), local.to_string()) + } + + /// The check that object `i`'s handle `c` holds no exclusive lend, for a call whose + /// signature would carry its borrow past the value. + fn unheld(&self, i: usize, c: &str) -> String { + self.checked(&format!( + "unsafe {{ rt::Object::<{}>::unheld({c}, w) }}", + self.object_path(i) + )) + ";" + } + /// The object that is not `Send` whose handle an argument of `ty` is at its top: by /// value, borrowed, or as `Some` of either. fn unsent_object(&self, ty: &Type) -> Option { diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index 1c2c87501..2eaeb64f0 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -446,6 +446,20 @@ pub struct Function { /// lent from its receiver's: shared, until the receiver's value is borrowed /// exclusively, moved out, or freed. pub lends: bool, + /// Whether it is a `&mut self` method of an object returning an object that borrows its + /// receiver, which C holds as a handle owning that value and the receiver's exclusive + /// borrow, given back once the value drops. A baseline written before it has none. + #[serde(default)] + pub lends_mut: bool, + /// For a method of a type its receiver's type derefs to, how many `Deref`s reach it from + /// the receiver's handle, each a `DerefMut` for `&mut self`, as Rust's auto-deref does. + #[serde(default)] + pub derefs: usize, + /// Whether a lifetime of an object it takes is `'static`, or names something else in the + /// signature, so the value may outlive the call or carry its borrow out of it: a handle an + /// exclusive lend returned fails it, since its borrow is the lend's. + #[serde(default)] + pub ties: bool, /// What it reads: Rust's function, a field it reads or writes, or a constant named as it is. pub access: Access, /// The instance it is, if a type parameter exports at several. diff --git a/ffi/src/lock.rs b/ffi/src/lock.rs index 877ed9059..18002bcab 100644 --- a/ffi/src/lock.rs +++ b/ffi/src/lock.rs @@ -779,11 +779,13 @@ fn fields(what: &str, ours: &[crate::ir::Field], theirs: &[crate::ir::Field]) -> /// What of the function `ours` changed in `theirs`, both bare and of one key. fn signature(ours: &Function, theirs: &Function) -> Vec { let (mut ours, mut theirs) = (ours.clone(), theirs.clone()); - // Which name the config gives a field: no binding names it otherwise. + // Which name the config gives a field: no binding names it otherwise. Nor whether a held + // handle fails it, which only a newer export lends and a baseline written before it lacks. for f in [&mut ours, &mut theirs] { if let Access::Field { shared, .. } = &mut f.access { *shared = false; } + f.ties = false; } let mut changes = Vec::new(); if ours.receiver != theirs.receiver { @@ -848,6 +850,9 @@ mod tests { send: true, collect: false, lends: false, + lends_mut: false, + derefs: 0, + ties: false, access: Access::Call, instance: None, home: Home { @@ -971,4 +976,12 @@ mod tests { assert!(changes[0].what.contains("lock_b")); assert!(changes[0].what.contains("lock_a")); } + + #[test] + fn ties_is_not_a_break() { + let base = api(); + let mut now = base.clone(); + now.functions[0].ties = true; + assert!(breaks(&base, &now, "lock").is_empty()); + } } diff --git a/ffi/tests/api.c b/ffi/tests/api.c index d3cd365a3..283cf1114 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -1718,6 +1718,55 @@ static int script(void) { api_Tally_free(tallied); api_Tallies_free(tallies); } + /* A draft borrowing its ledger exclusively until it drops, through which its sheet's + * members are reached by Deref and DerefMut. */ + { + api_Ledger *ledger = api_Ledger_new(); + api_Draft *draft; + api_Error err; + api_Ledger_edit(ledger, &draft, &err, NULL); + api_Draft_title_set(draft, str("minutes"), NULL); + api_Draft_write(draft, str("first"), NULL); + print("draft ", api_Draft_title_get(draft, NULL), " "); + printf("%u ", api_Draft_lines(draft, NULL)); + print("", api_Draft_describe(draft, NULL), " "); + printf("%s\n", api_Draft_edited(draft, NULL) ? "true" : "false"); + printf("committed %u\n", api_Draft_commit(draft, NULL)); + api_Draft_free(draft); + print("ledger ", api_Ledger_title(ledger, NULL), " "); + printf("%u\n", api_Ledger_published(ledger, NULL)); + api_Ledger_edit(ledger, &draft, &err, NULL); + printf("read %u %s\n", api_Draft_lines(draft, NULL), api_Draft_edited(draft, NULL) ? "true" : "false"); + api_Draft_free(draft); + api_Ledger_edit(ledger, &draft, &err, NULL); + api_Draft_write(draft, str("second"), NULL); + api_Draft_free(draft); + printf("dropped %u\n", api_Ledger_published(ledger, NULL)); + api_Receipt *receipt = api_Ledger_receipt(ledger, NULL); + printf("receipt %u\n", api_Receipt_count(receipt, NULL)); + api_Receipt_free(receipt); + { + api_Pad_u8 *small = api_Pad_u8_small(); + api_Pad_u16 *wide = api_Pad_u16_wide(); + api_Layered *layered = api_Layered_new(); + api_Marker *marker = api_Marker_new(str("m"), 3, 5); + api_Marker_y_set(marker, 7, NULL); + printf("forwarded %u %u %d %d", api_Pad_u16_title(wide), api_Layered_lines(layered), + api_Marker_x_get(marker, NULL), api_Marker_y_get(marker, NULL)); + print(" [", api_Pad_u8_describe(small), "]"); + print(" [", api_Pad_u16_describe(wide), "]\n"); + api_Marker_free(marker); + api_Layered_free(layered); + api_Pad_u16_free(wide); + api_Pad_u8_free(small); + } + api_Ledger_seal(ledger, NULL); + if (!api_Ledger_edit(ledger, &draft, &err, NULL)) { + print("sealed ", api_Error_to_string(&err), "\n"); + api_Error_free(&err); + } + api_Ledger_free(ledger); + } api_vec_bytes chunks = api_chunks(str("abcde"), 2); printf("chunks ["); @@ -2536,6 +2585,200 @@ static int statuses(void) { } api_Channel_free(channel); + /* A draft holds its ledger's exclusive borrow until it drops: any other use of the + * ledger fails meanwhile, as Rust's borrow checker refuses it, and a commit, a close, + * or a free of the draft gives it back. */ + { + api_Ledger *ledger = api_Ledger_new(); + api_Draft *draft; + api_Error err; + api_Ledger_edit(ledger, &draft, &err, NULL); + status = 0; + api_Ledger_published(ledger, &status); + if (status != API_STATUS_EXCLUSIVE) { + fprintf(stderr, "a read of a lent ledger wrote %d\n", status); + failed = 1; + } + status = 0; + api_Draft *second; + if (api_Ledger_edit(ledger, &second, &err, &status) || status != API_STATUS_BORROWED) { + fprintf(stderr, "a second draft of a lent ledger wrote %d\n", status); + failed = 1; + } + status = 0; + api_Ledger_drop(ledger, &status); + if (status != API_STATUS_BORROWED) { + fprintf(stderr, "a drop of a lent ledger wrote %d\n", status); + failed = 1; + } + /* A draft that must outlive the program, which a lent one never does. */ + status = 0; + if (api_lasting(draft, &status) || status != API_STATUS_LENT) { + fprintf(stderr, "a lent draft passed as lasting wrote %d\n", status); + failed = 1; + } + api_Draft_write(draft, str("x"), NULL); + status = 0; + if (api_Draft_commit(draft, &status) != 1 || status != 0) { + fprintf(stderr, "a commit wrote %d\n", status); + failed = 1; + } + /* The commit moved the draft out and gave the borrow back. */ + status = 0; + api_Draft_lines(draft, &status); + if (status != API_STATUS_MOVED) { + fprintf(stderr, "a committed draft wrote %d\n", status); + failed = 1; + } + status = 0; + if (api_Ledger_published(ledger, &status) != 1 || status != 0) { + fprintf(stderr, "a ledger after a commit wrote %d\n", status); + failed = 1; + } + api_Draft_free(draft); + /* A close gives it back too, publishing what the draft marked. */ + api_Ledger_edit(ledger, &draft, &err, NULL); + api_Draft_write(draft, str("y"), NULL); + status = 0; + api_Draft_drop(draft, &status); + if (status != 0 || api_Ledger_published(ledger, &status) != 2 || status != 0) { + fprintf(stderr, "a ledger after a close wrote %d\n", status); + failed = 1; + } + api_Draft_free(draft); + /* The ledger freed while lent drops once the draft does, which still works. */ + api_Ledger_edit(ledger, &draft, &err, NULL); + api_Ledger_free(ledger); + api_Draft_write(draft, str("z"), NULL); + status = 0; + if (api_Draft_commit(draft, &status) != 3 || status != 0) { + fprintf(stderr, "a draft of a freed ledger wrote %d\n", status); + failed = 1; + } + api_Draft_free(draft); + /* Clones of a receipt share its borrow, which the last one to drop gives back. */ + ledger = api_Ledger_new(); + api_Receipt *receipt = api_Ledger_receipt(ledger, NULL); + api_Receipt *copy = api_Receipt_clone(receipt, NULL); + api_Receipt_free(receipt); + status = 0; + api_Ledger_seal(ledger, &status); + if (status != API_STATUS_BORROWED || api_Receipt_count(copy, NULL) != 0) { + fprintf(stderr, "a ledger a cloned receipt borrows wrote %d\n", status); + failed = 1; + } + api_Receipt_free(copy); + status = 0; + api_Ledger_seal(ledger, &status); + if (status != 0) { + fprintf(stderr, "a ledger after its receipts wrote %d\n", status); + failed = 1; + } + /* A receipt whose bound lets it live as long as the program, and a field of a + * slip's clone, which would carry the ledger's borrow out, each fail as lent. */ + receipt = api_Ledger_receipt(ledger, NULL); + status = 0; + api_stored(receipt, &status); + if (status != API_STATUS_LENT || api_Receipt_count(receipt, NULL) != 0) { + fprintf(stderr, "a lent receipt stored wrote %d\n", status); + failed = 1; + } + status = 0; + api_erased(receipt, &status); + if (status != API_STATUS_LENT) { + fprintf(stderr, "a lent receipt erased wrote %d\n", status); + failed = 1; + } + status = 0; + api_summed_up_Receipt(receipt, &status); + if (status != API_STATUS_LENT) { + fprintf(stderr, "a lent receipt summed up wrote %d\n", status); + failed = 1; + } + status = 0; + if (api_tallied(receipt, &status) != 0 || status != 0) { + fprintf(stderr, "a lent receipt tallied wrote %d\n", status); + failed = 1; + } + status = 0; + api_Ledger_seal(ledger, &status); + if (status != 0) { + fprintf(stderr, "a ledger after its receipt moved into a call wrote %d\n", status); + failed = 1; + } + api_Receipt_free(receipt); + /* A lend bounded on its own borrow by a trait every lifetime meets borrows the + * ledger as any lend does. */ + receipt = api_Ledger_noted(ledger, NULL); + status = 0; + api_Ledger_seal(ledger, &status); + if (status != API_STATUS_BORROWED || api_Receipt_count(receipt, NULL) != 0) { + fprintf(stderr, "a ledger a noted receipt borrows wrote %d\n", status); + failed = 1; + } + api_Receipt_free(receipt); + api_Slip *slip = api_Ledger_slip(ledger, NULL); + api_Slip *twin = api_Slip_clone(slip, NULL); + api_Slip_free(slip); + status = 0; + api_Slip_receipt_get(twin, &status); + if (status != API_STATUS_LENT || api_Slip_count(twin, NULL) != 0) { + fprintf(stderr, "a lent slip's receipt wrote %d\n", status); + failed = 1; + } + /* A field that borrows only what outlives the ledger reads as ever. */ + status = 0; + api_Receipt *global = api_Slip_global_get(twin, &status); + if (status != 0 || api_Receipt_count(global, NULL) != 7) { + fprintf(stderr, "a lent slip's global receipt wrote %d\n", status); + failed = 1; + } + api_Receipt_free(global); + api_Slip_free(twin); + status = 0; + api_Ledger_seal(ledger, &status); + if (status != 0) { + fprintf(stderr, "a ledger after its slips wrote %d\n", status); + failed = 1; + } + api_Ledger_free(ledger); + /* Only `Pad`'s own `describe` hides its sheet's. */ + api_Pad_u8 *small = api_Pad_u8_small(); + api_Pad_u16 *wide = api_Pad_u16_wide(); + api_buf padded = api_Pad_u8_describe(small); + api_buf sheeted = api_Pad_u16_describe(wide); + if (padded.len != 5 || memcmp(padded.ptr, "pad 1", 5) != 0 || sheeted.len != 6 || + memcmp(sheeted.ptr, "sheet ", 6) != 0 || api_Pad_u16_tag(wide) != 2) { + fprintf(stderr, "pads describe as %.*s and %.*s\n", (int)padded.len, (const char *)padded.ptr, + (int)sheeted.len, (const char *)sheeted.ptr); + failed = 1; + } + api_buf_free(padded); + api_buf_free(sheeted); + /* `Pad`'s own `title`, whose path the config shares with its sheet's field. */ + if (api_Pad_u16_title(wide) != 2) { + fprintf(stderr, "a pad's title is %u\n", api_Pad_u16_title(wide)); + failed = 1; + } + /* A sheet behind a layer that does not export, whose `lines` it reaches. */ + api_Layered *layered = api_Layered_new(); + if (api_Layered_lines(layered) != 0) { + fprintf(stderr, "a layered sheet has lines\n"); + failed = 1; + } + api_Layered_free(layered); + /* A record's fields, reached through `Deref` and written through `DerefMut`. */ + api_Marker *marker = api_Marker_new(str("m"), 3, 5); + api_Marker_y_set(marker, 7, NULL); + if (api_Marker_x_get(marker, NULL) != 3 || api_Marker_y_get(marker, NULL) != 7) { + fprintf(stderr, "a marker's point is %d, %d\n", api_Marker_x_get(marker, NULL), api_Marker_y_get(marker, NULL)); + failed = 1; + } + api_Marker_free(marker); + api_Pad_u8_free(small); + api_Pad_u16_free(wide); + } + status = 0; api_Meters *meters = api_Meters_new(); api_Meter *first = api_Meters_first(meters, NULL); diff --git a/ffi/tests/api.cpp b/ffi/tests/api.cpp index c4384d21f..cdd569cd8 100644 --- a/ffi/tests/api.cpp +++ b/ffi/tests/api.cpp @@ -1042,6 +1042,43 @@ int script() { tallies.first().bump(); std::printf("tallied %u\n", tallies.first().bump()); } + { + // A draft borrowing its ledger exclusively until it is destroyed, through which its + // sheet's members are reached by Deref and DerefMut. + auto ledger = api::Ledger::new_(); + { + auto draft = ledger.edit().value(); + draft.title_set("minutes"); + draft.write("first"); + print("draft ", draft.title_get(), " "); + std::printf("%u ", draft.lines()); + print("", draft.describe(), " "); + std::printf("%s\n", yes(draft.edited())); + std::printf("committed %u\n", std::move(draft).commit()); + } + print("ledger ", ledger.title(), " "); + std::printf("%u\n", ledger.published()); + { + auto draft = ledger.edit().value(); + std::printf("read %u %s\n", draft.lines(), yes(draft.edited())); + } + { + auto draft = ledger.edit().value(); + draft.write("second"); + } + std::printf("dropped %u\n", ledger.published()); + std::printf("receipt %u\n", ledger.receipt().count()); + { + auto marker = api::Marker::new_(api::input("m"), 3, 5); + marker.y_set(7); + std::printf("forwarded %u %u %d %d", api::Pad_u16::wide().title(), api::Layered::new_().lines(), + marker.x_get(), marker.y_get()); + print(" [", api::Pad_u8::small().describe(), "]"); + print(" [", api::Pad_u16::wide().describe(), "]\n"); + } + ledger.seal(); + print("sealed ", api::Error_to_string(ledger.edit().error()), "\n"); + } std::printf("chunks ["); auto chunks = api::chunks("abcde", 2); @@ -2067,6 +2104,11 @@ int broken(const char *which) { recv.poll(waker); } else if (std::strcmp(which, "null view") == 0) { api::len(api::view(nullptr, 1)); + } else if (std::strcmp(which, "lent ledger") == 0) { + // A ledger used while a draft holds its exclusive borrow. + api::Ledger ledger = api::Ledger::new_(); + api::Draft draft = ledger.edit().value(); + ledger.published(); } else if (std::strcmp(which, "outlived") == 0) { api::Meters meters = api::Meters::new_(); api::Meter first = meters.first(); diff --git a/ffi/tests/api.dart b/ffi/tests/api.dart index d70e884c9..71a267cae 100644 --- a/ffi/tests/api.dart +++ b/ffi/tests/api.dart @@ -705,6 +705,46 @@ Future script() async { final tallies = api.Tallies(); tallies.first().bump(); print('tallied ${tallies.first().bump()}'); + // A draft borrowing its ledger exclusively until it closes, through which its sheet's + // members are reached by Deref and DerefMut: the ledger refuses any other use meanwhile. + final ledger = api.Ledger(); + var draft = ledger.edit(); + draft.titleSet('minutes'); + draft.write('first'); + print('draft ${draft.titleGet} ${draft.lines()} ${draft.describe()} ${draft.edited()}'); + try { + ledger.published(); + check(false, 'a lent ledger refuses a read'); + } on StateError catch (e) { + check(e.message == 'api_Ledger_published: a handle is borrowed exclusively', 'a lent ledger: $e'); + } + print('committed ${draft.commit()}'); + print('ledger ${ledger.title()} ${ledger.published()}'); + draft = ledger.edit(); + print('read ${draft.lines()} ${draft.edited()}'); + draft.close(); + draft = ledger.edit(); + draft.write('second'); + draft.close(); + print('dropped ${ledger.published()}'); + final receipt = ledger.receipt(); + print('receipt ${receipt.count()}'); + receipt.close(); + final padSmall = api.PadU8.small(), padWide = api.PadU16.wide(), layered = api.Layered(); + final marker = api.Marker('m', 3, 5); + marker.ySet(7); + print('forwarded ${padWide.title()} ${layered.lines()} ${marker.xGet} ${marker.yGet} ' + '[${padSmall.describe()}] [${padWide.describe()}]'); + for (final handle in [padSmall, padWide, layered, marker]) { + handle.close(); + } + ledger.seal(); + try { + ledger.edit().close(); + } on api.Error catch (e) { + print('sealed $e'); + } + ledger.close(); tallies.close(); print('chunks ${api.chunks(utf8.encode('abcde'), api.U64(2))}'); final counters = api.counters(['x', 'y']); diff --git a/ffi/tests/api.go b/ffi/tests/api.go index 7a355f8a6..0004ae21a 100644 --- a/ffi/tests/api.go +++ b/ffi/tests/api.go @@ -812,6 +812,41 @@ func script() { tallies := api.NewTallies() _ = must(must(tallies.First()).Bump()) fmt.Printf("tallied %d\n", must(must(tallies.First()).Bump())) + // A draft borrowing its ledger exclusively until it closes, through which its sheet's + // members are reached by Deref and DerefMut: the ledger refuses any other use meanwhile. + ledger := api.NewLedger() + draft := must(ledger.Edit()) + check(draft.TitleSet("minutes") == nil, "a draft's title sets") + check(draft.Write("first") == nil, "a draft writes") + fmt.Printf("draft %s %d %s %t\n", must(draft.TitleGet()), must(draft.Lines()), must(draft.Describe()), must(draft.Edited())) + _, exclusive := ledger.Published() + check( + errors.Is(exclusive, rt.ErrBorrowed) && exclusive.Error() == "api_Ledger_published: a handle is borrowed exclusively", + fmt.Sprintf("a lent ledger refuses a read: %v", exclusive), + ) + fmt.Printf("committed %d\n", must(draft.Commit())) + fmt.Printf("ledger %s %d\n", must(ledger.Title()), must(ledger.Published())) + draft = must(ledger.Edit()) + fmt.Printf("read %d %t\n", must(draft.Lines()), must(draft.Edited())) + check(draft.Close() == nil, "a draft closes") + draft = must(ledger.Edit()) + check(draft.Write("second") == nil, "a draft writes") + check(draft.Close() == nil, "a draft closes") + fmt.Printf("dropped %d\n", must(ledger.Published())) + receipt := must(ledger.Receipt()) + fmt.Printf("receipt %d\n", must(receipt.Count())) + check(receipt.Close() == nil, "a receipt closes") + padSmall, padWide, layered := api.PadU8Small(), api.PadU16Wide(), api.NewLayered() + marker := must(api.NewMarker("m", 3, 5)) + check(marker.YSet(7) == nil, "a marker's point sets") + fmt.Printf("forwarded %d %d %d %d [%s] [%s]\n", must(padWide.Title()), must(layered.Lines()), must(marker.XGet()), must(marker.YGet()), must(padSmall.Describe()), must(padWide.Describe())) + for _, closer := range []interface{ Close() error }{padSmall, padWide, layered, marker} { + check(closer.Close() == nil, "a forwarding handle closes") + } + check(ledger.Seal() == nil, "a ledger seals") + _, sealed := ledger.Edit() + fmt.Printf("sealed %s\n", sealed) + check(ledger.Close() == nil, "a ledger closes") fmt.Printf("chunks %s\n", list(api.Chunks(rt.NewBytes([]byte("abcde")), 2), func(b rt.Bytes) string { return list(b.Copy(), number) })) counters := must(api.Counters([]string{"x", "y"})) fmt.Printf("counters %s\n", strings.Trim(list(counters, func(c *api.Counter) string { diff --git a/ffi/tests/api.kt b/ffi/tests/api.kt index b7380a2e4..107ab47fa 100644 --- a/ffi/tests/api.kt +++ b/ffi/tests/api.kt @@ -624,6 +624,39 @@ fun script() { tallies.first().use { it.bump() } println("tallied ${tallies.first().use { it.bump() }}") } + // A draft borrowing its ledger exclusively until it closes, through which its sheet's + // members are reached by Deref and DerefMut: the ledger refuses any other use meanwhile. + Ledger.new().use { ledger -> + val draft = ledger.edit() + draft.titleSet("minutes") + draft.write("first") + println("draft ${draft.titleGet} ${draft.lines()} ${draft.describe()} ${draft.edited()}") + val refused = runCatching { ledger.published() }.exceptionOrNull() + check( + refused is IllegalStateException && refused.message == "api_Ledger_published: a handle is borrowed exclusively", + "a lent ledger refuses a read: $refused", + ) + println("committed ${draft.commit()}") + println("ledger ${ledger.title()} ${ledger.published()}") + ledger.edit().use { println("read ${it.lines()} ${it.edited()}") } + ledger.edit().use { it.write("second") } + println("dropped ${ledger.published()}") + println("receipt ${ledger.receipt().use { it.count() }}") + Marker.new("m", 3, 5).use { marker -> + marker.ySet(7) + val title = PadU16.wide().use { it.title() } + val lines = Layered.new().use { it.lines() } + val small = PadU8.small().use { it.describe() } + val wide = PadU16.wide().use { it.describe() } + println("forwarded $title $lines ${marker.xGet} ${marker.yGet} [$small] [$wide]") + } + ledger.seal() + try { + ledger.edit().close() + } catch (e: ErrorException) { + println("sealed ${e.message}") + } + } println("chunks ${chunks(Bytes("abcde".encodeToByteArray()), 2uL).map { it.toByteArray().toList() }}") val counters = counters(listOf("x", "y")) println("counters ${counters.joinToString(", ") { "${it.name()} ${it.get()}" }}") diff --git a/ffi/tests/api.py b/ffi/tests/api.py index 259ef0d6d..69befd3ad 100644 --- a/ffi/tests/api.py +++ b/ffi/tests/api.py @@ -684,6 +684,41 @@ async def polls(): tallies = api.Tallies.new() tallies.first().bump() print(f"tallied {tallies.first().bump()}") + # A draft borrowing its ledger exclusively until its last reference goes, through which + # its sheet's members are reached by Deref and DerefMut: the ledger refuses any other use + # meanwhile. + ledger = api.Ledger.new() + draft = ledger.edit() + draft.title_set("minutes") + draft.write("first") + print(f"draft {draft.title_get} {draft.lines()} {draft.describe()} {flag(draft.edited())}") + try: + ledger.published() + check(False, "a lent ledger refuses a read") + except RuntimeError as e: + check(str(e) == "api_Ledger_published: a handle is borrowed exclusively", repr(e)) + print(f"committed {draft.commit()}") + del draft + print(f"ledger {ledger.title()} {ledger.published()}") + draft = ledger.edit() + print(f"read {draft.lines()} {flag(draft.edited())}") + del draft + draft = ledger.edit() + draft.write("second") + del draft + print(f"dropped {ledger.published()}") + print(f"receipt {ledger.receipt().count()}") + marker = api.Marker.new("m", 3, 5) + marker.y_set(7) + print( + f"forwarded {api.PadU16.wide().title()} {api.Layered.new().lines()} {marker.x_get} {marker.y_get}" + f" [{api.PadU8.small().describe()}] [{api.PadU16.wide().describe()}]" + ) + ledger.seal() + try: + ledger.edit() + except api.ErrorException as e: + print(f"sealed {e}") print(f"chunks {[list(data(chunk)) for chunk in api.chunks(b'abcde', 2)]}") counters = api.counters(["x", "y"]) print("counters " + ", ".join(f"{c.name()} {c.get()}" for c in counters)) diff --git a/ffi/tests/api.swift b/ffi/tests/api.swift index 55bdc3c18..3f1e4f464 100644 --- a/ffi/tests/api.swift +++ b/ffi/tests/api.swift @@ -892,6 +892,50 @@ func script() { _ = try! tallies.first().bump() print("tallied \(try! tallies.first().bump())") } + do { + // A draft borrowing its ledger exclusively until it is consumed, through which its + // sheet's members are reached by Deref and DerefMut: the ledger refuses any other use + // meanwhile. + var ledger = Ledger.new() + var draft = try! ledger.edit() + try! draft.titleSet("minutes") + try! draft.write("first") + print("draft \(try! draft.titleGet) \(try! draft.lines()) \(try! draft.describe()) \(try! draft.edited())") + do { + _ = try ledger.published() + check(false, "a lent ledger refuses a read") + } catch let e as CheckError { + check( + e.function == "api_Ledger_published" && e.message == "a handle is borrowed exclusively", + "a lent ledger threw \(e)" + ) + } catch { + check(false, "a lent ledger threw \(error)") + } + print("committed \(try! draft.commit())") + print("ledger \(try! ledger.title()) \(try! ledger.published())") + let read = try! ledger.edit() + print("read \(try! read.lines()) \(try! read.edited())") + _ = consume read + var second = try! ledger.edit() + try! second.write("second") + _ = consume second + print("dropped \(try! ledger.published())") + print("receipt \(try! ledger.receipt().count())") + var marker = Marker.new("m", 3, 5) + try! marker.ySet(7) + print("forwarded \(PadU16.wide().title()) \(Layered.new().lines()) \(try! marker.xGet) \(try! marker.yGet) [\(PadU8.small().describe())] [\(PadU16.wide().describe())]") + _ = consume marker + try! ledger.seal() + do { + _ = try ledger.edit() + check(false, "a sealed ledger refuses a draft") + } catch let e as Api.Error { + print("sealed \(e)") + } catch { + check(false, "a sealed ledger throws an Error") + } + } print("chunks \(chunks(Bytes("abcde".utf8), 2).map { Array($0) })") var counters = counters(["x", "y"]) print("counters \(listed(counters) { "\(try! $0.name()) \(try! $0.get())" })") diff --git a/ffi/tests/api.ts b/ffi/tests/api.ts index 06f8ffbc1..b3a96fa53 100644 --- a/ffi/tests/api.ts +++ b/ffi/tests/api.ts @@ -27,6 +27,7 @@ import * as Counter from "./web/Counter.ts"; import * as Cursor from "./web/Cursor.ts"; import * as Der from "./web/Der.ts"; import * as Digest from "./web/Digest.ts"; +import * as Draft from "./web/Draft.ts"; import * as Error_ from "./web/Error_.ts"; import type * as Event from "./web/Event.ts"; import * as Extent from "./web/Extent.ts"; @@ -37,10 +38,13 @@ import * as Json from "./web/Json.ts"; import * as Key from "./web/Key.ts"; import * as Label from "./web/Label.ts"; import * as Labelled from "./web/Labelled.ts"; +import * as Layered from "./web/Layered.ts"; +import * as Ledger from "./web/Ledger.ts"; import * as Local from "./web/Local.ts"; import type { Log } from "./web/Log.ts"; import * as Logger from "./web/Logger.ts"; import * as Mark from "./web/Mark.ts"; +import * as Marker from "./web/Marker.ts"; import * as Measure from "./web/Measure.ts"; import * as Message from "./web/Message.ts"; import * as Meter from "./web/Meter.ts"; @@ -50,11 +54,14 @@ import * as Name from "./web/Name.ts"; import * as Node from "./web/Node.ts"; import * as Numbers from "./web/Numbers.ts"; import * as OuterInnerU8 from "./web/OuterInnerU8.ts"; +import * as PadU16 from "./web/PadU16.ts"; +import * as PadU8 from "./web/PadU8.ts"; import * as PairSizeU8 from "./web/PairSizeU8.ts"; import * as PairU32 from "./web/PairU32.ts"; import * as PairU8Size from "./web/PairU8Size.ts"; import * as Peer from "./web/Peer.ts"; import * as Point from "./web/Point.ts"; +import * as Receipt from "./web/Receipt.ts"; import * as Registry from "./web/Registry.ts"; import * as Retry from "./web/Retry.ts"; import * as Score from "./web/Score.ts"; @@ -894,6 +901,49 @@ async function script(): Promise { Tally.bump(Tallies.first(tallies)); print(`tallied ${Tally.bump(Tallies.first(tallies))}`); close(tallies); + // A draft the ledger's `edit` lends holds the ledger borrowed exclusively until it closes, + // and its sheet's members are reached by Deref and DerefMut: the ledger refuses any other + // use meanwhile. + const ledger = Ledger.new(); + const edit = (): Draft.Draft => { + const edited = Ledger.edit(ledger); + if (!edited.ok) throw new Error("an unsealed ledger lends a draft"); + return edited.value; + }; + let draft = edit(); + Draft.titleSet(draft, "minutes"); + Draft.write(draft, "first"); + print(`draft ${Draft.titleGet(draft)} ${Draft.lines(draft)} ${Draft.describe(draft)} ${Draft.edited(draft)}`); + borrowed(() => Ledger.published(ledger), "api_Ledger_published: a handle is borrowed exclusively", "a lent ledger refuses a read"); + print(`committed ${Draft.commit(draft)}`); + close(draft); + print(`ledger ${Ledger.title(ledger)} ${Ledger.published(ledger)}`); + draft = edit(); + print(`read ${Draft.lines(draft)} ${Draft.edited(draft)}`); + close(draft); + draft = edit(); + Draft.write(draft, "second"); + close(draft); + print(`dropped ${Ledger.published(ledger)}`); + const receipt = Ledger.receipt(ledger); + print(`receipt ${Receipt.count(receipt)}`); + close(receipt); + { + const small = PadU8.small(); + const wide = PadU16.wide(); + const layered = Layered.new$(); + const marker = Marker.new$("m", 3, 5); + Marker.ySet(marker, 7); + print( + `forwarded ${PadU16.title(wide)} ${Layered.lines(layered)} ${Marker.xGet(marker)} ${Marker.yGet(marker)} ` + + `[${PadU8.describe(small)}] [${PadU16.describe(wide)}]`, + ); + for (const handle of [small, wide, layered, marker]) close(handle); + } + Ledger.seal(ledger); + const sealed = Ledger.edit(ledger); + if (!sealed.ok) print(`sealed ${Error_.toString(sealed.error)}`); + close(ledger); print(`chunks ${list(api.chunks(enc("abcde"), 2).map(list))}`); const counters = api.counters(["x", "y"]); print(`counters ${counters.map((n) => `${Counter.name(n)} ${dec(Counter.get(n))}`).join(", ")}`); diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index d9e25c625..6f7378d18 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -99,6 +99,33 @@ fn exporter(name: &str, out: &Path, targets: &[&str], args: &[&std::ffi::OsStr], command } +/// What `Deref` forwards: a member the object or a nearer target has hides one past it, even +/// a target that does not export, a method only a method and a field only a field, and the +/// config leaves out a forwarded member by the object's path, a field sharing a method's by +/// `field@`. An exclude naming nothing fails the export, so each one here was forwarded. +#[test] +fn deref_shadowing() { + let header = std::fs::read_to_string(api().out.join("include").join("api.h")).unwrap(); + for present in [ + "api_Layered_lines(", + "api_Pad_u16_title(", + "api_Marker_x_get(", + "api_Marker_x_set(", + "api_Marker_y_get(", + ] { + assert!(header.contains(present), "{present} is not exported"); + } + for absent in [ + "api_Layered_describe(", + "api_Pad_u16_lines(", + "api_Pad_u16_title_get(", + "api_Marker_x(", + "api_Marker_y(", + ] { + assert!(!header.contains(absent), "{absent} is exported"); + } +} + /// The api fixture, exported and built once for each language's test. struct Api { /// The export. @@ -421,6 +448,7 @@ fn api_cpp() { ("overread", "api_tail: a reader read more than it was asked"), ("null view", "a view of null bytes has a length"), ("outlived", OUTLIVED), + ("lent ledger", "api_Ledger_published: a handle is borrowed exclusively"), ] { let output = Command::new(&exe).arg(case).output().unwrap(); failed(&output, &format!("C++{standard} {case}")); diff --git a/ffi/tests/miri/api.rs b/ffi/tests/miri/api.rs index 1d9bfebc3..7a16ffa0d 100644 --- a/ffi/tests/miri/api.rs +++ b/ffi/tests/miri/api.rs @@ -135,6 +135,45 @@ fn close_while_reserved() { } } +/// A draft the ledger's `edit` lends holds the ledger's exclusive borrow until it drops: +/// through a commit that moves it out, past a free of the ledger, and shared by a receipt's +/// clone, which the last copy gives back. +#[test] +fn exclusive_lend() { + unsafe { + let null = std::ptr::null_mut(); + let mut err = std::mem::MaybeUninit::::uninit(); + let mut draft = std::ptr::null(); + let ledger = api_Ledger_new(); + assert!(api_Ledger_edit(ledger, &mut draft, err.as_mut_ptr(), null)); + api_Draft_write(draft, view("first"), null); + let mut status = 0; + api_Ledger_published(ledger, &mut status); + assert_eq!(status, rt::Status::Exclusive as i32); + assert_eq!(api_Draft_commit(draft, null), 1); + api_Draft_free(draft); + assert_eq!(api_Ledger_published(ledger, null), 1); + assert!(api_Ledger_edit(ledger, &mut draft, err.as_mut_ptr(), null)); + api_Ledger_free(ledger); + api_Draft_write(draft, view("second"), null); + assert_eq!(api_Draft_lines(draft, null), 2); + assert_eq!(api_Draft_commit(draft, null), 2); + api_Draft_free(draft); + let ledger = api_Ledger_new(); + let receipt = api_Ledger_receipt(ledger, null); + let copy = api_Receipt_clone(receipt, null); + api_Receipt_free(receipt); + api_Ledger_seal(ledger, &mut status); + assert_eq!(status, rt::Status::Borrowed as i32); + assert_eq!(api_Receipt_count(copy, null), 0); + api_Receipt_free(copy); + status = 0; + api_Ledger_seal(ledger, &mut status); + assert_eq!(status, 0); + api_Ledger_free(ledger); + } +} + #[test] fn buffers() { unsafe { diff --git a/quest/m1/exclusive-lend.md b/quest/m1/exclusive-lend.md deleted file mode 100644 index d0b511c13..000000000 --- a/quest/m1/exclusive-lend.md +++ /dev/null @@ -1,36 +0,0 @@ -# [L] Export what a mutable method returns borrowing its receiver - -## Goal - -[rust2-ffi](/ffi/README.md) exports a method taking `&mut self` that returns an object -borrowing its receiver, such as moq-mux's `catalog::Producer::modify(&mut self) -> -Result>`, in every language. The census then no longer lists `catalog::Guard` -under what C can never hold, and moq's switch can drop the three `modify` calls in -moq-ffi's hand-written wrapper (`rs/moq-ffi/src/media.rs`). Adding exports breaks no generated -API, so this does not hold [moq's pin](/quest/m1/ffi-export/ship.md). - -## Plan - -Decided with the maintainer on 2026-11-16, picking -[kixel-ai/rust2#844](https://github.com/kixel-ai/rust2/pull/844) to merge: ✅ an exclusive -lend of the receiver, held until the returned object closes. Rejected: leaving `Guard` out. - -- Today a `&self` method's returned borrowing object is a lent handle that holds its - receiver and checks it on each use. The `&mut self` case takes the receiver's exclusive - borrow for the lent handle's whole life, as a call borrowing it as `&mut` does for one - call: any other use of the receiver while it is open fails `_STATUS_BORROWED`, - and closing the lent handle, or its consuming method such as `Guard::commit(self)`, gives - the borrow back. The receiver's `_free` while lent leaves the drop to the lent handle's - close, as a `&self` lend does. -- `Guard` is only useful through `Deref>` and `DerefMut`: moq-ffi calls - `guard.set_section(..)` and `guard.video.set_properties(..)`, so the exporter must reach - the target too. Recommended: a type with `Deref` gets its target's `&self` methods and - public fields on its own handle, and with `DerefMut` its `&mut self` methods and field - setters, each calling through `deref` or `deref_mut`, as Rust's auto-deref does. That - keeps `Guard`'s `updated` flag exact, since only `deref_mut` sets it. Rejected: a getter - returning the target cloned and a setter writing it back, which calls `deref_mut` on - every write and leaves `video.set_properties` unreachable on a copy. -- Prove it with the api fixture: an object whose `&mut self` method returns a guard - borrowing it, with a `Deref`, a `DerefMut`, and a consuming method, used in every - language and compared with native Rust in the transcript, plus a use of the receiver - while the guard is open, which fails. diff --git a/quest/m1/ffi-refusals/README.md b/quest/m1/ffi-refusals/README.md index 7bc6c8ef3..a5702cf1b 100644 --- a/quest/m1/ffi-refusals/README.md +++ b/quest/m1/ffi-refusals/README.md @@ -83,9 +83,9 @@ Decided with the maintainer on 2026-11-12, in the quest audit: `SocketAddr` is, and `server::Listener::accept_with` as its future need not be `Send`); `just ffi census` fails on an exclude that names what exports. The bump is then only the bump. Of the types refused for not being `Send`, `clock::Entered` - and `clock::Rng` export since [#844](https://github.com/kixel-ai/rust2/pull/844), and `catalog::Guard` is left out, as - `Producer::modify` returns it borrowing its receiver mutably, which no handle may hold - until [an exclusive lend](/quest/m1/exclusive-lend.md) exports it. + and `clock::Rng` export since [#844](https://github.com/kixel-ai/rust2/pull/844), and `catalog::Guard` since + [#848](https://github.com/kixel-ai/rust2/pull/848), whose handle holds the exclusive lend + of the receiver `Producer::modify` borrows mutably. - ✅ The closing work is a child, [no config](/quest/m1/ffi-refusals/no-config.md), as [the exporter epic's](/quest/m1/ffi-export/ship.md) is: an epic's `Required` would hold back every child. diff --git a/quest/m1/ffi-refusals/moq-pin.md b/quest/m1/ffi-refusals/moq-pin.md index 0e3ad60c4..8cfd493ef 100644 --- a/quest/m1/ffi-refusals/moq-pin.md +++ b/quest/m1/ffi-refusals/moq-pin.md @@ -31,6 +31,9 @@ At `ffcb7cd9`, `container::Producer::modify` returns moq-mux's `quic::driver` re-exports moq-quic's `stream::Id` but not the `Side` its `new` and `initiator` take (2). Both are moq's to fix; the stand-in's narrowing to moq-tokio's session side also drops `quic::driver`. +Once `Guard` is reachable, `container::Producer::modify` exports as an exclusive lend, as +`catalog::Producer::modify` does since [#848](https://github.com/kixel-ai/rust2/pull/848), so +the bump drops its excludes from `ffi/moq/ffi.toml`. Decided with the maintainer on 2026-11-07, in the quest audit: one pin bump for both, since each is an XS bump of the same pin line. Rejected: one bump per moq quest. Superseded on diff --git a/quest/m1/ffi-refusals/no-config.md b/quest/m1/ffi-refusals/no-config.md index 4ae566670..136a6acec 100644 --- a/quest/m1/ffi-refusals/no-config.md +++ b/quest/m1/ffi-refusals/no-config.md @@ -21,6 +21,12 @@ already rejects; and "exclude it in the config" in `ffi/src/driver.rs`'s refusal 2026-11-04, and no exclude stands in for a rule. This is its last child, split out by the 2026-11-12 audit so the epic needs no `Required` of its own. +Since [#848](https://github.com/kixel-ai/rust2/pull/848) exports an exclusive lend, rustls's +`ClientConfig::dangerous` returns a held `DangerousClientConfig`, whose `pub cfg: &'a mut +ClientConfig` field `ffi/moq/ffi.toml` excludes: no rule yet exports an object's `pub` field +holding a reference, which would need its own rule, such as a getter through the reference +and no setter. + One deletion needs no clean census and may land in any sibling's PR first: `go/bench/ffi.toml` with the `--config` in `go/justfile`'s bench recipe.