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
21 changes: 17 additions & 4 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,16 @@ exclude = ["track::Producer::poll_closed"]
"session::Stats" = "session_stats_snapshot"

# Another package exported into the same library, which the package builds with: its
# own `exclude` and `rename`, by paths from its crate root.
# own `exclude`, `rename`, and `instances`, by paths from its crate root.
[crates.moq-pattern]
exclude = ["Patterns::iter"]

# The instances a generic type exports at, by its path, and their C names without the
# prefix. An argument is `()`, a primitive, `String`, or an exported type by its path
# from its package's name in snake case, itself an instance if generic. Trailing
# arguments left out take their defaults.
[crates.moq-mux.instances]
"catalog::Producer<moq_mux::catalog::hang::Extra>" = "catalog_producer"
```

## Rules
Expand All @@ -57,6 +64,7 @@ export's, and adds nothing; another crate's type is refused.
| an enum whose fields map, with no `Drop` of its own | a C enum without fields, or a struct of a tag and a union |
| any other type, if `Send` | an object: an opaque handle to an `Arc`, freed with `_free` |
| a type whose only generic parameters are lifetimes, such as `Path<'a>` | an object holding its `'static` form |
| a generic type, at each instance `instances` names | that instance as any other type, with each method whose impl and own bounds it meets; any other instance is refused |
| a `pub` field of an object | a getter returning a copy |
| a `pub` trait | a callback interface: a table of C functions and their data |
| `fn` and inherent `pub` methods | functions named through their type |
Expand All @@ -72,7 +80,7 @@ export's, and adds nothing; another crate's type is refused.
| `Option<T>` | a null handle or buffer, or `<prefix>_option_<T>` |
| a `pub const` | a `#define` if a `bool` or integer, else a function returning it |
| `impl Into<X>`, `impl AsRef<X>` | `X` |
| another type parameter | the first of `String`, `Bytes`, and `Vec<u8>` meeting its bounds, or a foreign implementation of its one exported trait |
| another type parameter | the first of `String`, `Bytes`, and `Vec<u8>` meeting its bounds, a foreign implementation of its one exported trait, or, as an argument of a generic type, the one argument of a named instance that meets its bounds and makes each generic type the signature names a named instance |

A record or enum holds only values and `Copy` handles: one with a field that does not map,
or that holds itself, is an object instead, and the census lists it. A borrowed return is
Expand Down Expand Up @@ -110,7 +118,11 @@ refused, and the census counts why.
Joining loses where segments split, and every export shares the prefix, so every C
name is registered, and two items claiming one is a compile error at both spans, fixed
by a `rename`: moq-net's `session::Stats` and `Session::stats` are both
`moq_session_stats`.
`moq_session_stats`. An instance is named by `instances`, and its methods through
that name. An `exclude` of a method by the generic type's path leaves it out of every
instance, and by the instance's path (`"Producer<moq_mux::catalog::hang::Extra>::stats"`)
out of that one; a `rename` of a method by the generic type's path names it at every
instance.

## IR

Expand All @@ -127,7 +139,8 @@ the runtime the glue includes is [`runtime/rt.rs`](runtime/rt.rs).
`--census dir` exports nothing. It writes `<package>.md` for each exported package,
which counts what exports and ranks every refusal by construct and by the type it names,
lists each refused item at its span, and ends with the `exclude` list that exports the
rest. It ignores the config's `exclude`.
rest, and the refused instances to drop from `instances`. It ignores the config's
`exclude`, and reads its `instances`.

## Tests

Expand Down
34 changes: 32 additions & 2 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ use std::sync::atomic::{AtomicUsize, Ordering};
use std::task::{Context, Poll, Wake, Waker};

use api_lib::{
Channel, Counter, Event, LIMIT, Log, Logger, Message, Name, Node, Point, Registry, Shape, Size, Stamp, Tally,
Window,
Channel, Counter, Event, LIMIT, Log, Logger, Message, Name, Node, Pair, Point, Registry, Shape, Size, Stack, Stamp,
Tally, Window,
};
use bytes::Bytes;

Expand Down Expand Up @@ -198,6 +198,36 @@ fn main() {
let size = area.size();
println!("area {} {} {}", size.width, size.height, area.pixels());

let pair = Pair { left: 2u32, right: 5 };
let swapped = pair.swap();
println!(
"pair {} {} sum {} {pair:?} {}",
swapped.left,
swapped.right,
pair.sum(),
pair == swapped
);
println!("even {} {}", pair.even(), Pair { left: 7u32, right: 7 }.even());
let sized = Pair {
left: Size { width: 1, height: 2 },
right: 3u8,
};
let flipped = sized.swap();
println!("sized {} {} {flipped:?}", flipped.left, flipped.right.width);
let beside = Pair { left: 258u32, right: 9 }.beside(sized.left);
println!("beside {} {beside:?}", beside.left);
let mut stack = Stack::new();
for (i, name) in ["a", "b"].into_iter().enumerate() {
stack.push(Counter::new(name, i as u64 + 1));
}
let top = stack.pop().map(|c| c.get());
println!(
"stack {} {top:?} {} {}",
stack.depth(),
stack.pop().is_some(),
stack.pop().is_none()
);

let token = api_lib::Token::new(7);
println!("token {} dropped {}", token.id, api_lib::dropped());
drop(token);
Expand Down
13 changes: 11 additions & 2 deletions ffi/fixtures/api/ffi.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,16 @@
package = "api-fixture"
prefix = "api"
# The list's tail is not `Clone`, so its getter has no copy to return.
exclude = ["Node::next"]
# The list's tail is not `Clone`, so its getter has no copy to return, and one instance
# leaves out a method the others keep.
exclude = ["Node::next", "Pair<u8, dep_fixture::Size>::swap"]

# Generic types at the instances C uses, each with its C name: `Pair<u32>` is
# `Pair<u32, u32>`, and `swap` returns each `Pair` of a `Size` as the other.
[instances]
"Pair<u32>" = "pair"
"Pair<dep_fixture::Size, u8>" = "size_pair"
"Pair<u8, dep_fixture::Size>" = "pair_size"
"Stack<api_fixture::Counter>" = "counters"

# Exported into the same library: `grow` names its types.
[crates.dep-fixture]
Expand Down
66 changes: 66 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -484,6 +484,72 @@ pub fn describe(event: &Event) -> String {
format!("{event:?}")
}

/// Two values: a generic record, which exports at each instance the config names. Its
/// second parameter defaults to its first, as an instance may leave it.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Pair<L, R = L> {
pub left: L,
pub right: R,
}

impl<L: Copy, R: Copy> Pair<L, R> {
/// The pair swapped: another instance, unless both are of one type.
pub fn swap(&self) -> Pair<R, L> {
Pair {
left: self.right,
right: self.left,
}
}

/// Whether the sides are equal: a method of only the instances whose sides compare.
pub fn even(&self) -> bool
where
L: PartialEq<R>,
{
self.left == self.right
}
}

/// An impl of one instance, whose methods no other instance has.
impl Pair<u32> {
pub fn sum(&self) -> u32 {
self.left + self.right
}

/// The left value as a byte, beside `right`: the one instance that names the result
/// fills the type parameter, with `dep_fixture::Size`.
pub fn beside<T: Copy>(&self, right: T) -> Pair<u8, T> {
Pair {
left: self.left as u8,
right,
}
}
}

/// A stack: a generic object, at an instance of objects, whose handles move in and out.
#[derive(Debug, Default)]
pub struct Stack<T> {
items: Vec<T>,
}

impl<T> Stack<T> {
pub fn new() -> Self {
Self { items: Vec::new() }
}

pub fn push(&mut self, item: T) {
self.items.push(item);
}

pub fn pop(&mut self) -> Option<T> {
self.items.pop()
}

pub fn depth(&self) -> usize {
self.items.len()
}
}

/// An area grown by `by` on each side: another export's types, across crates.
pub fn grow(area: &dep::Area, by: u32) -> dep::Area {
let size = area.size();
Expand Down
10 changes: 9 additions & 1 deletion ffi/fixtures/reject/expected.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,18 @@ fixtures/reject/src/lib.rs:113:2: rust2-ffi: cannot export method `Text::replace
fixtures/reject/src/lib.rs:118:2: rust2-ffi: cannot export method `Text::later`: returned object that borrows `impl std::future::Future<Output = Text<'_>>`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:125:1: rust2-ffi: cannot export fn `either`: reference inside a parameter `std::option::Option<&str>`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:130:1: rust2-ffi: cannot export struct `Lease`: object no export returns; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:149:9: rust2-ffi: cannot export use `HashSet`: re-export of another crate's item `std`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:14:1: rust2-ffi: cannot export fn `map`: foreign type `std::collections::HashMap`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:158:1: rust2-ffi: cannot export fn `unnamed`: instance the config does not name `reject_fixture::Cell<u8>`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:149:1: note: `Cell` exports only at the instances the config names
fixtures/reject/src/lib.rs:163:1: rust2-ffi: cannot export fn `fill`: generic parameter of several instances `u16, u32`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:168:1: rust2-ffi: cannot export struct `Bounded`: generic type; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:168:1: rust2-ffi: instance `Bounded<String>` in the config exports nothing: `reject_fixture::Bounded` needs `std::string::String: std::marker::Copy`
fixtures/reject/src/lib.rs:171:1: rust2-ffi: cannot export instance `Holder<std::option::Option<u32>>`: type argument the config cannot spell `std::option::Option<u32>`; drop it from the config's `instances`
fixtures/reject/src/lib.rs:176:9: rust2-ffi: cannot export use `HashSet`: re-export of another crate's item `std`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:26:1: rust2-ffi: cannot export fn `borrowing`: borrowing future from a function that is not async; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option<std::boxed::Box<std::option::Option<u32>>>`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:36:1: rust2-ffi: instance `Opaque<u8>` in the config exports nothing: `reject_fixture::Opaque` takes no type arguments
fixtures/reject/src/lib.rs:40:1: rust2-ffi: cannot export fn `peek`: reference to a handle inside a value `std::boxed::Box<Opaque>`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:45:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:49:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out
Expand All @@ -28,3 +35,4 @@ fixtures/reject/src/lib.rs:92:1: rust2-ffi: cannot export fn `retext`: 'static b
fixtures/reject/src/lib.rs:92:15: note: `'a` is `'static`, as a handle outlives every call
fixtures/reject/src/lib.rs:97:1: rust2-ffi: cannot export fn `first`: borrowed return that is not Clone `Opaque`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclude it in the config to leave it out
no span: rust2-ffi: instance `Missing<u8>` in the config exports nothing: `reject_fixture::Missing` names no exported struct or enum
10 changes: 10 additions & 0 deletions ffi/fixtures/reject/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,15 @@ prefix = "reject"
# An exclusion leaves an item out, so nothing refuses it.
exclude = ["Excluded"]

# Instances that cannot export: an unmet bound, a default argument no key can spell, a
# type that is not generic, and a path that names nothing. `Cell<u16>` and `Cell<u32>` export, and nothing else of `Cell` does.
[instances]
"Bounded<String>" = "bounded"
"Cell<u16>" = "cell_u16"
"Cell<u32>" = "cell"
"Holder" = "holder"
"Missing<u8>" = "missing"
"Opaque<u8>" = "opaque_u8"

# Another export, whose `Size` claims the same C name as this one's.
[crates.dep-fixture]
27 changes: 27 additions & 0 deletions ffi/fixtures/reject/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -145,5 +145,32 @@ pub fn measure(size: dep::Size) -> dep::Area {
dep::Area::new(size)
}

/// A generic type the config names at `u32` alone.
pub struct Cell<T>(T);

impl<T> Cell<T> {
pub fn new(value: T) -> Self {
Self(value)
}
}

/// An instance the config does not name.
pub fn unnamed(cell: Cell<u8>) -> u8 {
cell.0
}

/// A type parameter both instances of `Cell` could fill.
pub fn fill<T: Copy>(value: T) -> Cell<T> {
Cell(value)
}

/// A generic type whose bound the config's instance does not meet.
pub struct Bounded<T: Copy>(pub T);

/// A generic type whose default argument is a type no instance key can spell.
pub struct Holder<T = Option<u32>> {
pub value: T,
}

/// Another crate's item that is no export, so nothing names it.
pub use std::collections::HashSet;
Loading