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
7 changes: 7 additions & 0 deletions ffi/MIGRATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Migrating

## Unreleased

- In `exclude` and `rename`, a path that a field shares with a method or constant of its
type, such as `Backoff::initial`, names only the method, as in rustdoc. Name the field
`field@Backoff::initial`: an `exclude` that left out both now needs both entries.
6 changes: 4 additions & 2 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ package = "moq-net"
# The prefix of every C name, the package's name in snake case by default.
prefix = "moq"
# Paths from the crate root left out: a module, an item, or one method or field. Each
# must name something exported. Nothing else leaves an item out.
# must name something exported. Nothing else leaves an item out. As in rustdoc, a path a
# method or constant shares with a field names the method, and `field@` the field.
exclude = ["track::Producer::poll_closed"]

# C names, without the prefix, for paths whose names the naming rule makes clash.
Expand Down Expand Up @@ -125,7 +126,8 @@ 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`. An instance is named by `instances`, and a type instance's
`moq_session_stats`. So are a field and the method of its name, as moq-tokio's
`Backoff::initial`; `field@Backoff::initial` names the field. An instance is named by `instances`, and a type instance's
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
Expand Down
11 changes: 11 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -244,4 +244,15 @@ fn main() {
println!("token {} dropped {}", token.id, api_lib::dropped());
drop(token);
println!("dropped {}", api_lib::dropped());

let retry = api_lib::Retry::new(Some(5));
let limit = retry.limit;
println!(
"retry {} {} {} {}",
u8::from(limit.is_some()),
limit.unwrap_or(0),
retry.limit(),
retry.delay()
);
println!("slot {}", api_lib::Slot::<u8>::new(200).value());
}
12 changes: 10 additions & 2 deletions ffi/fixtures/api/ffi.toml
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
package = "api-fixture"
prefix = "api"
# The list's tail is not `Clone`, so its getter has no copy to return, one instance leaves
# out a method the others keep, and `Seed` is generic, so no callback implements it.
exclude = ["Node::next", "Pair<u8, dep_fixture::Size>::swap", "Seed"]
# out a method the others keep, `Seed` is generic, so no callback implements it, and
# `field@` leaves out a field alone where a method takes its path, as `Retry`'s and
# `Slot<u8>`'s do. `Slot<u32>` has no such method, so its path alone names its field.
exclude = ["Node::next", "Pair<u8, dep_fixture::Size>::swap", "Seed", "Slot<u32>::value", "field@Retry::delay", "field@Slot<u8>::value"]

# The field `Retry::limit`, whose name its method takes.
[rename]
"field@Retry::limit" = "retry_limit_setting"

# 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.
Expand All @@ -11,6 +17,8 @@ exclude = ["Node::next", "Pair<u8, dep_fixture::Size>::swap", "Seed"]
"Pair<dep_fixture::Size, u8>" = "size_pair"
"Pair<u8, dep_fixture::Size>" = "pair_size"
"Stack<api_fixture::Counter>" = "counters"
"Slot<u8>" = "byte_slot"
"Slot<u32>" = "slot"
# Generic functions and methods likewise, each type parameter by name, an `impl Trait` one
# by its argument's, in any order.
"Counter::seeded(from: api_fixture::Point)" = "counter_seeded_point"
Expand Down
42 changes: 42 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,28 @@ impl Drop for Token {
}
}

/// Retry settings: each field is unset until C sets it, and the method of its name
/// resolves it, as Rust's accessors do. Not exhaustive, so an object with getters.
#[non_exhaustive]
pub struct Retry {
pub limit: Option<u32>,
pub delay: Option<u32>,
}

impl Retry {
pub fn new(limit: Option<u32>) -> Self {
Self { limit, delay: None }
}

pub fn limit(&self) -> u32 {
self.limit.unwrap_or(3)
}

pub fn delay(&self) -> u32 {
self.delay.unwrap_or(100)
}
}

/// How many tokens have dropped.
pub fn dropped() -> u32 {
DROPPED.load(std::sync::atomic::Ordering::Relaxed)
Expand Down Expand Up @@ -600,3 +622,23 @@ pub fn grow(area: &dep::Area, by: u32) -> dep::Area {
height: size.height + by,
})
}

/// A slot whose method `value` only `Slot<u8>` has, so its path alone names `Slot<u32>`'s
/// field and `Slot<u8>`'s method. Not exhaustive, so an object with getters.
#[non_exhaustive]
pub struct Slot<T> {
pub value: T,
}

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

impl Slot<u8> {
/// The value widened and doubled, apart from the field.
pub fn value(&self) -> u16 {
u16::from(self.value) * 2
}
}
3 changes: 3 additions & 0 deletions ffi/fixtures/reject/expected.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ fixtures/reject/src/lib.rs:180:1: rust2-ffi: instance `copied(U: u8)` in the con
fixtures/reject/src/lib.rs:186:2: rust2-ffi: instance `Bounded::get(U: u64)` in the config exports nothing: nothing exported reaches it
fixtures/reject/src/lib.rs:192:1: rust2-ffi: cannot export fn `lend`: Waker outside a parameter taken by value; 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:207:2: rust2-ffi: fn `reject_fixture::Limit::max` and field `reject_fixture::Limit::max` are both `reject_limit_max` in C
fixtures/reject/src/lib.rs:199:2: note: field `reject_fixture::Limit::max` is here
fixtures/reject/src/lib.rs: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
Expand All @@ -43,3 +45,4 @@ fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclu
fixtures/reject/src/lib.rs:9:1: rust2-ffi: instance `pair(T: u8)` in the config exports nothing: it takes no type parameters
no span: rust2-ffi: instance `Missing<u8>` in the config exports nothing: `reject_fixture::Missing` names no exported struct or enum
no span: rust2-ffi: instance `missing(T: u8)` in the config exports nothing: `missing` names no exported function or method
no span: rust2-ffi: rename `field@Limit::min` in the config names nothing exported
4 changes: 4 additions & 0 deletions ffi/fixtures/reject/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ prefix = "reject"
# An exclusion leaves an item out, so nothing refuses it.
exclude = ["Excluded"]

# A field that is none: `min` names nothing of `Limit`.
[rename]
"field@Limit::min" = "limit_min"

# 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]
Expand Down
16 changes: 16 additions & 0 deletions ffi/fixtures/reject/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -192,3 +192,19 @@ impl<T: Copy> Bounded<T> {
pub fn lend(waker: &std::task::Waker) {
waker.wake_by_ref();
}

/// A field and a method of one name, which claim one C name until `field@` renames one.
#[non_exhaustive]
pub struct Limit {
pub max: u32,
}

impl Limit {
pub fn new(max: u32) -> Self {
Self { max }
}

pub fn max(&self) -> u32 {
self.max.max(1)
}
}
11 changes: 6 additions & 5 deletions ffi/moq/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -135,11 +135,6 @@ exclude = [
[crates.moq-tokio]
exclude = [
"Addrs",
# Not refused: each names both a field and a method, whose getters `rename` cannot
# tell apart, so both are left out.
"Backoff::initial",
"Backoff::max",
"Backoff::timeout",
"Client::connect",
"Listener::accept_health",
"Listener::local_addr",
Expand Down Expand Up @@ -179,6 +174,7 @@ exclude = [
"crypto::install_default",
"crypto::provider",
"failover::Attempt",
"field@Log::level",
"listen::Config::preferred_v4",
"listen::Config::preferred_v6",
"listen::Config::version",
Expand Down Expand Up @@ -325,6 +321,11 @@ exclude = [
"connect::Error" = "connect_target_error"
# The rule makes both this type and `Connection::monitor` `moq_connection_monitor`.
"connection::Monitor" = "monitor"
# The rule makes each of these fields and the method of its name, which resolves its
# default, `moq_backoff_<field>`.
"field@Backoff::initial" = "backoff_initial_setting"
"field@Backoff::max" = "backoff_max_setting"
"field@Backoff::timeout" = "backoff_timeout_setting"

[crates.hang]
exclude = [
Expand Down
7 changes: 7 additions & 0 deletions ffi/moq/moq.c
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,13 @@ int main(void) {
CHECK(moq_connect_error_is_auth(&unauthorized));
CHECK(is(moq_connect_error_to_string(&unauthorized), "unauthorized"));

/* A backoff's fields are settings left unset, and the methods of their names resolve them. */
moq_backoff *backoff = moq_backoff_default();
CHECK(moq_backoff_initial_setting(backoff) == NULL);
moq_duration initial = moq_backoff_initial(backoff);
CHECK(initial.secs == 1 && initial.nanos == 0);
moq_backoff_free(backoff);

if (failures == 0) {
printf("ok\n");
}
Expand Down
24 changes: 20 additions & 4 deletions ffi/src/abi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ use std::collections::{BTreeMap, HashMap};

use rustc_span::Span;

use crate::ir::{Api, Dyn, Function, Int, Receiver, Type};
use crate::ir::{Access, Api, Dyn, Function, Int, Receiver, Type};

/// A C name claimed twice: the name, then what claimed it first and second.
pub type Clash = (String, (String, Span), (String, Span));
Expand Down Expand Up @@ -161,16 +161,29 @@ impl<'a> Abi<'a> {
}

/// A function's C name: an instance's as the config names it, else a method's through
/// its type's, unless renamed itself.
/// its type's, unless renamed itself. A field is renamed by `field@` and its path, or
/// by its path unless a method or constant takes it.
fn function_name(&self, function: &Function, owner: Option<&Ty>) -> String {
if let Some(instance) = &function.instance {
return format!("{}_{}", self.prefix, instance.name);
}
let path = function.path.join("::");
let shared = match function.access {
Access::Field { shared } => {
let key = format!("field@{path}");
if let Some(renamed) = self.rename.get(&key) {
self.renamed.borrow_mut().insert(key);
return format!("{}_{renamed}", self.prefix);
}
shared
}
_ => false,
};
let owner = match owner {
Some(Ty::Struct(name) | Ty::Enum(name) | Ty::Handle { name, .. }) => name,
_ => return self.name(&function.path),
};
match self.rename.contains_key(&function.path.join("::")) {
match !shared && self.rename.contains_key(&path) {
true => self.name(&function.path),
false => format!("{owner}_{}", snake(function.name())),
}
Expand Down Expand Up @@ -455,7 +468,10 @@ impl<'a> Abi<'a> {
functions.extend(api.functions.iter().map(|f| (f, None)));
for (function, owner) in functions {
let export = self.export(function, owner.as_ref());
let what = format!("fn `{}`", function.path.join("::"));
let what = match function.access {
Access::Field { .. } => format!("field `{}`", function.path.join("::")),
_ => format!("fn `{}`", function.path.join("::")),
};
self.claim(export.call.name.clone(), what.clone(), function.span);
if let Some((handle, poll, free)) = &export.future {
self.claim(handle.clone(), what.clone(), function.span);
Expand Down
21 changes: 18 additions & 3 deletions ffi/src/collect.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1173,13 +1173,28 @@ impl<'tcx> Collector<'tcx> {
fn getters(&mut self, site: &Site<'tcx>) -> Vec<Function> {
let tcx = self.tcx;
let mut getters = Vec::new();
let self_ty = self.site_ty(site);
for field in &tcx.adt_def(site.key.def_id).non_enum_variant().fields {
if !field.vis.is_public() {
continue;
}
let name = field.name.to_string();
let shown = [&site.shown[..], std::slice::from_ref(&name)].concat();
if self.exclude(&shown) {
// As in rustdoc, `field@` and the path name the field, and the path alone does
// unless a method or constant of this instance takes the name, which it then names.
let shared = (tcx.inherent_impls(site.key.def_id).iter())
.filter_map(|&imp| Some((imp, self.impl_args(imp, self_ty)?)))
.flat_map(|(imp, parent)| {
(tcx.associated_items(imp).filter_by_name_unhygienic(field.name)).map(move |item| (item, parent))
})
.any(|(item, parent)| {
matches!(item.kind, ty::AssocKind::Fn { .. } | ty::AssocKind::Const { .. })
&& tcx.visibility(item.def_id).is_public()
Comment thread
kixelated marked this conversation as resolved.
Resolved
&& self.applies(item.def_id, parent)
});
let mut key = shown.clone();
key[1].insert_str(0, "field@");
if self.exclude(&key) || (!shared && self.exclude(&shown)) {
continue;
}
let span = tcx.def_span(field.did);
Expand All @@ -1196,10 +1211,10 @@ impl<'tcx> Collector<'tcx> {
err: None,
future: false,
eager: false,
access: Access::Field,
access: Access::Field { shared },
instance: None,
}),
Err(why) => self.refuse(&shown, "field", span, vec![why], false),
Err(why) => self.refuse(if shared { &key } else { &shown }, "field", span, vec![why], false),
}
}
getters
Expand Down
6 changes: 4 additions & 2 deletions ffi/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,14 @@ pub struct Config {
/// The prefix of every C name, the package's name in snake case by default.
pub prefix: Option<String>,
/// Paths from the crate root left out of the export: a module, an item, or one
/// method (`track::Producer::poll_closed`). Each must name something exported.
/// method or field (`track::Producer::poll_closed`). Each must name something
/// exported. As in rustdoc, a path a method or constant shares with a field names the
/// method, and `field@` before it names the field.
Comment thread
kixelated marked this conversation as resolved.
Resolved
#[serde(default)]
pub exclude: Vec<String>,
/// C names, without the prefix, for paths from the crate root whose names the rule
/// makes clash: `"session::Stats" = "session_stats_snapshot"`. A type's methods are
/// named through its new name.
/// named through its new name. A field is named by its path as `exclude` names it.
#[serde(default)]
pub rename: BTreeMap<String, String>,
/// Generic types exported at instances, each with its C name, without the prefix:
Expand Down
22 changes: 18 additions & 4 deletions ffi/src/driver.rs
Original file line number Diff line number Diff line change
Expand Up @@ -96,18 +96,21 @@ impl Callbacks for Export {
return Compilation::Stop;
};
let collected = collect::collect(tcx, &crates);
// Each rename, by the Rust path it names, which starts with its crate's name.
// Each rename, by the Rust path it names, which starts with its crate's name, after
// a field's `field@`.
let mut renames = BTreeMap::new();
for (report, package) in collected.reports.iter().zip(&self.crates) {
for (path, name) in self.items(&package.name).1 {
renames.insert(format!("{}::{path}", report.krate), name.clone());
let (field, path) = field(path);
renames.insert(format!("{field}{}::{path}", report.krate), name.clone());
}
}
let abi = Abi::new(&collected.api, &self.config.prefix(), &renames, &collected.instances);
for key in abi.unused_renames() {
let (field, key) = field(key);
let (krate, path) = key.split_once("::").expect("a rename starts with its crate");
tcx.dcx().err(format!(
"rust2-ffi: rename `{path}` in {} names nothing exported",
"rust2-ffi: rename `{field}{path}` in {} names nothing exported",
self.table(&collected, krate)
));
}
Expand Down Expand Up @@ -177,7 +180,10 @@ impl Callbacks for Export {
format!("rust2-ffi: {second} and {first} are both `{name}` in C"),
)
.with_span_note(*first_span, format!("{first} is here"))
.with_help("rename or exclude one in the config")
.with_help(match first.starts_with("field ") || second.starts_with("field ") {
true => "rename or exclude one in the config, a field by `field@` and its path",
false => "rename or exclude one in the config",
})
.emit();
}
if tcx.dcx().has_errors().is_some() {
Expand Down Expand Up @@ -312,3 +318,11 @@ pub fn write(path: &Path, text: &str) -> Result<(), String> {
}
std::fs::write(path, text).map_err(|err| format!("writing {}: {err}", path.display()))
}

/// A config path's `field@`, if it names a field by it, and the path after it.
fn field(path: &str) -> (&str, &str) {
match path.strip_prefix("field@") {
Some(path) => ("field@", path),
None => ("", path),
}
}
2 changes: 1 addition & 1 deletion ffi/src/glue.rs
Original file line number Diff line number Diff line change
Expand Up @@ -897,7 +897,7 @@ impl Gen<'_> {
}
let call = match function.access {
Access::Call => format!("{callee}({})", args.join(", ")),
Access::Field => format!("&({}).{}", args[0], function.name()),
Access::Field { .. } => format!("&({}).{}", args[0], function.name()),
Access::Const => callee,
};
let body = stmts.join("\n\t");
Expand Down
6 changes: 4 additions & 2 deletions ffi/src/ir.rs
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,10 @@ pub struct Instance {
pub enum Access {
/// It calls the function.
Call,
/// It reads a `pub` field of its receiver.
Field,
/// It reads a `pub` field of its receiver. `shared` when a method or constant of its
/// type takes its name, which its path then names, so the config names the field
/// `field@<path>`, as rustdoc does.
Field { shared: bool },
/// It reads a constant that is not a `bool` or integer.
Const,
}
Expand Down
Loading