Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
19 changes: 11 additions & 8 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,14 +112,15 @@ public path names, or an error taken by value, is held by value as an opaque han
| `bool`, integers but 128-bit, floats, `char` | `bool`, `<stdint.h>` types, `float`, `double`, a `uint32_t` code point |
| `u128` | `<prefix>_u128`: its low and high 64 bits |
| `NonZero<T>` of an integer but 128-bit | `T`, in every binding too; a zero passed in aborts, and `Option<NonZero<T>>` is `T`'s option |
| `[u8; N]` | `<prefix>_array_u8_<N>`: a struct of its `N` bytes, `items`, copied across; an empty one, or one of any other element, is refused |
| `[u8; N]` | `<prefix>_array_u8_<N>`: a struct of its `N` bytes, `items`, copied across; an empty one is refused |
| `[T; N]` of any other `T`, returned or a constant's value | `Vec<T>` of its `N` items; taken, it is refused |
| `&str`, `String`, `&[u8]`, `Vec<u8>`, `bytes::Bytes` | `<prefix>_buf`: an owned buffer returned; passed in, a view, or a buffer Rust returned, which Rust takes back without a copy unless it sits behind a pointer or in an array; `<prefix>_buf_clone` shares one the caller keeps, which a `Vec<u8>`, `String`, or `PathBuf` parameter then copies, since only a sole owner's allocation becomes a `Vec` |
| `&Path`, `PathBuf` | `<prefix>_buf` of the path's bytes as the OS holds them on Unix, which need not be UTF-8, else UTF-8 |
| `Duration` | `<prefix>_duration` |
| `SocketAddr`, `SocketAddrV4`, `SocketAddrV6` | `<prefix>_socket_addr`: its IP's bytes, port, and whether it is IPv6; one of the other family passed to `V4` or `V6` aborts |
| `url::Url` | an object `<prefix>_Url`, made by `<prefix>_Url_parse`, which fails with the parse error's message, and printed by `_to_string` |
| `Arc<T>` of another crate's `Send` and `Sync` type that no other rule maps, such as `Arc<rustls::ServerConfig>` | an opaque object named by `T`'s crate and name, such as `<prefix>_rustls_ServerConfig`, with `_clone` and `_free` and none of `T`'s API: it only passes back to Rust |
| another crate's `Send` and `Sync` type taken or returned by value or lent, with no type parameters, that no other rule maps, that is no iterator or future, and that is not reached by its public path, such as one only a `#[doc(hidden)]` module names | an opaque object named as the `Arc` form is, with `_free` and none of `T`'s API, holding the value: Rust takes it back by value, or borrows it; a type also named behind an `Arc` is that form, and refused by value |
| `Arc<T>` of another crate's `Send` and `Sync` type that no other rule maps, such as `Arc<rustls::ServerConfig>`, or `Arc<dyn Trait>` and `&'static dyn Trait` of another crate's trait without generic arguments, whose auto traits are `Send` and `Sync` but those the trait implies, borrowing nothing C lends, as rustls's `Arc<dyn ResolvesServerCert>` | an opaque object named by `T`'s crate and name, such as `<prefix>_rustls_ServerConfig`, with `_clone` and `_free` and none of `T`'s API: it only passes back to Rust |
| another crate's `Send` and `Sync` type taken or returned by value or lent, with no type parameters, that no other rule maps, that is no iterator or future, and that is not reached by its public path, such as one only a `#[doc(hidden)]` module names, or a standard library type no other rule maps, such as `io::Error`, named by its full path, `<prefix>_std_io_Error` | an opaque object named as the `Arc` form is, with `_free` and none of `T`'s API, holding the value: Rust takes it back by value, or borrows it; a type also named behind an `Arc` is that form, and refused by value |
| `std::time::Instant` | an object `<prefix>_Instant`, which only Rust makes, copied into each call that takes it and compared by `_eq`, with none of its methods |
| `tracing::Level` | `<prefix>_Level`: a C enum of its five levels, `TRACE` to `ERROR` |
| `tracing::level_filters::LevelFilter` | `Option<tracing::Level>`, whose `None` is `OFF` |
Expand All @@ -139,6 +140,7 @@ public path names, or an error taken by value, is held by value as an opaque han
| `impl Into<X>`, where `X` does not map | what a `From` implementation into `X` takes: a source parameter by its bounds as above, so `impl<B: Into<Bytes>> From<B> for Timed<Bytes>` takes `Bytes`, and by each `Into<Y>` whose `Y` does not map, what converts into `Y` in turn, each `Y` once and refusing a chain longer than the crate's recursion limit; any other source as it is, so `impl<'a, V> From<&'a V> for Timed<&'a V>` takes `&V`. Two sources C passes as one buffer, such as `String` and `Vec<u8>`, are refused, unless they are forms of one value, as `&str` and `String` are |
| `impl IntoIterator<Item = X>`, where `X` is no type parameter | `Vec<X>`, or `&[Y]` where `X` is `&Y` |
| `impl io::Read`, not bounded by `Seek` | `&[u8]` |
| `impl Iterator<Item = X>` taken | `Vec<X>`, whose items Rust iterates; for `X` of `&str` or `&[u8]`, an array of buffers C lends for the call; an iterator of other references, or one a future or a callback takes, is refused |
| another type parameter | `serde_json::Value` for a serde `Serialize` or `Deserialize` bound, else the first of `String`, `Bytes`, and `Vec<u8>` meeting its bounds, or a foreign implementation of its one exported trait; else an instance of the function at each type the exports implement a trait bounding it for, through a blanket impl at each type implementing what the impl requires, as `&X` where that meets its bounds too and no bound, its own or one a supertrait implies, makes it outlive the call, so C keeps its handle, and, as an argument of a generic type, at each argument of an instance that meets its bounds and makes each generic type the signature names an instance |
| a const parameter of a function | an instance of the function at each value an instance of a generic type the signature passes it to has there, where each generic type the signature then names is an instance |
| a const argument | a `bool` or an integer below 128 bits; any other is refused |
Expand All @@ -158,19 +160,20 @@ A record or enum holds only values and `Copy` handles: one with a field that doe
or that holds itself, is an object instead, and the census lists it. A borrowed return is
returned as a clone, so it must be `Clone`, and a handle in it is a new handle to the
clone, but for an object a `&self` method of an object returns borrowed from its receiver
alone, or an object's `pub` field holds: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
alone, or an object's `pub` field holds, bare or as an `Option`'s `Some`: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
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`, 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. 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
slice, is in and out, and not inside an `Option`, a callback, or a future, nor borrowed
by what the call returns; a `&mut` of another crate's `Arc` is refused. Only a bare
returned `&Object` is lent, never one inside what a call returns nor its error. What C could never hold, an
object no export C can call returns or lends to a closure, a generic type no export
instantiates, and whatever takes one, is left out and listed in the census. Everything
instantiates, a type parameter bounded by another crate's trait no type C holds implements,
and whatever takes one, is left out and listed in the census. Everything
else is refused, and the census counts why.

## Targets
Expand Down Expand Up @@ -283,8 +286,8 @@ where it was while its file is unchanged.
shared and aborts, naming the function, once it was since borrowed exclusively, moved
out, or freed, which Rust's borrow checker would refuse. Borrowing a lent handle
exclusively aborts too, as Rust lent it shared.
- **Interned strings**: a `&str` a function needs for `'static`, as `Path::from_static`
does, is leaked once per distinct content and reused for every later equal one, so a
- **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.
- **Arrays** of a `Vec` are a pointer, a length, and an owner, as a buffer is: passed
in, Rust copies each element out of C's array, or for a slice of a fixed-width integer
Expand Down
33 changes: 33 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -678,6 +678,33 @@ fn main() {
String::from_utf8_lossy(&api::cert_der(cert)),
api::chain_len(chain)
);
// Another crate's trait objects: an `Arc`, taken back, and `&'static` ones, held by value.
let resolver = api::resolver("r1");
println!("resolver {}", api::resolved(resolver));
let mut codecs = api::Codecs::new();
println!("codecs {}", codecs.ids());
let mut list = codecs.list.clone();
list.reverse();
codecs.list = list;
println!("codecs reversed {}", codecs.ids());
// A standard library value no type maps, in a handle.
let failure = api::failure("boom");
println!(
"failure {} {}",
api::failure_message(&failure),
api::failure_kind(failure)
);
// Iterators, passed as the arrays of their items.
println!("sum_all {}", api::sum_all(vec![1u32, 2, 3].into_iter()));
println!("weigh_all {}", api::weigh_all(vec![Counter::new("w", 3)].into_iter()));
println!("offered_len {}", api::offered_len([&b"h3"[..], b"moq-00"].into_iter()));
println!("join_words {}", api::join_words(["a", "b", "c"]));
// Bytes that must be `'static`, interned.
println!("der {}", String::from_utf8_lossy(&api::Der::from_slice(b"der").bytes()));
println!(
"der again {}",
String::from_utf8_lossy(&api::Der::from_slice(b"der").bytes())
);
let session = api::resume("h3", 60).unwrap();
println!("resume {} {}", session.alpn(), session.lifetime().seconds);
println!("resume err {}", api::resume("", 60).err().unwrap());
Expand All @@ -689,6 +716,11 @@ fn main() {
println!("cleared {}", meters.first().count());
meters.last.add(4);
println!("field lent {}", meters.last.add(1));
// An optional field that is not Clone, lent as `Some` of a handle.
println!("spare {}", meters.spare.is_some());
meters.spare = Some(api::Meter::default());
meters.spare.as_ref().unwrap().add(5);
println!("spare lent {}", meters.spare.as_ref().unwrap().add(1));
let tallies = api::Tallies::new();
tallies.first().bump();
println!("tallied {}", tallies.first().bump());
Expand Down Expand Up @@ -799,6 +831,7 @@ fn main() {

// Slices, passed in and returned as clones, and the socket address of each family.
println!("shapes {:?} greetings {:?}", api::Shape::ALL, api::GREETINGS);
println!("both {:?} primes {:?}", api::Shape::BOTH, api::PRIMES);
let trail = api::Trail::new(
&[api::Point { x: 1, y: 2 }, api::Point { x: 3, y: 4 }],
&["a".to_string(), "b".to_string()],
Expand Down
137 changes: 136 additions & 1 deletion ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -602,11 +602,13 @@ impl Meter {
}
}

/// Owns a meter it lends, and one in a field, lent as the method's is.
/// Owns a meter it lends, and one in a field, lent as the method's is, and an optional one,
/// lent as `Some` of it.
#[derive(Default)]
pub struct Meters {
first: Meter,
pub last: Meter,
pub spare: Option<Meter>,
}

impl Meters {
Expand Down Expand Up @@ -2710,6 +2712,133 @@ pub fn blame(err: tls::held::Invalid) -> String {
err.to_string()
}

/// Another crate's trait object behind an `Arc`: an opaque handle, taken back as the `Arc`.
pub fn resolver(name: &str) -> Arc<dyn tls::held::Resolver> {
Arc::new(tls::held::Named(name.to_string()))
}

/// The name a resolver resolves, from its handle.
pub fn resolved(resolver: Arc<dyn tls::held::Resolver>) -> String {
resolver.name()
}

/// A resolver as a tuple struct's field, whose accessors each binding names as its `_0`.
pub struct Resolving(pub Arc<dyn tls::held::Resolver>);

impl Resolving {
pub fn new(name: &str) -> Self {
Self(resolver(name))
}
}

/// Codecs, each another crate's `&'static dyn Codec`, held by value in an opaque handle.
pub struct Codecs {
pub list: Vec<&'static dyn tls::held::Codec>,
seen: u8,
}

impl Codecs {
pub fn new() -> Self {
Self {
list: vec![&tls::held::ZLIB, &tls::held::BROTLI],
seen: 0,
}
}

/// The ids of the listed codecs, in order, as one number of a digit each.
pub fn ids(&mut self) -> u32 {
self.seen += 1;
self.list.iter().fold(0, |n, codec| n * 10 + u32::from(codec.id()))
}
}

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

/// A standard library value no exported type maps: an opaque handle held by value.
pub fn failure(message: &str) -> std::io::Error {
std::io::Error::other(message.to_string())
}

/// The failure's message, borrowed from its handle.
pub fn failure_message(error: &std::io::Error) -> String {
error.to_string()
}

/// The failure's kind, taken back by value.
pub fn failure_kind(error: std::io::Error) -> String {
format!("{:?}", error.kind())
}

/// The sum of what an iterator yields, which C passes as the array of its items.
pub fn sum_all(items: impl Iterator<Item = u32>) -> u32 {
items.sum()
}

/// What a counter weighs, owned or borrowed, which C cannot implement for its constant.
pub trait Weigh {
const SCALE: u64;
fn weight(&self) -> u64;
}

impl Weigh for Counter {
const SCALE: u64 = 1;
fn weight(&self) -> u64 {
self.get() * Self::SCALE
}
}

impl Weigh for &Counter {
const SCALE: u64 = 10;
fn weight(&self) -> u64 {
self.get() * Self::SCALE
}
}

/// The weights of an iterator's items summed: C passes the array of its counters, each
/// moved in, so `&Counter`'s weight is not taken.
pub fn weigh_all<I: Iterator<Item = W>, W: Weigh>(items: I) -> u64 {
items.map(|item| item.weight()).sum()
}

/// The total length of borrowed byte strings, as moq-tokio's TLS acceptor reads offered ALPNs.
pub fn offered_len<'a>(alpns: impl Iterator<Item = &'a [u8]>) -> usize {
alpns.map(<[u8]>::len).sum()
}

/// Words joined with spaces: an `IntoIterator` of what converts to `&str`, as moq-tokio's
/// WebSocket listener takes its protocols.
pub fn join_words<I, S>(words: I) -> String
where
I: IntoIterator<Item = S>,
S: AsRef<str>,
{
let words: Vec<String> = words.into_iter().map(|w| w.as_ref().to_string()).collect();
words.join(" ")
}

/// Bytes that must outlive every handle, as rustls's `CertificateDer::from_slice` borrows
/// its DER: the glue interns them.
pub struct Der<'a>(&'a [u8]);

impl<'a> Der<'a> {
pub fn from_slice(bytes: &'a [u8]) -> Self {
Self(bytes)
}

pub fn bytes(&self) -> Vec<u8> {
self.0.to_vec()
}
}

/// Reads a stream no type C holds implements: left out, as C never holds one.
pub fn pump<T: tls::held::Stream>(mut stream: T) -> u8 {
stream.read()
}

/// A session of `alpn` lasting `seconds`, from a crate the facade re-exports nothing from:
/// its type exports by its path there, and its error crosses as its message.
pub fn resume(alpn: &str, seconds: u32) -> Result<tls::Session, tls::Error> {
Expand Down Expand Up @@ -3064,11 +3193,17 @@ impl Site {
impl Shape {
/// Every shape, as a constant slice.
pub const ALL: &'static [Shape] = &[Shape::Circle, Shape::Square];

/// Every shape, as a constant array, returned as the array of its elements.
pub const BOTH: [Shape; 2] = [Shape::Circle, Shape::Square];
}

/// Greetings, as a constant slice of references, each returned as a clone.
pub const GREETINGS: &[&str] = &["hi", "hello"];

/// Primes, as a constant array of a block's element.
pub const PRIMES: [u32; 3] = [2, 3, 5];

/// A trail through points, each labeled: slices passed in and lent back out.
pub struct Trail {
points: Vec<Point>,
Expand Down
Loading