Skip to content
Closed
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
8 changes: 8 additions & 0 deletions ffi/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ exclude = ["track::Producer::poll_closed"]

Every `pub` item reachable from the crate root, by its shortest path, is exported or
refused. `#[doc(hidden)]` items are no part of the API and are left out; type aliases
export nothing of their own.
export nothing of their own. Another crate's item that the API re-exports is exported at
that path, as moq-net's `Patterns` is; another crate's type named but not re-exported is
refused, and so is a re-exported module of another crate, whose API is its own.

| Rust | C |
| --- | --- |
Expand Down
1 change: 1 addition & 0 deletions ffi/fixtures/api/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ name = "api_lib"

[dependencies]
bytes = "1.11.1"
dep-fixture = { path = "../dep" }

[lints]
workspace = true
7 changes: 6 additions & 1 deletion ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +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, Stamp, Tally, Window,
Area, Channel, Counter, Event, LIMIT, Log, Logger, Message, Name, Node, Point, Registry, Shape, Size, Stamp, Tally,
Window,
};
use bytes::Bytes;

Expand Down Expand Up @@ -191,6 +192,10 @@ fn main() {
println!("tally {} {}", tally.bump(), tally == tally);
println!("both {}", api_lib::bump_both(&tally, &tally));

let area = api_lib::grow(&Area::new(Size { width: 2, height: 3 }), 1);
let size = area.size();
println!("area {} {} {}", size.width, size.height, area.pixels());

let token = api_lib::Token::new(7);
println!("token {} dropped {}", token.id, api_lib::dropped());
drop(token);
Expand Down
11 changes: 11 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ use std::task::{Poll, Waker};
use std::time::Duration;

use bytes::Bytes;
// Another crate's items, exported at these paths.
pub use dep::{Area, Size};

/// The largest value a [`Counter`] reaches.
pub const LIMIT: u64 = 1000;
Expand Down Expand Up @@ -467,3 +469,12 @@ pub fn greet(name: impl Into<String>, shape: Shape) -> String {
pub fn describe(event: &Event) -> String {
format!("{event:?}")
}

/// An area grown by `by` on each side: another crate's types, named through their re-export.
pub fn grow(area: &Area, by: u32) -> Area {
let size = area.size();
Area::new(Size {
width: size.width + by,
height: size.height + by,
})
}
13 changes: 13 additions & 0 deletions ffi/fixtures/dep/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
[package]
name = "dep-fixture"
description = "Another crate, whose items the api fixture re-exports"
version = "0.0.0"
edition = "2024"
license = "MIT OR Apache-2.0"
publish = false

[lib]
name = "dep"

[lints]
workspace = true
29 changes: 29 additions & 0 deletions ffi/fixtures/dep/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
//! Another crate's items, which the api fixture re-exports and names in its own API.

/// A size: a record, though another crate defines it.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Size {
pub width: u32,
pub height: u32,
}

/// An area: an object, though another crate defines it.
#[derive(Clone, Debug)]
pub struct Area {
size: Size,
}

impl Area {
pub fn new(size: Size) -> Self {
Self { size }
}

pub fn size(&self) -> Size {
self.size
}

/// Its width times its height.
pub fn pixels(&self) -> u64 {
u64::from(self.size.width) * u64::from(self.size.height)
}
}
3 changes: 3 additions & 0 deletions ffi/fixtures/reject/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,8 @@ edition = "2024"
license = "MIT OR Apache-2.0"
publish = false

[dependencies]
dep-fixture = { path = "../dep" }

[lints]
workspace = true
1 change: 1 addition & 0 deletions ffi/fixtures/reject/expected.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
fixtures/reject/src/lib.rs:102:9: rust2-ffi: cannot export use `dep`: re-export of another crate's module `dep`; 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: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
Expand Down
3 changes: 3 additions & 0 deletions ffi/fixtures/reject/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -97,3 +97,6 @@ pub fn retext<'a>(text: &mut Text<'a>, with: &'a str) {
pub fn first(opaque: &Opaque) -> Option<&Opaque> {
Some(opaque)
}

/// Another crate's module, whose API is that crate's own export.
pub use dep;
25 changes: 8 additions & 17 deletions ffi/moq/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,16 @@ exclude = [
"Hops::as_slice",
"Hops::iter",
"IntoBytes",
"InvalidPattern",
"Path::borrow",
"Path::new",
"Path::parts",
"Path::strip_prefix",
"Pattern",
"Patterns",
"Pattern::captures",
"Pattern::intersect",
"Pattern::new",
"Pattern::segments",
"Patterns::intersect",
"Patterns::iter",
"Server::accept",
"Server::accept_request",
"Server::with_publisher",
Expand All @@ -33,33 +36,20 @@ exclude = [
"Versions::iter",
"announce::Announce::captures",
"announce::Consumer::poll_synced",
"auth::Grant::expires",
"auth::Grant::publish",
"auth::Grant::subscribe",
"bytes",
"cache::Pool::poll",
"frame::Buffer",
"frame::Frame::arrived",
"frame::Producer::group",
"goaway::Consumer::poll",
"group::Consumer::poll_read_frames",
"group::Consumer::read_frames",
"group::Producer::write_frames",
"kio",
"origin::Consumer::allowed",
"origin::Consumer::scope",
"origin::Driver::poll",
"origin::Producer::allowed",
"origin::Producer::scope",
"origin::Requesting::poll_ok",
"path::Relative::borrow",
"path::Relative::new",
"path::Segment",
"path::Specificity",
"server::Handshake::with_deadline",
"server::Handshake::with_publisher",
"stats::Config::exclude",
"stats::Config::with_exclude",
"stats::Failure::ALL",
"stats::RefusalKind::ALL",
"stats::Report::sessions",
Expand All @@ -68,7 +58,8 @@ exclude = [
"stats::Snapshot::sessions",
"stats::Snapshot::traffic",
"time::Driver",
"time::Instant",
"time::Instant::from_std",
"time::Instant::into_std",
"time::run",
"track::Querying::poll_ok",
"track::Subscribing::poll_ok",
Expand Down
25 changes: 22 additions & 3 deletions ffi/moq/moq.c
Original file line number Diff line number Diff line change
Expand Up @@ -131,14 +131,33 @@ int main(void) {
moq_path *root = moq_origin_producer_root(origin);
CHECK(is(moq_path_as_str(root), ""));
moq_path_free(root);
moq_path *absolute = moq_origin_producer_absolute(origin, str("room/alice"));

/* Scoped beneath a root to the patterns moq-pattern parses, which moq-net re-exports. */
moq_pattern *alice = NULL;
moq_invalid_pattern invalid;
CHECK(moq_pattern_subtree(str("alice"), &alice, &invalid));
moq_patterns *patterns = moq_patterns_new();
CHECK(moq_patterns_insert(patterns, alice));
moq_pattern_free(alice);
moq_origin_producer *scoped = NULL;
CHECK(moq_origin_producer_scope(origin, str("room"), patterns, &scoped, &err));
moq_patterns_free(patterns);
root = moq_origin_producer_root(scoped);
CHECK(is(moq_path_as_str(root), "room"));
moq_path_free(root);
moq_path *absolute = moq_origin_producer_absolute(scoped, str("alice"));
CHECK(is(moq_path_as_str(absolute), "room/alice"));
moq_path_free(absolute);
moq_origin_consumer *reader = moq_origin_producer_consume(origin);
absolute = moq_origin_consumer_absolute(reader, str("room/bob"));
moq_patterns *allowed = moq_origin_producer_allowed(scoped);
CHECK(moq_patterns_matches(allowed, str("alice/cam")));
CHECK(!moq_patterns_matches(allowed, str("bob")));
moq_patterns_free(allowed);
moq_origin_consumer *reader = moq_origin_producer_consume(scoped);
absolute = moq_origin_consumer_absolute(reader, str("bob"));
CHECK(is(moq_path_as_str(absolute), "room/bob"));
moq_path_free(absolute);
moq_origin_consumer_free(reader);
moq_origin_producer_free(scoped);

/* A broadcast the origin creates is stamped with its path, which its info lends. */
moq_origin_publication *publication = NULL;
Expand Down
42 changes: 21 additions & 21 deletions ffi/src/collect.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ pub struct Collected {
pub aliases: Vec<String>,
}

/// How a local type is exported, once decided.
/// How a type is exported, once decided.
#[derive(Clone)]
enum Decl {
Record(usize),
Expand All @@ -80,7 +80,7 @@ struct Collector<'tcx> {
hidden: Vec<String>,
excluded: Vec<(String, usize)>,
aliases: Vec<String>,
/// Local items the walk left out, and why: `excluded` or `doc(hidden)`.
/// Items the walk left out, and why: `excluded` or `doc(hidden)`.
left_out: rustc_data_structures::fx::FxHashMap<DefId, &'static str>,
/// The type parameters of the function being mapped that take a foreign
/// implementation, with the callback each takes.
Expand Down Expand Up @@ -217,18 +217,20 @@ impl<'tcx> Collector<'tcx> {
.first()
.and_then(|reexport| reexport.id())
.map_or_else(|| tcx.def_span(def_id), |id| tcx.def_span(id));
let Some(local) = def_id.as_local() else {
let krate = tcx.crate_name(def_id.krate);
self.refuse(
&path,
"use",
span,
vec![why("re-export of another crate's item", krate.to_string())],
);
continue;
};
match kind {
DefKind::Mod => queue.push_back((local, path)),
DefKind::Mod => match def_id.as_local() {
Some(local) => queue.push_back((local, path)),
// Another crate's module is that crate's own export.
None => {
let krate = tcx.crate_name(def_id.krate);
self.refuse(
&path,
"use",
span,
vec![why("re-export of another crate's module", krate.to_string())],
);
}
},
DefKind::TyAlias => self.aliases.push(path.join("::")),
DefKind::Macro(_) => self.refuse(&path, "macro", span, vec![why("macro", "")]),
DefKind::Static { .. } => self.refuse(&path, "static", span, vec![why("static", "")]),
Expand Down Expand Up @@ -1236,8 +1238,6 @@ impl<'tcx> Collector<'tcx> {
}
_ => return Err(why("Arc", strip_args(tcx, did))),
}
} else if !did.is_local() {
return Err(why("foreign type", strip_args(tcx, did)));
} else {
match self.decls.get(&did) {
Some(Decl::Record(i)) => Type::Record(*i),
Expand All @@ -1249,12 +1249,12 @@ impl<'tcx> Collector<'tcx> {
Some(Decl::Object(i)) => Type::Object(*i),
Some(Decl::Refused(_)) => return Err(why("refused type", tcx.def_path_str(did))),
Some(Decl::Callback(_)) | None => {
let construct = self
.left_out
.get(&did)
.copied()
.unwrap_or("type not reachable from the crate root");
return Err(why(construct, tcx.def_path_str(did)));
return Err(match self.left_out.get(&did) {
Some(construct) => why(construct, tcx.def_path_str(did)),
// Exported only where the crate's API re-exports it.
None if !did.is_local() => why("foreign type", strip_args(tcx, did)),
None => why("type not reachable from the crate root", tcx.def_path_str(did)),
});
}
}
}
Expand Down
8 changes: 8 additions & 0 deletions ffi/tests/api.c
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,14 @@ static int script(void) {
printf("both %u\n", api_bump_both(tally, tally));
api_tally_free(tally);

/* Another crate's types, through the re-exports. */
api_area *small = api_area_new((api_size){.width = 2, .height = 3});
api_area *area = api_grow(small, 1);
api_area_free(small);
api_size size = api_area_size(area);
printf("area %u %u %llu\n", size.width, size.height, (unsigned long long)api_area_pixels(area));
api_area_free(area);

/* Its Drop runs when C frees the handle, not before. */
api_token *token = api_token_new(7);
printf("token %u dropped %u\n", api_token_id(token), api_dropped());
Expand Down
5 changes: 3 additions & 2 deletions quest/m1/ffi-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,9 @@ census refuses and what moq waits on:
`strip_prefix`, and `Relative::new`, and drops `AsPath` and the `borrow` methods from
[the exclude list](/ffi/moq/ffi.toml), refusing only `Path::from_static`'s `'static` borrow.
- **Several crates**: moq-tokio's sessions and the media crates hold moq-ffi's remaining API.
Export each with its own census, naming another export's types across crates, as
moq-pattern's re-exports already need.
Export each with its own census into one library, naming another export's types across
crates. What a crate re-exports, such as moq-net's `Patterns`, already exports at the
re-export's path.
- **Driving**: sessions and origins run a `Driver` polled with a time and a `kio::Waiter`.
Decide between exporting that poll, a generated thread that drives it, or moq-tokio's
runtime helpers.
Expand Down