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
2 changes: 2 additions & 0 deletions ffi/Cargo.lock

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

5 changes: 5 additions & 0 deletions ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

- A type parameter bounded by serde's `Serialize` or `Deserialize` takes
`serde_json::Value`, not `String`: C passes a `<prefix>_json` it parses from JSON text
with `<prefix>_json_parse`, not a buffer, and a generic type at such a parameter is
named by `json` (`moq_json_snapshot_json`), not `string`. An item that clashes with
`<prefix>_json` or its functions takes a `rename`.
- A type parameter whose bounds imply bytes, through a supertrait such as moq's
`IntoBytes: AsRef<[u8]>` or a `From` implementation such as moq's
`impl<B: Into<Bytes>> From<B> for Timed<Bytes>`, exports as bytes rather than
Expand Down
6 changes: 4 additions & 2 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,15 +76,17 @@ export's, and adds nothing; another crate's type is refused.
| `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` |
| `serde_json::Value` | an object `<prefix>_json`, made by `<prefix>_json_parse` from JSON text, which fails with serde_json's message, and read back by `_to_text`; its contents are the caller's JSON library's to read |
| `Vec<T>` and `&[T]` of any other `T` | `<prefix>_vec_<T>`: an array of `T`'s C values, viewed passed in and owned returned, a slice as a clone; of references only returned |
| `Waker`, taken by value | `<prefix>_waker`, as a future's poll takes it |
| `Range<T>`, `Bound<T>` of an integer | `<prefix>_range_<T>`, `<prefix>_bound_<T>`: a `<prefix>_bound` kind and a value |
| `impl RangeBounds<T>` of an integer | `<prefix>_bounds_<T>`: its start and end bounds |
| `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>`, or a bound implying one, as a supertrait does | `X`, or `&X` and then `String` or `Vec<T>` where `X` is `str` or `[T]` |
| `impl Into<X>`, where `X` does not map | what a `From` implementation into `X` takes, by its source parameter's bounds as above: `impl<B: Into<Bytes>> From<B> for Timed<Bytes>` takes `Bytes` |
| another type parameter | 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, as `&X` where that meets its bounds too, 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 |
| `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 any other source as it is, so `impl<'a, V> From<&'a V> for Timed<&'a V>` takes `&V` |
| `impl IntoIterator<Item = X>`, where `X` is no type parameter | `Vec<X>` |
| 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, as `&X` where that meets its bounds too, 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 generic type infers the instances it exports at, with no config: the one at its
defaults, if each type parameter has one; the one each inherent impl is of, such as
Expand Down
2 changes: 2 additions & 0 deletions ffi/fixtures/api/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ name = "api_lib"
[dependencies]
bytes = "1.11.1"
dep-fixture = { path = "../dep" }
serde = "1.0.229"
serde_json = "1.0.154"
url = "2.5.8"

[lints]
Expand Down
16 changes: 16 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -371,6 +371,22 @@ fn main() {
api_lib::worth(None, Box::default())
);
println!("sums {:?}", api_lib::sums(vec![vec![1, 2], Vec::new(), vec![3]]));
let summed = api_lib::summed([Point { x: 1, y: 2 }, Point { x: -4, y: 6 }]);
let none = api_lib::summed([]);
println!("summed {} {} {} {}", summed.x, summed.y, none.x, none.y);
println!(
"longest {} {}",
api_lib::longest(["a".to_string(), "abc".to_string()]),
api_lib::longest([])
);
let doc: serde_json::Value = r#"{"b": [1, 2.5, null], "a": "\u00e9"}"#.parse().expect("a JSON document");
println!("json {}", api_lib::encode(&doc));
println!("timed text {}", api_lib::timed_text(&doc));
println!("tagged {}", api_lib::tagged(doc, "t"));
match "{\"a\":".parse::<serde_json::Value>() {
Ok(doc) => println!("json parse {doc}"),
Err(err) => println!("json parse err {err}"),
}
let site = api_lib::Site::new(base);
println!("site {} {}", site.home, site.home);

Expand Down
35 changes: 35 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -662,6 +662,18 @@ pub fn timed_hex(payload: impl Into<Timed<Bytes>> + 'static) -> String {
hex(payload.into().value)
}

/// A reference stamped with no time, as moq's `Timed` converts one.
impl<'a, V> From<&'a V> for Timed<&'a V> {
fn from(value: &'a V) -> Self {
Self { value, at: None }
}
}

/// A timed value's compact JSON text, taken as moq's JSON tracks take theirs.
pub fn timed_text<'a, T: serde::Serialize + 'a>(value: impl Into<Timed<&'a T>>) -> String {
serde_json::to_string(value.into().value).expect("a JSON document serializes")
}

pub fn greet(name: impl Into<String>, shape: Shape) -> String {
format!("hello {}, a {shape:?}", name.into())
}
Expand Down Expand Up @@ -1037,6 +1049,29 @@ pub fn sums(rows: Vec<Vec<u32>>) -> Vec<u32> {
rows.iter().map(|row| row.iter().sum()).collect()
}

/// The points added up, from anything that iterates them.
pub fn summed(points: impl IntoIterator<Item = Point>) -> Point {
points.into_iter().fold(Point::default(), |sum, p| sum.offset(p.x, p.y))
}

/// The length of the longest word, naming its iterator.
pub fn longest<I>(words: I) -> usize
where
I: IntoIterator<Item = String>,
{
words.into_iter().map(|word| word.len()).max().unwrap_or(0)
}

/// `value` as compact JSON text: a serde bound takes a JSON document.
pub fn encode<T: serde::Serialize>(value: &T) -> String {
serde_json::to_string(value).expect("a JSON document serializes")
}

/// `doc` under `tag`, as a new document.
pub fn tagged(doc: serde_json::Value, tag: &str) -> serde_json::Value {
serde_json::json!({ "tag": tag, "doc": doc })
}

/// A site: every field is `pub`, but a URL is a handle C cannot copy, so it is an object
/// whose getter returns a clone.
pub struct Site {
Expand Down
4 changes: 4 additions & 0 deletions ffi/fixtures/reject/expected.txt
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ fixtures/reject/src/lib.rs:320:1: rust2-ffi: cannot export fn `count_some`: Vec
fixtures/reject/src/lib.rs:325:1: rust2-ffi: cannot export fn `count_slice`: slice of references `&str`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:330:1: rust2-ffi: cannot export fn `peek_all`: reference to a handle inside a value `[Opaque]`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:335:1: rust2-ffi: cannot export fn `none_opaque`: borrowed return that is not Clone `[Opaque]`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:347:1: rust2-ffi: cannot export fn `stash`: generic parameter `std::convert::Into`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:362:1: rust2-ffi: cannot export fn `hold`: generic parameter `std::convert::Into`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:367:1: rust2-ffi: cannot export fn `bound`: generic parameter `std::convert::Into`; exclude it in the config to leave it out
fixtures/reject/src/lib.rs:372:1: rust2-ffi: cannot export fn `kept`: generic parameter `std::convert::Into`; exclude it in the config to leave it out
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 Down
2 changes: 1 addition & 1 deletion ffi/fixtures/reject/ffi.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package = "reject-fixture"
prefix = "reject"
# An exclusion leaves an item or an instance out, so nothing refuses it.
exclude = ["Cell<u16>", "Excluded"]
exclude = ["Cell<u16>", "Excluded", "Held"]

# A field that is none: `min` names nothing of `Limit`.
[rename]
Expand Down
37 changes: 37 additions & 0 deletions ffi/fixtures/reject/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -335,3 +335,40 @@ pub fn peek_all(values: &[Opaque]) -> usize {
pub fn none_opaque() -> &'static [Opaque] {
&[]
}

/// A conversion only from what outlives every call, which C cannot lend.
impl From<&'static u32> for Excluded {
fn from(_: &'static u32) -> Self {
Excluded
}
}

/// Takes only a `'static` borrow, through `Excluded`'s `From`.
pub fn stash(value: impl Into<Excluded>) -> u32 {
let _ = value.into();
0
}

/// Excluded, borrowing what it converts from.
pub struct Held<'a>(pub &'a u32);

impl<'a> From<&'a u32> for Held<'a> {
fn from(value: &'a u32) -> Self {
Held(value)
}
}

/// Takes a borrow only for as long as `'static`, which the target's lifetime demands.
pub fn hold(value: impl Into<Held<'static>>) -> u32 {
*value.into().0
}

/// Takes a borrow only for as long as `'static`, which its own lifetime bound demands.
pub fn bound<'a: 'static>(value: impl Into<Held<'a>>) -> u32 {
*value.into().0
}

/// Takes a borrow only for as long as `'static`, which its parameter's bound demands.
pub fn kept<'a>(value: impl Into<Held<'a>> + 'static) -> u32 {
*value.into().0
}
13 changes: 1 addition & 12 deletions ffi/moq/ffi.toml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ exclude = [
"track::Fetching",
"track::Resolving",
"track::Subscribing",
"track::Subscription::with_ranges",
"transport::Error",
"transport::MaybeSend",
"transport::MaybeSync",
Expand Down Expand Up @@ -84,7 +83,7 @@ exclude = [

# Exported with moq-net, whose signatures name their types, such as `Patterns` and `Instant`.
[crates.moq-pattern]
exclude = ["Pattern::captures", "Pattern::new", "Patterns::iter"]
exclude = ["Pattern::captures", "Patterns::iter"]

[crates.moq-clock]
exclude = [
Expand Down Expand Up @@ -310,8 +309,6 @@ exclude = [
"catalog::Guard",
"catalog::IntoRendition",
"catalog::Producer::audio",
"catalog::Producer::json_snapshot",
"catalog::Producer::json_stream",
"catalog::Producer::modify",
"catalog::Producer::stats",
"catalog::Producer::text",
Expand All @@ -325,23 +322,17 @@ exclude = [
"catalog::Select",
"catalog::Stream",
"catalog::hang::CatalogExt",
"catalog::hang::Extra::get",
"catalog::hang::Extra::iter",
"catalog::hang::Extra::remove",
"catalog::hang::Extra::set",
"codec::aac::Config::parse",
"codec::annexb::NalIterator",
"codec::annexb::build_prefix",
"codec::annexb::find_start_code",
"codec::annexb::from_length_prefixed",
"codec::annexb::length_prefixed_to_annexb",
"codec::av1::Error",
"codec::av1::Import::decode",
"codec::flac::Config",
"codec::h264::Export",
"codec::h264::Import::decode",
"codec::h265::Export",
"codec::h265::Import::decode",
"codec::opus::Config::parse",
"codec::opus::Mapping::new",
"codec::opus::mapping::Config",
Expand Down Expand Up @@ -370,8 +361,6 @@ exclude = [
"follow::Event",
"follow::Instances",
"json::Consumer",
"json::Snapshot",
"json::Stream",
]

[crates.moq-mux.rename]
Expand Down
116 changes: 116 additions & 0 deletions ffi/moq/moq.c
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,45 @@ static void lists_stats(void *data, moq_hang_catalog_extra *catalog) {
moq_catalog_stats_free(stats);
}

/* Whether `buf` holds `s` anywhere. */
static int contains(moq_buf buf, const char *s) {
size_t len = strlen(s);
for (size_t i = 0; i + len <= buf.len; i++) {
if (memcmp(buf.ptr + i, s, len) == 0) {
return 1;
}
}
return 0;
}

/* Sets the lent catalog's `app` section to the JSON document in data, in place. */
static void sets_app(void *data, moq_hang_catalog_extra *catalog) {
moq_catalog_hang_extra *sections = moq_hang_catalog_extra_ext(catalog);
moq_mux_error *err = NULL;
CHECK(moq_catalog_hang_extra_set(sections, str("app"), data, &err));
moq_hang_catalog_extra_set_ext(catalog, sections);
moq_catalog_hang_extra_free(sections);
}

/* What C reads back from the lent catalog: its JSON, and its `app` section as text. */
struct readback {
moq_buf json;
moq_buf app;
};

static void reads_back(void *data, moq_hang_catalog_extra *catalog) {
struct readback *back = data;
moq_hang_error *hang_err = NULL;
CHECK(moq_hang_catalog_extra_to_json(catalog, &back->json, &hang_err));
moq_catalog_hang_extra *sections = moq_hang_catalog_extra_ext(catalog);
moq_json *app = moq_catalog_hang_extra_get(sections, str("app"));
if (app != NULL) {
back->app = moq_json_to_text(app);
moq_json_free(app);
}
moq_catalog_hang_extra_free(sections);
}

static int wakes = 0;

static void wake(void *data) {
Expand Down Expand Up @@ -276,6 +315,25 @@ int main(void) {
moq_mux_error_free(mux_err);
mux_err = NULL;

/* A subscription's ranges, from any iterable of them: an array, copied in. */
moq_track_range ranges[] = {
moq_track_range_live(),
moq_track_range_groups((moq_bounds_u64){.start = {.kind = MOQ_BOUND_INCLUDED, .value = 2},
.end = {.kind = MOQ_BOUND_EXCLUDED, .value = 6}}),
};
moq_track_subscription *unranged = moq_track_subscription_default();
moq_track_subscription *ranged =
moq_track_subscription_with_ranges(unranged, (moq_vec_track_range){.ptr = ranges, .len = 2});
moq_track_subscription_free(unranged);
moq_vec_track_range got = moq_track_subscription_ranges(ranged);
CHECK(got.len == 2 && moq_track_range_eq(&got.ptr[0], &ranges[0]));
CHECK(got.len == 2 && got.ptr[1].start.tag == MOQ_TRACK_ANCHOR_ABSOLUTE && got.ptr[1].start.absolute._0 == 2);
CHECK(got.len == 2 && got.ptr[1].end.some && got.ptr[1].end.value.absolute._0 == 6);
moq_vec_track_range_free(got);
moq_track_range_free(&ranges[0]);
moq_track_range_free(&ranges[1]);
moq_track_subscription_free(ranged);

/* A catalog at moq-mux's untyped extension, from the config C builds, whose generic
* `is_claimed` is named by the last segment of its argument, and whose `mutate` lends
* the catalog to C, which sets its fields in place. */
Expand All @@ -298,6 +356,64 @@ int main(void) {
int listed_stats = 0;
CHECK(moq_catalog_producer_extra_mutate(catalog, lists_stats, &listed_stats, &mux_err));
CHECK(listed_stats == 1);
/* A JSON track the catalog lists, published through moq-mux's generic `json_snapshot`
* at a JSON document, and a section C parses from text, set in the lent catalog and
* read back as text. */
moq_track_producer *status = NULL;
CHECK(moq_broadcast_producer_create_track(publisher, str("status"), NULL, &status, &err));
moq_json_config *json_config = moq_json_config_default();
moq_json_options *json_options = moq_json_options_default();
moq_json_snapshot_json *status_snapshot = NULL;
CHECK(moq_catalog_producer_extra_json_snapshot_config(catalog, status, json_config, json_options, &status_snapshot,
&mux_err));
moq_json_config_free(json_config);
moq_json_options_free(json_options);
moq_track_producer_free(status);
CHECK(is(moq_json_snapshot_json_name(status_snapshot), "status"));
CHECK(moq_catalog_producer_extra_is_claimed_json_config(catalog, str("status")));
/* A value C parses is published as the track's latest, which a subscriber reads back
* as JSON text. */
moq_json *latest = NULL;
moq_buf json_err;
CHECK(moq_json_parse(str("{\"on\": true}"), &latest, &json_err));
CHECK(moq_json_snapshot_json_update(status_snapshot, latest, &mux_err));
moq_json_free(latest);
moq_track_subscriber *status_subscriber = moq_json_snapshot_json_consume(status_snapshot);
moq_track_subscriber_recv_group_future *status_receiving = moq_track_subscriber_recv_group(status_subscriber);
moq_group_consumer *status_group = NULL;
CHECK(moq_track_subscriber_recv_group_poll(status_receiving, waker, &status_group, &err) == MOQ_POLL_READY);
moq_track_subscriber_recv_group_future_free(status_receiving);
moq_frame_frame *status_frame = NULL;
if (status_group != NULL) {
moq_group_consumer_read_frame_future *status_reading = moq_group_consumer_read_frame(status_group);
CHECK(moq_group_consumer_read_frame_poll(status_reading, waker, &status_frame, &err) == MOQ_POLL_READY);
moq_group_consumer_read_frame_future_free(status_reading);
moq_group_consumer_free(status_group);
}
CHECK(status_frame != NULL && is(moq_frame_frame_payload(status_frame), "{\"on\":true}"));
moq_frame_frame_free(status_frame);
moq_track_subscriber_free(status_subscriber);
moq_json *app = NULL;
CHECK(moq_json_parse(str("{\"v\": [1, true]}"), &app, &json_err));
CHECK(moq_catalog_producer_extra_mutate(catalog, sets_app, app, &mux_err));
moq_json_free(app);
struct readback back = {0};
CHECK(moq_catalog_producer_extra_mutate(catalog, reads_back, &back, &mux_err));
CHECK(contains(back.json, "\"status\""));
moq_buf_free(back.json);
CHECK(is(back.app, "{\"v\":[1,true]}"));
/* Malformed text fails to parse, and a reserved section is moq-mux's error. */
CHECK(!moq_json_parse(str("{\"v\":"), &app, &json_err));
CHECK(is(json_err, "EOF while parsing a value at line 1 column 5"));
moq_catalog_hang_extra *sections = moq_catalog_hang_extra_default();
CHECK(moq_json_parse(str("1"), &app, &json_err));
CHECK(!moq_catalog_hang_extra_set(sections, str("json"), app, &mux_err));
CHECK(mux_err != NULL && is(moq_mux_error_to_string(mux_err), "reserved catalog section: json"));
moq_mux_error_free(mux_err);
mux_err = NULL;
moq_json_free(app);
moq_catalog_hang_extra_free(sections);
moq_json_snapshot_json_free(status_snapshot);
moq_catalog_producer_extra_free(catalog);
moq_broadcast_producer_free(publisher);

Expand Down
Loading