Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
269ab0c
chore(quest): claim quest/m1/exclusive-lend.md
kixelated Nov 16, 2026
7846513
wip: exclusive lend of a &mut self method's borrowing return, and Der…
kixelated Nov 16, 2026
dc64ba8
wip: the exclusive lend in every language's api test
kixelated Nov 16, 2026
ebca631
wip: reject a shared view, lock ties, README for exclusive lends
kixelated Nov 16, 2026
80a3bc0
wip: exercise catalog modify in moq, retire the quest
kixelated Nov 16, 2026
f826347
Merge remote-tracking branch 'origin/main' into quest/m1/exclusive-lend
kixelated Nov 16, 2026
399c14f
wip: the exclusive lend in the web test
kixelated Nov 16, 2026
cdfed5c
test(ffi): the exclusive lend under Miri
kixelated Nov 16, 2026
f055917
fix(ffi): bounds and field accessors tie a lend, refuse a Copy one, s…
kixelated Nov 16, 2026
819a0c3
fix(ffi): any bound naming a lifetime ties it, and a 'static field do…
kixelated Nov 16, 2026
c55b8f2
fix(ffi): a bound ties a lend only when proving it constrains a lifetime
kixelated Nov 16, 2026
117bd4d
fix(ffi): a bound ties a lend only when its lifetimes fail to resolve
kixelated Nov 16, 2026
e6ac09f
fix(ffi): an instance's erased lifetime ties a lend as 'static
kixelated Nov 16, 2026
f539924
fix(ffi): an exclusive lend's traits must hold at every lifetime
kixelated Nov 16, 2026
f03348d
fix(ffi): an instance's erased lifetime is 'static in a lend's trait …
kixelated Nov 16, 2026
deba6be
fix(ffi): Deref forwarding shadows by kind and through unexported tar…
kixelated Nov 16, 2026
b0f3953
fix(ffi): a forwarded field shares its path with a method by field@
kixelated Nov 16, 2026
e9f9491
fix(ffi): a forwarded field shares its path with the object's associa…
kixelated Nov 16, 2026
6b9216d
fix(ffi): an exclusive lend's own bounds on its borrow must hold at e…
kixelated Nov 16, 2026
f9842f5
docs(ffi): member_names keeps its doc comment above it
kixelated Nov 16, 2026
1a61875
test(ffi): the transcript compares Deref forwarding with native Rust
kixelated Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<Box<dyn Future<Output = ()> + Send>>` meets, as kio's `clock::timeout` takes, or taken as `Pin<&mut F>` by a poll, as kio's `Waiter::poll_future` takes | `<prefix>_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 | `<prefix>_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<T, E>` | `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)` |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -341,6 +350,17 @@ where it was while its file is unchanged.
shared and fails with `<PREFIX>_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 `<PREFIX>_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 `<PREFIX>_STATUS_EXCLUSIVE` or `<PREFIX>_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 `<PREFIX>_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.
Expand Down
38 changes: 38 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::<u16>::wide().title(),
api::Layered::new().lines(),
marker.x,
marker.y,
api::Pad::<u8>::small().describe(),
api::Pad::<u16>::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<String> = counters.iter().map(|c| format!("{} {}", c.name(), c.get())).collect();
Expand Down
9 changes: 8 additions & 1 deletion ffi/fixtures/api/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,27 @@
# `field@` leaves out a field alone where a method takes its path, as `Retry`'s and
# `Slot<u8>`'s do, and `Retry::jitter` and `field@Retry::jitter` leave out a refused method
# and its field. `Slot<u32>` 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<u16>::lines` is. A forwarded field
# sharing its path with a method is `field@`, as `Pad<u16>`'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<u16>::lines",
"Pair<u8, api::Size>::swap",
"Queued",
"Rooted",
"Sample",
"Scoped",
"Slot<u32>::value",
"Retry::jitter",
"field@Pad<u16>::title",
"field@Retry::delay",
"field@Retry::jitter",
"field@Slot<u8>::value",
Expand Down
Loading