diff --git a/ffi/MIGRATE.md b/ffi/MIGRATE.md index 211c0f6cf..72be195a1 100644 --- a/ffi/MIGRATE.md +++ b/ffi/MIGRATE.md @@ -8,3 +8,9 @@ - Every export defines `_contract` and `_CONTRACT`, so an exported item that the naming rule names either, such as a crate root's `pub fn contract` or `pub const CONTRACT`, clashes with them: give it another name with a `rename`. +- A field, parameter, or variant named a C++ keyword, such as moq's `namespace`, takes + a leading `_` in C as a C keyword does (`_namespace`), so the header compiles as C++. +- The C++ header's runtime names (`view`, `result`, `task`, `future`, `poll_t`, and + `detail`) and every variant's payload name (`_`, even without fields) + join the names the naming rule claims, so an exported item named one clashes: give it + another name with a `rename`. diff --git a/ffi/README.md b/ffi/README.md index 2a293f73f..b21b8089b 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -24,6 +24,7 @@ to what the library builds with on any platform, read off cargo's resolution, wh it was declared (the manifest, cargo's config, `--config`, or the environment), keyed by its source's URL. A `[replace]` from the source it replaces, which no `[patch]` can carry, is an error. +Beside the C header, `include/.hpp` holds the same API in C++. ```toml # ffi.toml, beside the package's Cargo.toml unless --manifest-path says otherwise. @@ -143,6 +144,44 @@ refused, and the census counts why. out of that one; a `rename` of a method by the generic type's path names it at every instance. +## C++ + +`.hpp` is header-only C++ over the C header, for C++17, 20, and 23, with +exceptions and RTTI on or off: it throws nothing and reads no type information. + +- **Names** are the C names without the prefix, in a namespace of it: `moq_track_producer` + is `moq::track_producer`, and its method `moq_track_producer_append_group` is + `moq::track_producer::append_group`. A keyword takes a trailing `_` (`counter::new_`), + as does a member named as its class or one of its fields. +- **Objects** are classes owning their handle, move-only unless `Clone`, whose copy + clones. `&self` methods are `const`, and `self` methods are `&&`, so a call that moves + the value out reads `std::move(c).into_label()`. A handle taken by value is moved into, + by a parameter taken by value. +- **Records** are structs, and **enums** an `enum class`, or for one with data a + `std::variant` of a struct per variant, `_`. An enum's methods and + traits are free functions taking it first. `PartialEq` is `==`, `Display` `to_string()`, + `Debug` `debug()`, and `Default` `default_()`. +- **Bytes** are passed as a `view`, which any contiguous bytes convert to, and returned as + a `buf`, which owns Rust's buffer without a copy. `Option` is `std::optional`, a + tuple `std::tuple`, and `Result` a `result`, whose `value()` aborts on an + error. +- **Traits** are abstract classes, passed as a `std::unique_ptr` that Rust deletes. +- **Closures** lent for a call are any callable, taken by a template parameter, which + Rust calls only during the call, from any thread. An object it lends is a reference to + its class for that call: moving out of it aborts. +- **Futures** are move-only `future<...>`s, freed when destroyed, which cancels them and + loses nothing. `poll(waker)` polls once; `std::move(f).get()` blocks the thread; + `std::move(f).then(exec, callback)` polls on an executor and calls back there, returning + a `task` that cancels when destroyed, after which the callback has finished or never + runs; and from C++20, `co_await std::move(f).via(exec)` resumes the coroutine on the + executor. An executor is any callable taking a `void()` job to run once, later, on any + thread: never inline, since a wake may come from inside Rust. Each wake that lands while + the future polls polls it again, and a future has one poller at a time, since awaiting + it moves it. +- A **waker** is a shared callable, which Rust may call from any thread. +- **The contract** is checked when the program loads, before any other call: a header + and a library from different builds abort. + ## IR [`src/ir.rs`](src/ir.rs) is the API as each generator reads it, with no language decided: @@ -150,8 +189,10 @@ records, enums, objects, callbacks, functions, and constants of every export, ea its Rust path, its span, and its docs. A type is in the exact form Rust takes or returns it (`&str` apart from `String`, `Box` apart from `impl Trait`), so a generator can borrow where Rust borrows. [`src/abi.rs`](src/abi.rs) decides the C ABI from it once, -names and signatures, so [`src/c.rs`](src/c.rs) and [`src/glue.rs`](src/glue.rs) agree; -the runtime the glue includes is [`runtime/rt.rs`](runtime/rt.rs). +names and signatures, so [`src/c.rs`](src/c.rs), [`src/cpp.rs`](src/cpp.rs), and +[`src/glue.rs`](src/glue.rs) agree; the runtime the glue includes is +[`runtime/rt.rs`](runtime/rt.rs), and the one the C++ header includes +[`runtime/rt.hpp`](runtime/rt.hpp). ## Census @@ -164,20 +205,24 @@ rest, and the refused instances to drop from `instances`. It ignores the config' ## Tests ```bash -just ffi test # export the fixtures, build them, and drive api from C -just ffi moq # export moq's crates at the pinned revision, build them, and run moq/moq.c +just ffi test # export the fixtures, build them, and drive api from C and C++ +just ffi moq # export moq's crates at the pinned revision, build them, and run moq/moq.c and moq/moq.cpp just ffi census # census each into target/census -nix develop .#bench --command just ffi bench # frame writes, through the export and moq's rs/moq-c +nix develop .#bench --command just ffi bench # frame writes and reads, through the export from C and C++, and moq's rs/moq-c ``` The `api` fixture covers each rule once, and names the `dep` fixture's types, which export into the same library. `tests/api.c` runs the same script as the fixture's `examples/transcript.rs`, and the two transcripts must match line for line; -then it breaks each runtime check, which must abort with its message. The `reject` +then it breaks each runtime check, which must abort with its message. `tests/api.cpp` +runs the script through the C++ header at C++17, 20, and 23, with exceptions and RTTI off +at 17 and 23, then checks its futures: a wake that lands during a poll, a cancel between a +wake and its poll that loses nothing, and a coroutine resumed or destroyed. The `reject` fixture's expected errors, each with its notes, are `fixtures/reject/expected.txt`. moq's crates export through `target/moq-ffi`, an empty library on each that `just ffi moq` writes in place of moq-ffi's remainder. `moq/moq.c` publishes and subscribes to a moq-net track in one process, polling each read, scopes an origin to moq-pattern's patterns and hands it to a client to publish, polls its driver until the origin's last owner drops, reads an OpusHead into hang's catalog through moq-mux, publishes a binary track the catalog lists, and reads the catalog lent to C through -`catalog::Producer::mutate`. +`catalog::Producer::mutate`. `moq/moq.cpp` does the same through the C++ header, at +C++17 without exceptions or RTTI, as OBS builds it. diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index 74b6e07b7..d9d429126 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -72,6 +72,14 @@ fn main() { println!("debug {c:?}"); let label = c.into_label(Some(p)); println!("label {label:?}"); + let empty = api_lib::Note { + text: Some(String::new()), + }; + println!( + "note {} {}", + api_lib::has_text(empty), + api_lib::has_text(api_lib::Note::default()) + ); let (below, above) = Counter::new("s", 7).split(5); println!( diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index 37f5d19ee..22acbe364 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -40,6 +40,17 @@ pub struct Label { pub ttl: Option, } +/// A note whose text may be present but empty, which crosses as itself, not as none. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Note { + pub text: Option, +} + +/// Whether `note` has text, even empty. +pub fn has_text(note: Note) -> bool { + note.text.is_some() +} + /// A plain enumeration. #[derive(Clone, Copy, Debug, PartialEq)] pub enum Shape { @@ -354,6 +365,21 @@ impl Channel { } } +/// `value`, on its second poll: the first wakes its waker before it returns pending, so +/// the wake lands before the poller waits for one. +pub async fn yielded(value: u32) -> u32 { + let mut woken = false; + std::future::poll_fn(|cx| match std::mem::replace(&mut woken, true) { + true => Poll::Ready(()), + false => { + cx.waker().wake_by_ref(); + Poll::Pending + } + }) + .await; + value +} + /// A time: an object, since its field is private, but `Copy`, so passing it by value /// copies it rather than moving it out of its handle. #[derive(Clone, Copy, Debug, PartialEq)] diff --git a/ffi/justfile b/ffi/justfile index 42a6aa7ca..6f4c685b3 100644 --- a/ffi/justfile +++ b/ffi/justfile @@ -37,7 +37,7 @@ run *args: census checkout="": (standin checkout) cargo run --locked --quiet -- --config moq/ffi.toml --manifest-path target/moq-ffi/Cargo.toml --census target/census -# Time frame writes through the export and through moq's hand-written rs/moq-c, in the bench shell: nix develop .#bench. +# Time frame writes through the export, from C and C++, and through moq's hand-written rs/moq-c, in the bench shell: nix develop .#bench. bench checkout="": (moq checkout) #!/usr/bin/env bash set -euo pipefail @@ -50,12 +50,14 @@ bench checkout="": (moq checkout) | jq -r 'select(.reason == "build-script-executed" and (.package_id | contains("moq-c#"))) | .out_dir') cc -O2 -std=c11 -Wall -Wextra -Werror -I "$out/include" moq/bench/export.c "$out/target/release/libmoq.a" -lpthread -ldl -lm -o target/bench-export cc -O2 -std=c11 -Wall -Wextra -Werror -I "$moqc/include" moq/bench/moq-c.c "$src/target/release/libmoq.a" -lpthread -ldl -lm -o target/bench-moq-c + c++ -O2 -std=c++17 -Wall -Wextra -Werror -I "$out/include" moq/bench/export.cpp "$out/target/release/libmoq.a" -lpthread -ldl -lm -o target/bench-export-cpp for _ in 1 2 3; do target/bench-moq-c target/bench-export + target/bench-export-cpp done -# Export moq's crates' C ABI, build it, and run moq/moq.c against it, from the moq revision `just ts moq` pins or a checkout. +# Export moq's crates' C ABI, build it, and run moq/moq.c and moq/moq.cpp against it, from the moq revision `just ts moq` pins or a checkout. moq checkout="": (standin checkout) #!/usr/bin/env bash set -euo pipefail @@ -66,6 +68,9 @@ moq checkout="": (standin checkout) cargo build --quiet --release --manifest-path "$out/Cargo.toml" cc -std=c11 -pedantic -Wall -Wextra -Werror -I "$out/include" moq/moq.c "$out/target/release/libmoq.a" -lpthread -ldl -lm -o target/moq-test target/moq-test + # The C++ header at OBS's standard, without exceptions or RTTI. + c++ -std=c++17 -fno-exceptions -fno-rtti -pedantic -Wall -Wextra -Werror -I "$out/include" moq/moq.cpp "$out/target/release/libmoq.a" -lpthread -ldl -lm -o target/moq-cpp-test + target/moq-cpp-test # Write target/moq-ffi, an empty library on every crate moq/ffi.toml exports, from the moq revision `just ts moq` pins or a checkout: the check builds with all of them, as moq-ffi's remainder will. [private] diff --git a/ffi/moq/bench/export.c b/ffi/moq/bench/export.c index 9e95a7328..24381a992 100644 --- a/ffi/moq/bench/export.c +++ b/ffi/moq/bench/export.c @@ -1,5 +1,6 @@ /* The frame write path through the exported C ABI: a timed track, groups of 100 frames of - * 100 bytes, each frame stamped. bench/moq-c.c times the same through moq's rs/moq-c. */ + * 100 bytes, each frame stamped. bench/moq-c.c times the same through moq's rs/moq-c, and + * bench/export.cpp through the C++ header. Then the read path, each read a future. */ #define _POSIX_C_SOURCE 199309L @@ -78,7 +79,6 @@ int main(void) { moq_group_producer_free(group); } double reused = (now() - start) / (GROUPS * FRAMES); - moq_timestamp_free(at); /* The floor: a borrow of a handle and a bool back. */ start = now(); @@ -88,8 +88,49 @@ int main(void) { } double call = (now() - start) / (GROUPS * FRAMES); - printf("export: %.0f ns per stamped 100 B frame, %.0f reusing the timestamp, %.1f ns per handle call%s\n", stamped, reused, - call, closed ? "!" : ""); + /* Reads: each frame written, then read through a new future polled once, ready. */ + moq_waker waker = {0}; + moq_track_consumer *consumer = moq_track_producer_consume(track); + moq_track_consumer_subscribe_future *subscribing = moq_track_consumer_subscribe(consumer, NULL); + moq_track_subscriber *subscriber = NULL; + if (moq_track_consumer_subscribe_poll(subscribing, waker, &subscriber, &err) != MOQ_POLL_READY) { + return 4; + } + moq_track_consumer_subscribe_future_free(subscribing); + start = now(); + for (int g = 0; g < GROUPS; g++) { + moq_group_producer *group = NULL; + moq_track_producer_append_group(track, &group, &err); + moq_track_subscriber_recv_group_future *receiving = moq_track_subscriber_recv_group(subscriber); + moq_group_consumer *reader = NULL; + if (moq_track_subscriber_recv_group_poll(receiving, waker, &reader, &err) != MOQ_POLL_READY || reader == NULL) { + return 5; + } + moq_track_subscriber_recv_group_future_free(receiving); + for (int f = 0; f < FRAMES; f++) { + if (!moq_group_producer_write_frame(group, at, frame, &err)) { + return 6; + } + moq_group_consumer_read_frame_future *reading = moq_group_consumer_read_frame(reader); + moq_frame_frame *read = NULL; + if (moq_group_consumer_read_frame_poll(reading, waker, &read, &err) != MOQ_POLL_READY || read == NULL) { + return 7; + } + moq_group_consumer_read_frame_future_free(reading); + moq_frame_frame_free(read); + } + moq_group_producer_finish(group, &err); + moq_group_producer_free(group); + moq_group_consumer_free(reader); + } + double read = (now() - start) / (GROUPS * FRAMES); + moq_timestamp_free(at); + moq_track_subscriber_free(subscriber); + moq_track_consumer_free(consumer); + + printf("export: %.0f ns per stamped 100 B frame, %.0f reusing the timestamp, %.1f ns per handle call, %.0f ns per frame " + "written and read%s\n", + stamped, reused, call, read, closed ? "!" : ""); moq_track_producer_free(track); moq_timescale_free(micro); moq_broadcast_producer_free(broadcast); diff --git a/ffi/moq/bench/export.cpp b/ffi/moq/bench/export.cpp new file mode 100644 index 000000000..f9a06c5da --- /dev/null +++ b/ffi/moq/bench/export.cpp @@ -0,0 +1,103 @@ +// bench/export.c's frame writes through the generated C++ header, so the two differ by +// what the C++ wrapper adds; then the read path, each read a future polled once ready. + +#include +#include + +#include "moq.hpp" + +namespace { + +constexpr int groups = 10000; +constexpr int frames = 100; + +// Nanoseconds per frame since `start`. +double per_frame(std::chrono::steady_clock::time_point start) { + std::chrono::duration elapsed = std::chrono::steady_clock::now() - start; + return elapsed.count() / (groups * frames); +} + +} // namespace + +int main() { + moq::broadcast_producer broadcast = moq::broadcast_info::new_().produce(); + moq::timescale micro = moq::timescale::micro(); + auto track = broadcast.create_track("bench", moq::track_info::default_().with_timescale(µ)); + if (!track) { + return 1; + } + + std::uint8_t payload[100] = {0}; + moq::view frame(payload, sizeof payload); + std::uint64_t micros = 0; + + // Each frame stamped through a fresh timestamp handle, as a caller holding a u64 must. + auto start = std::chrono::steady_clock::now(); + for (int g = 0; g < groups; g++) { + moq::group_producer group = std::move(*track->append_group()); + for (int f = 0; f < frames; f++) { + moq::timestamp at = std::move(*moq::timestamp::from_micros(micros++)); + if (!group.write_frame(&at, frame)) { + return 2; + } + } + (void)std::move(group).finish(); + } + double stamped = per_frame(start); + + // The same, reusing one timestamp handle: what the handle costs. + moq::timestamp at = std::move(*moq::timestamp::from_micros(micros)); + start = std::chrono::steady_clock::now(); + for (int g = 0; g < groups; g++) { + moq::group_producer group = std::move(*track->append_group()); + for (int f = 0; f < frames; f++) { + if (!group.write_frame(&at, frame)) { + return 3; + } + } + (void)std::move(group).finish(); + } + double reused = per_frame(start); + + // The floor: a borrow of a handle and a bool back. + start = std::chrono::steady_clock::now(); + int closed = 0; + for (int i = 0; i < groups * frames; i++) { + closed += track->is_closed(); + } + double call = per_frame(start); + + // Reads: each frame written, then read through a new future polled once, ready. + moq::waker waker([]() {}); + moq::track_consumer consumer = track->consume(); + auto subscribed = consumer.subscribe(std::nullopt).poll(waker); + if (!subscribed || !*subscribed) { + return 4; + } + moq::track_subscriber subscriber = std::move(**subscribed); + start = std::chrono::steady_clock::now(); + for (int g = 0; g < groups; g++) { + moq::group_producer group = std::move(*track->append_group()); + auto received = subscriber.recv_group().poll(waker); + if (!received || !*received || !received->value()) { + return 5; + } + moq::group_consumer reader = std::move(*received->value()); + for (int f = 0; f < frames; f++) { + if (!group.write_frame(&at, frame)) { + return 6; + } + auto read = reader.read_frame().poll(waker); + if (!read || !*read || !read->value()) { + return 7; + } + } + (void)std::move(group).finish(); + } + double read = per_frame(start); + + std::printf( + "export (C++): %.0f ns per stamped 100 B frame, %.0f reusing the timestamp, %.1f ns per handle call, %.0f ns per frame written and read%s\n", + stamped, reused, call, read, closed ? "!" : ""); + return 0; +} diff --git a/ffi/moq/moq.cpp b/ffi/moq/moq.cpp new file mode 100644 index 000000000..b0f725f5a --- /dev/null +++ b/ffi/moq/moq.cpp @@ -0,0 +1,206 @@ +// moq.c's script through the generated C++ header: a broadcast's track, published and +// subscribed to in one process, with every read polled as a future, and an origin, with +// moq-pattern, moq-clock, moq-tokio, hang, and moq-mux exported into the same library, +// and the catalog lent to C++ for a call. +// +// It needs no runtime: the waker counts wakes, and each poll that must wait is polled +// again after the write that wakes it. + +#include +#include + +#include "moq.hpp" + +namespace { + +int failures = 0; + +#define CHECK(cond) \ + do { \ + if (!(cond)) { \ + std::fprintf(stderr, "%s:%d: %s\n", __FILE__, __LINE__, #cond); \ + failures++; \ + } \ + } while (0) + +// Whether a returned buffer holds `s`. +bool is(const moq::buf &buf, const char *s) { + bool same = buf.str() == s; + if (!same) { + std::fprintf(stderr, "got \"%.*s\", want \"%s\"\n", static_cast(buf.size()), + reinterpret_cast(buf.data()), s); + } + return same; +} + +int wakes = 0; + +} // namespace + +int main() { + moq::waker waker([]() { wakes++; }); + + moq::broadcast_producer broadcast = moq::broadcast_info::new_().produce(); + auto track = broadcast.create_track("video", std::nullopt); + CHECK(track && is(track->name(), "video")); + + // A second track of the same name is an error, printed as Rust prints it. + auto duplicate = broadcast.create_track("video", std::nullopt); + CHECK(!duplicate && is(duplicate.error().to_string(), "duplicate")); + + moq::track_consumer consumer = track->consume(); + auto subscribed = consumer.subscribe(std::nullopt).poll(waker); + CHECK(subscribed && *subscribed); + moq::track_subscriber subscriber = std::move(**subscribed); + + // A group's arrival wakes the subscriber's pending receive. + auto receiving = subscriber.recv_group(); + CHECK(!receiving.poll(waker)); + auto writer = track->append_group(); + CHECK(writer && wakes == 1); + auto received = receiving.poll(waker); + CHECK(received && *received && received->value()); + moq::group_consumer group = std::move(*received->value()); + CHECK(group.index() == 0); + + // So does a frame's. + { + auto reading = group.read_frame(); + CHECK(!reading.poll(waker)); + CHECK(writer->write_frame(nullptr, "hello")); + CHECK(wakes == 2); + auto frame = reading.poll(waker); + CHECK(frame && *frame && frame->value()); + const moq::frame_frame &hello = *frame->value(); + CHECK(is(hello.payload(), "hello")); + CHECK(!hello.timestamp()); + // When it arrived: moq-clock's `Instant`, from moq-clock's own export. + CHECK(moq::now().checked_duration_since(hello.arrived()).has_value()); + } + + // A timestamp is a `Copy` value behind a handle: passing it copies it out. The track is + // untimed, so a timestamped frame is refused. + auto at = moq::timestamp::from_millis(1500); + CHECK(at && at->as_secs() == 1); + auto late = writer->write_frame(&*at, "late"); + CHECK(!late && is(late.error().to_string(), "frame timestamp doesn't fit its track")); + CHECK(at->as_secs() == 1); + + // The last frame, then the group's end, which reads as None, both blocking. + CHECK(writer->write_frame(nullptr, "world")); + CHECK(std::move(*writer).finish()); + auto world = group.read_frame().get(); + CHECK(world && world.value() && is(world.value()->payload(), "world")); + auto end = group.read_frame().get(); + CHECK(end && !end.value()); + + // An origin and the driver that runs it, a tuple. Its root, which it lends, is returned + // as a new handle to a clone. + auto [origin, driver] = moq::origin_producer::new_(moq::origin_config::default_()); + CHECK(is(origin.root().as_str(), "")); + + // Scoped beneath a root to patterns, which moq-pattern's own export builds. + { + auto alice = moq::pattern::subtree("alice"); + CHECK(alice); + moq::patterns patterns = moq::patterns::new_(); + CHECK(patterns.insert(*alice)); + auto scoped = origin.scope("room", patterns); + CHECK(scoped); + CHECK(is(scoped->root().as_str(), "room")); + auto absolute = scoped->absolute("alice"); + CHECK(absolute && is(absolute->as_str(), "room/alice")); + moq::patterns allowed = scoped->allowed(); + CHECK(allowed.matches("alice/cam")); + CHECK(!allowed.matches("bob")); + absolute = scoped->consume().absolute("bob"); + CHECK(absolute && is(absolute->as_str(), "room/bob")); + } + + // A broadcast the origin creates is stamped with its path, which its info lends. + { + auto publication = origin.create_broadcast("room/alice"); + CHECK(publication); + moq::path path = publication->broadcast().info().path(); + CHECK(is(path.as_str(), "room/alice")); + + // Paths own their segments, so C++ builds them, and relative ones, from a string. + auto cam = moq::path::new_("/cam/"); + CHECK(cam && is(cam->as_str(), "cam")); + auto joined = path.join(*cam); + CHECK(joined && is(joined->as_str(), "room/alice/cam")); + std::optional stripped = joined->strip_prefix(path); + CHECK(stripped && *stripped == *cam); + CHECK(!path.strip_prefix(*joined)); + auto up = moq::relative::new_("../bob"); + CHECK(up); + auto resolved = joined->resolve(*up); + CHECK(resolved && is(resolved->as_str(), "room/bob")); + } + + // The driver, polled as a language's event loop would: at the time, and with a waiter + // made from the waker and held across polls, since what a poll registers lives only as + // long as its waiter. It runs until every owner of the origin is gone. + moq::waiter waiter = moq::waiter::new_(waker); + CHECK(driver.poll(moq::now(), waiter)); + { + // A client publishes the origin through moq-net's generic `with_publisher`, which a + // consumer moves into. + moq::client publishing = moq::client::new_().with_publisher(origin.consume()); + (void)publishing; + } + int before = wakes; + { + moq::origin_producer last = std::move(origin); + } + // The last owner's drop wakes the driver, which then finishes, cleanly. + CHECK(wakes > before); + auto closed = driver.poll(moq::now(), waiter); + CHECK(!closed && is(closed.error().to_string(), "closed")); + + // moq-mux reads an OpusHead into hang's catalog config: 44.1 kHz in, stereo, which the + // catalog lists at the decoder's 48 kHz, keeping the head as its description. + static const std::uint8_t head[] = {'O', 'p', 'u', 's', 'H', 'e', 'a', 'd', 1, 2, 0x38, 0x01, 0x44, 0xac, 0, 0, 0, 0, 0}; + auto audio = moq::codec_opus_audio_config(moq::view(head, sizeof head)); + CHECK(audio); + CHECK(audio->sample_rate() == 48000); + CHECK(audio->channel_count() == 2); + CHECK(std::holds_alternative(audio->codec())); + auto description = audio->description(); + CHECK(description && description->size() == sizeof head && std::memcmp(description->data(), head, sizeof head) == 0); + // A truncated head is moq-mux's error. + auto truncated = moq::codec_opus_audio_config(moq::view(head, 8)); + CHECK(!truncated && !truncated.error().to_string().empty()); + + // A binary track the catalog lists, published through moq-mux's generic + // `binary_snapshot` at the config C++ builds. + { + moq::broadcast_producer publisher = moq::broadcast_info::new_().produce(); + moq::catalog_config_extra extra = moq::catalog_config::default_().with_catalog(moq::hang_catalog::default_()); + auto catalog = moq::catalog_producer::new_(publisher, std::move(extra)); + CHECK(catalog); + auto state = publisher.create_track("state", std::nullopt); + CHECK(state); + auto snapshot = catalog->binary_snapshot(std::move(*state), moq::binary_config::default_()); + CHECK(snapshot && is(snapshot->name(), "state")); + CHECK(snapshot->update("latest")); + int listed_state = 0; + CHECK(catalog->mutate([&](moq::hang_catalog &lent) { + auto json = lent.to_json(); + CHECK(json); + if (json && json.value().str().find("state") != std::string_view::npos) { + listed_state++; + } + })); + CHECK(listed_state == 1); + } + + // moq-tokio's terminal connect errors, which moq-net's `Error` shares no names with. + CHECK(moq::connect_error_is_auth(moq::connect_error::unauthorized)); + CHECK(is(moq::connect_error_to_string(moq::connect_error::unauthorized), "unauthorized")); + + if (failures == 0) { + std::printf("ok\n"); + } + return failures != 0; +} diff --git a/ffi/runtime/rt.hpp b/ffi/runtime/rt.hpp new file mode 100644 index 000000000..deb5cc1c2 --- /dev/null +++ b/ffi/runtime/rt.hpp @@ -0,0 +1,737 @@ +// The runtime every C++ binding shares: bytes, results, wakers, and futures over the C +// ABI. rust2-ffi copies it into each header, inside the export's namespace, after +// `detail` names the export's C types. It throws nothing and reads no type information, +// so it builds with exceptions and RTTI off. + +namespace detail { + +[[noreturn]] inline void fail(const char *what) noexcept { + ::std::fputs(what, stderr); + ::std::fputc('\n', stderr); + ::std::abort(); +} + +struct access; + +// A count of references, held by C++ and, once given a waker, by Rust: freed with the last. +struct node { + ::std::atomic<::std::size_t> refs{1}; + + node() = default; + node(const node &) = delete; + node &operator=(const node &) = delete; + virtual ~node() = default; + virtual void wake() noexcept = 0; + + void ref() noexcept { + refs.fetch_add(1, ::std::memory_order_relaxed); + } + + void unref() noexcept { + if (refs.fetch_sub(1, ::std::memory_order_acq_rel) == 1) { + delete this; + } + } +}; + +inline void wake_node(void *data) noexcept { + static_cast(data)->wake(); +} + +inline void drop_node(void *data) noexcept { + static_cast(data)->unref(); +} + +// `n` as a waker that borrows its reference, which Rust reuses when given it again. +inline c_waker lend(node *n) noexcept { + return c_waker{&wake_node, &drop_node, n}; +} + +// `n` as a waker holding a new reference, which Rust drops. +inline c_waker give(node *n) noexcept { + n->ref(); + return lend(n); +} + +// An owned reference to a node. +template +class ptr { + T *node_; + +public: + // Adopts a reference already counted. + explicit ptr(T *node) noexcept : node_(node) {} + ptr(const ptr &other) noexcept : node_(other.node_) { + node_->ref(); + } + ptr(ptr &&other) noexcept : node_(::std::exchange(other.node_, nullptr)) {} + ptr &operator=(const ptr &) = delete; + ptr &operator=(ptr &&) = delete; + ~ptr() { + if (node_ != nullptr) { + node_->unref(); + } + } + T *operator->() const noexcept { + return node_; + } +}; + +// A finished poll's value: none, then the output. +template +class slot { + ::std::optional value_; + +public: + template + void emplace(A &&...args) { + value_.emplace(::std::forward(args)...); + } + explicit operator bool() const noexcept { + return value_.has_value(); + } + T take() { + return ::std::move(*value_); + } + ::std::optional release() { + return ::std::move(value_); + } +}; + +template <> +class slot { + bool ready_ = false; + +public: + void emplace() noexcept { + ready_ = true; + } + explicit operator bool() const noexcept { + return ready_; + } + void take() noexcept {} + bool release() noexcept { + return ready_; + } +}; + +// The bytes of a view, never null, so a view of none is told apart from a missing one. +inline const ::std::uint8_t *bytes(const void *data, ::std::size_t len) noexcept { + static const ::std::uint8_t empty = 0; + if (data == nullptr && len != 0) { + fail("a view of null bytes has a length"); + } + return len == 0 ? &empty : static_cast(data); +} + +} // namespace detail + +class buf; + +// Bytes lent to a call: text or binary, read during the call and never kept. +class view { + const ::std::uint8_t *data_; + ::std::size_t size_; + +public: + view() noexcept : data_(detail::bytes(nullptr, 0)), size_(0) {} + view(const void *data, ::std::size_t size) noexcept : data_(detail::bytes(data, size)), size_(size) {} + view(const char *text) noexcept : view(text, ::std::strlen(text)) {} + // Any contiguous range of bytes, such as `std::string`, `std::string_view`, `std::vector`, or `buf`. + template ().data()) == 1 && + !::std::is_pointer_v<::std::decay_t>>, + class = decltype(::std::declval().size())> + view(const R &range) noexcept : view(range.data(), range.size()) {} + + const ::std::uint8_t *data() const noexcept { + return data_; + } + ::std::size_t size() const noexcept { + return size_; + } + bool empty() const noexcept { + return size_ == 0; + } + const ::std::uint8_t *begin() const noexcept { + return data_; + } + const ::std::uint8_t *end() const noexcept { + return data_ + size_; + } + ::std::string_view str() const noexcept { + return ::std::string_view(reinterpret_cast(data_), size_); + } + + friend struct detail::access; +}; + +// Owned bytes: returned by Rust without a copy, or copied from C++. +class buf { + // Rust's when `owner` is set, else C++'s, allocated with `new[]` unless empty. + detail::c_buf raw_; + + explicit buf(detail::c_buf raw) noexcept : raw_(raw) {} + + void reset() noexcept { + if (raw_.owner != nullptr) { + detail::c_buf_free(raw_); + } else if (raw_.len != 0) { + delete[] raw_.ptr; + } + raw_ = detail::c_buf{nullptr, 0, nullptr}; + } + +public: + buf() noexcept : raw_{nullptr, 0, nullptr} {} + // A copy of `bytes`. + explicit buf(view bytes) : buf() { + if (!bytes.empty()) { + auto *copy = new ::std::uint8_t[bytes.size()]; + ::std::memcpy(copy, bytes.data(), bytes.size()); + raw_ = detail::c_buf{copy, bytes.size(), nullptr}; + } + } + buf(const buf &other) : buf(view(other)) {} + buf(buf &&other) noexcept : raw_(::std::exchange(other.raw_, detail::c_buf{nullptr, 0, nullptr})) {} + buf &operator=(const buf &other) { + if (this != &other) { + *this = buf(other); + } + return *this; + } + buf &operator=(buf &&other) noexcept { + ::std::swap(raw_, other.raw_); + return *this; + } + ~buf() { + reset(); + } + + const ::std::uint8_t *data() const noexcept { + return detail::bytes(raw_.ptr, raw_.len); + } + ::std::size_t size() const noexcept { + return raw_.len; + } + bool empty() const noexcept { + return raw_.len == 0; + } + const ::std::uint8_t *begin() const noexcept { + return data(); + } + const ::std::uint8_t *end() const noexcept { + return data() + size(); + } + ::std::string_view str() const noexcept { + return view(*this).str(); + } + + friend struct detail::access; +}; + +// What a fallible call returns: its value, or the error that stopped it. +template +class result { + ::std::variant value_; + + template <::std::size_t I, class A> + result(::std::in_place_index_t index, A &&arg) : value_(index, ::std::forward(arg)) {} + + void check() const noexcept { + if (value_.index() != 0) { + detail::fail("value() of a result that holds an error"); + } + } + +public: + static result ok(T value) { + return result(::std::in_place_index<0>, ::std::move(value)); + } + static result err(E error) { + return result(::std::in_place_index<1>, ::std::move(error)); + } + + bool has_value() const noexcept { + return value_.index() == 0; + } + explicit operator bool() const noexcept { + return has_value(); + } + // The value, aborting if it holds an error. + T &value() & { + check(); + return *::std::get_if<0>(&value_); + } + const T &value() const & { + check(); + return *::std::get_if<0>(&value_); + } + T &&value() && { + check(); + return ::std::move(*::std::get_if<0>(&value_)); + } + T &operator*() & { + return value(); + } + const T &operator*() const & { + return value(); + } + T &&operator*() && { + return ::std::move(*this).value(); + } + T *operator->() { + return &value(); + } + const T *operator->() const { + return &value(); + } + // The error, aborting if it holds a value. + E &error() & { + if (value_.index() != 1) { + detail::fail("error() of a result that holds a value"); + } + return *::std::get_if<1>(&value_); + } + const E &error() const & { + return const_cast(this)->error(); + } + E &&error() && { + return ::std::move(error()); + } +}; + +template +class result { + ::std::optional error_; + +public: + static result ok() { + return result(); + } + static result err(E error) { + result r; + r.error_.emplace(::std::move(error)); + return r; + } + + bool has_value() const noexcept { + return !error_.has_value(); + } + explicit operator bool() const noexcept { + return has_value(); + } + // Aborts if it holds an error. + void value() const noexcept { + if (error_.has_value()) { + detail::fail("value() of a result that holds an error"); + } + } + E &error() & { + if (!error_.has_value()) { + detail::fail("error() of a result that holds a value"); + } + return *error_; + } + const E &error() const & { + return const_cast(this)->error(); + } + E &&error() && { + return ::std::move(error()); + } +}; + +// Wakes a future's poller: a shared callable, which Rust may call from any thread, any +// number of times, until it lets go. +class waker { + detail::node *node_; + + template + struct callable final : detail::node { + F f; + explicit callable(F f) : f(::std::move(f)) {} + void wake() noexcept override { + f(); + } + }; + +public: + template , waker>>> + explicit waker(F f) : node_(new callable(::std::move(f))) {} + waker(const waker &other) noexcept : node_(other.node_) { + node_->ref(); + } + waker &operator=(const waker &other) noexcept { + other.node_->ref(); + node_->unref(); + node_ = other.node_; + return *this; + } + ~waker() { + node_->unref(); + } + + void wake() const noexcept { + node_->wake(); + } + + friend struct detail::access; +}; + +// What a future poll returns: the output when ready, or nothing yet. +template +using poll_t = ::std::conditional_t<::std::is_void_v, bool, ::std::optional>; + +class task; + +namespace detail { + +// A future driven on an executor, which a `task` cancels. +struct task_node : node { + virtual void cancel() noexcept = 0; +}; + +template +class driver; + +template +void spawn(task &slot, typename Op::raw *raw, Exec exec, F f); + +} // namespace detail + +// A future running on an executor until it calls back with the output. Destroying it +// cancels the future: once that returns, the callback has finished or never runs. +class task { + detail::task_node *node_ = nullptr; + + void reset() noexcept { + if (node_ != nullptr) { + ::std::exchange(node_, nullptr)->cancel(); + } + } + +public: + task() noexcept = default; + task(task &&other) noexcept : node_(::std::exchange(other.node_, nullptr)) {} + task &operator=(task &&other) noexcept { + if (this != &other) { + reset(); + node_ = ::std::exchange(other.node_, nullptr); + } + return *this; + } + ~task() { + reset(); + } + + template + friend void detail::spawn(task &, typename Op::raw *, Exec, F); +}; + +// A Rust future, polled from C++: move-only, so one poller holds it at a time. Destroying +// it before it finishes cancels it, which loses nothing, since a value leaves Rust only in +// the poll that finishes it. +template +class future { + typename Op::raw *raw_; + // The waker Rust holds from the last poll, which it reuses when given it again. + detail::node *last_ = nullptr; + + explicit future(typename Op::raw *raw) noexcept : raw_(raw) {} + + void poll_into(const waker &w, detail::slot &out); + + friend struct detail::access; + +public: + using output = typename Op::output; + + future(future &&other) noexcept + : raw_(::std::exchange(other.raw_, nullptr)), last_(::std::exchange(other.last_, nullptr)) {} + future &operator=(future &&other) noexcept { + ::std::swap(raw_, other.raw_); + ::std::swap(last_, other.last_); + return *this; + } + ~future() { + Op::free(raw_); + } + + // Poll once: the output when ready, else nothing, and `w` is woken when it is worth + // polling again. Polling after it is ready aborts. + poll_t poll(const waker &w); + + // Block the calling thread until the output is ready. + output get() &&; + + // Poll on `exec` until ready, then call `f` there with the output. `exec` is any + // callable that takes a `void()` callable and runs it once, later, on any thread: never + // within the call, which may come from inside Rust. + template + task then(Exec exec, F f) &&; + + // From C++20, `co_await` it, polled and resumed on `exec`, as `then` takes it. + // Destroying the suspended coroutine cancels the future. Declared at every standard, + // so the class is one definition across translation units built at different ones. + template + auto via(Exec exec) &&; +}; + +namespace detail { + +// What generated classes keep private, for the generated code. +struct access { + static c_buf raw(const view &v) noexcept { + return c_buf{v.data_, v.size_, nullptr}; + } + static buf adopt(c_buf raw) noexcept { + return buf(raw); + } + static ::std::optional adopt_option(c_buf raw) noexcept { + if (raw.ptr == nullptr) { + return ::std::nullopt; + } + return buf(raw); + } + static node *raw(const waker &w) noexcept { + return w.node_; + } + template + static auto raw(const T &object) noexcept { + return object.raw_; + } + template + static T wrap(R *raw) noexcept { + return T(raw); + } + template + static void release(T &object) noexcept { + object.raw_ = nullptr; + } +}; + +inline c_buf none() noexcept { + return c_buf{nullptr, 0, nullptr}; +} + +// An object Rust lends a closure for one call, as its class over the lent handle, which +// it gives back unfreed. Moving out of it would keep the borrow past the call. +template +class lent { + T object_; + R *raw_; + +public: + explicit lent(R *raw) noexcept + : object_(access::wrap(const_cast<::std::remove_const_t *>(raw))), raw_(raw) {} + lent(const lent &) = delete; + lent &operator=(const lent &) = delete; + ~lent() { + if (access::raw(object_) != raw_) { + fail("a lent object was moved out of"); + } + access::release(object_); + } + + T &get() noexcept { + return object_; + } +}; + +template +class driver final : public task_node { + enum : int { idle, queued, running, done }; + + ::std::mutex mutex_; + // Null once the future finished or was cancelled. + typename Op::raw *raw_; + Exec exec_; + F f_; + ::std::atomic state_{idle}; + // Whether a wake landed while it polled, so it polls again. + ::std::atomic woken_{false}; + // The thread running its poll and callback, if any. + ::std::atomic<::std::thread::id> on_{}; + // Whether Rust holds a reference from the first poll, which it reuses. + bool given_ = false; + + void post() { + ref(); + exec_([self = ptr(this)]() { self->run(); }); + } + + void run() { + ::std::unique_lock<::std::mutex> lock(mutex_); + if (raw_ == nullptr) { + return; + } + on_.store(::std::this_thread::get_id(), ::std::memory_order_relaxed); + state_.store(running, ::std::memory_order_release); + woken_.store(false, ::std::memory_order_release); + slot out; + c_waker w = given_ ? lend(this) : give(this); + given_ = true; + Op::poll(raw_, w, out); + if (out) { + state_.store(done, ::std::memory_order_release); + Op::free(::std::exchange(raw_, nullptr)); + if constexpr (::std::is_void_v) { + f_(); + } else { + f_(out.take()); + } + } else { + int expect = running; + // A wake during the poll lands in `woken_`: poll again, after what else is queued. + state_.compare_exchange_strong(expect, idle, ::std::memory_order_acq_rel); + if (woken_.exchange(false, ::std::memory_order_acq_rel)) { + wake(); + } + } + on_.store(::std::thread::id(), ::std::memory_order_relaxed); + } + +public: + driver(typename Op::raw *raw, Exec exec, F f) : raw_(raw), exec_(::std::move(exec)), f_(::std::move(f)) {} + + void wake() noexcept override { + int s = state_.load(::std::memory_order_acquire); + for (;;) { + switch (s) { + case idle: + if (state_.compare_exchange_weak(s, queued, ::std::memory_order_acq_rel)) { + post(); + return; + } + break; + case running: + woken_.store(true, ::std::memory_order_release); + // It may have just gone idle, missing the flag. + if (state_.compare_exchange_strong(s, running, ::std::memory_order_acq_rel)) { + return; + } + break; + default: + return; + } + } + } + + void cancel() noexcept override { + // From its own callback, the future is already gone. + if (on_.load(::std::memory_order_relaxed) != ::std::this_thread::get_id()) { + ::std::lock_guard<::std::mutex> lock(mutex_); + state_.store(done, ::std::memory_order_release); + Op::free(::std::exchange(raw_, nullptr)); + } + unref(); + } +}; + +template +void spawn(task &slot, typename Op::raw *raw, Exec exec, F f) { + auto *d = new driver(raw, ::std::move(exec), ::std::move(f)); + slot = task(); + slot.node_ = d; + d->wake(); +} + +} // namespace detail + +template +void future::poll_into(const waker &w, detail::slot &out) { + detail::node *n = detail::access::raw(w); + detail::c_waker raw = n == last_ ? detail::lend(n) : detail::give(n); + last_ = n; + Op::poll(raw_, raw, out); +} + +template +poll_t::output> future::poll(const waker &w) { + detail::slot out; + poll_into(w, out); + return out.release(); +} + +template +typename future::output future::get() && { + struct parker { + ::std::mutex mutex; + ::std::condition_variable cv; + bool woken = false; + }; + auto p = ::std::make_shared(); + waker w([p]() { + { + ::std::lock_guard<::std::mutex> lock(p->mutex); + p->woken = true; + } + p->cv.notify_one(); + }); + for (;;) { + { + // Before the poll, so a wake that lands between its pending and the wait is kept. + ::std::lock_guard<::std::mutex> lock(p->mutex); + p->woken = false; + } + detail::slot out; + poll_into(w, out); + if (out) { + return out.take(); + } + ::std::unique_lock<::std::mutex> lock(p->mutex); + p->cv.wait(lock, [&]() { return p->woken; }); + } +} + +template +template +task future::then(Exec exec, F f) && { + task t; + detail::spawn(t, ::std::exchange(raw_, nullptr), ::std::move(exec), ::std::move(f)); + return t; +} + +#if defined(__cpp_impl_coroutine) && __cpp_impl_coroutine >= 201902L && __has_include() +namespace detail { + +template +class awaiter { + typename Op::raw *raw_; + Exec exec_; + slot out_; + task task_; + +public: + awaiter(typename Op::raw *raw, Exec exec) : raw_(raw), exec_(::std::move(exec)) {} + awaiter(const awaiter &) = delete; + awaiter &operator=(const awaiter &) = delete; + ~awaiter() { + Op::free(raw_); + } + + bool await_ready() const noexcept { + return false; + } + + void await_suspend(::std::coroutine_handle<> h) { + // The task is in place before the first poll, which may resume the coroutine and + // destroy this from the executor's thread. + spawn(task_, ::std::exchange(raw_, nullptr), ::std::move(exec_), [this, h](auto &&...value) { + out_.emplace(::std::forward(value)...); + h.resume(); + }); + } + + typename Op::output await_resume() { + return out_.take(); + } +}; + +} // namespace detail + +template +template +auto future::via(Exec exec) && { + return detail::awaiter(::std::exchange(raw_, nullptr), ::std::move(exec)); +} +#endif diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 5e7de9108..59c24bfe7 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -417,7 +417,11 @@ impl<'a> Abi<'a> { .map(|r| r.span) .or_else(|| api.objects.first().map(|o| o.span)) .unwrap_or(rustc_span::DUMMY_SP); - for runtime in ["contract", "buf", "buf_free", "duration", "waker", "poll"] { + // C's runtime, then what C++'s adds in the namespace its types share. + for runtime in [ + "contract", "buf", "buf_free", "duration", "waker", "poll", "view", "result", "task", "future", "poll_t", + "detail", + ] { self.claim(self.rt(runtime), "the runtime".to_string(), crate_span); } for constant in ["CONTRACT", "POLL_PENDING", "POLL_READY", "POLL_ERROR"] { @@ -449,7 +453,8 @@ impl<'a> Abi<'a> { let plain = e.plain(); if !plain { self.claim(format!("{name}_tag"), what.clone(), e.span); - for variant in e.variants.iter().filter(|v| !v.fields.is_empty()) { + // Each variant's payload, which C++ names even when it has no fields. + for variant in &e.variants { self.claim(format!("{name}_{}", snake(&variant.name)), what.clone(), e.span); } } @@ -601,13 +606,108 @@ pub fn snake(name: &str) -> String { out } -/// A name that C would read as a keyword, with `_` appended. +/// A name that C or C++, which includes the header, would read as a keyword, with `_` +/// prepended. pub fn escape(name: &str) -> String { const KEYWORDS: &[&str] = &[ - "auto", "bool", "break", "case", "char", "const", "continue", "default", "do", "double", "else", "enum", - "extern", "false", "float", "for", "goto", "if", "inline", "int", "long", "register", "restrict", "return", - "short", "signed", "sizeof", "static", "struct", "switch", "true", "typedef", "union", "unsigned", "void", - "volatile", "while", "out", "err", "future", "waker", "data", + "auto", + "bool", + "break", + "case", + "char", + "const", + "continue", + "default", + "do", + "double", + "else", + "enum", + "extern", + "false", + "float", + "for", + "goto", + "if", + "inline", + "int", + "long", + "register", + "restrict", + "return", + "short", + "signed", + "sizeof", + "static", + "struct", + "switch", + "true", + "typedef", + "union", + "unsigned", + "void", + "volatile", + "while", + "out", + "err", + "future", + "waker", + "data", + "alignas", + "alignof", + "and", + "and_eq", + "asm", + "bitand", + "bitor", + "catch", + "char8_t", + "char16_t", + "char32_t", + "class", + "compl", + "concept", + "consteval", + "constexpr", + "constinit", + "const_cast", + "co_await", + "co_return", + "co_yield", + "decltype", + "delete", + "dynamic_cast", + "explicit", + "export", + "friend", + "mutable", + "namespace", + "new", + "noexcept", + "not", + "not_eq", + "nullptr", + "operator", + "or", + "or_eq", + "private", + "protected", + "public", + "reinterpret_cast", + "requires", + "static_assert", + "static_cast", + "template", + "this", + "thread_local", + "throw", + "try", + "typeid", + "typename", + "using", + "virtual", + "wchar_t", + "xor", + "xor_eq", ]; // `out0`, `out1`, ... are a returned tuple's. let out = name diff --git a/ffi/src/c.rs b/ffi/src/c.rs index da479cdfd..02a800884 100644 --- a/ffi/src/c.rs +++ b/ffi/src/c.rs @@ -53,39 +53,8 @@ impl Header<'_> { self.out.push('\n'); } - /// `ty` declaring `name`: a parameter, field, or, with an empty name, a type. fn decl(&self, ty: &Ty, name: &str) -> String { - let space = |t: &str| match name.is_empty() { - true => t.to_string(), - false => format!("{t} {name}"), - }; - match ty { - Ty::Void => space("void"), - Ty::Bool => space("bool"), - Ty::Int(int) => space(c_int(*int)), - Ty::F32 => space("float"), - Ty::F64 => space("double"), - Ty::Char => space("uint32_t"), - Ty::Buf => space(&self.abi.rt("buf")), - Ty::Duration => space(&self.abi.rt("duration")), - Ty::Struct(n) | Ty::Enum(n) => space(n), - Ty::Handle { name: n, constant } => match constant { - true => format!("const {n} *{name}"), - false => format!("{n} *{name}"), - }, - Ty::Future(n) => format!("{n} *{name}"), - Ty::Waker => space(&self.abi.rt("waker")), - Ty::Poll => space(&self.abi.rt("poll")), - Ty::Out(inner) => self.decl(inner, &format!("*{name}")), - Ty::In(inner) => format!("const {}", self.decl(inner, &format!("*{name}"))), - Ty::Fn(params, ret) => { - let params: Vec = std::iter::once("void *data".to_string()) - .chain(params.iter().map(|p| self.decl(p, ""))) - .collect(); - self.decl(ret, &format!("(*{name})({})", params.join(", "))) - } - Ty::Data => format!("void *{name}"), - } + decl(self.abi, ty, name) } fn prototype(&self, sig: &Sig) -> String { @@ -437,6 +406,41 @@ impl Header<'_> { } } +/// `ty` declaring `name`: a parameter, field, or, with an empty name, a type. +pub fn decl(abi: &Abi<'_>, ty: &Ty, name: &str) -> String { + let space = |t: &str| match name.is_empty() { + true => t.to_string(), + false => format!("{t} {name}"), + }; + match ty { + Ty::Void => space("void"), + Ty::Bool => space("bool"), + Ty::Int(int) => space(c_int(*int)), + Ty::F32 => space("float"), + Ty::F64 => space("double"), + Ty::Char => space("uint32_t"), + Ty::Buf => space(&abi.rt("buf")), + Ty::Duration => space(&abi.rt("duration")), + Ty::Struct(n) | Ty::Enum(n) => space(n), + Ty::Handle { name: n, constant } => match constant { + true => format!("const {n} *{name}"), + false => format!("{n} *{name}"), + }, + Ty::Future(n) => format!("{n} *{name}"), + Ty::Waker => space(&abi.rt("waker")), + Ty::Poll => space(&abi.rt("poll")), + Ty::Out(inner) => decl(abi, inner, &format!("*{name}")), + Ty::In(inner) => format!("const {}", decl(abi, inner, &format!("*{name}"))), + Ty::Fn(params, ret) => { + let params: Vec = std::iter::once("void *data".to_string()) + .chain(params.iter().map(|p| decl(abi, p, ""))) + .collect(); + decl(abi, ret, &format!("(*{name})({})", params.join(", "))) + } + Ty::Data => format!("void *{name}"), + } +} + /// A C comment holding `docs`, each line indented by `indent`, or nothing for none. fn comment(docs: &str, indent: &str) -> String { if docs.is_empty() { diff --git a/ffi/src/cpp.rs b/ffi/src/cpp.rs new file mode 100644 index 000000000..96257c29d --- /dev/null +++ b/ffi/src/cpp.rs @@ -0,0 +1,1295 @@ +//! The C++ header: header-only classes over the C header's declarations, from C++17, with +//! exceptions and RTTI on or off. +//! +//! Each name is its C name without the prefix, in a namespace of the prefix: `moq_track` +//! is `moq::track`, and a method is its C name without its type's (`moq_track_close` is +//! `moq::track::close`). C names are unique, so these are too, once a keyword, or a member +//! named as its class or a field, takes a trailing `_`. An object is a move-only class +//! owning its handle, copyable if `Clone`; a record a struct; an enum an `enum class`, or +//! for one with data a `std::variant` of a struct per variant, with its methods free +//! functions; a closure lent for the call a template parameter. The runtime they share, +//! [`runtime/rt.hpp`](../runtime/rt.hpp), holds the bytes, results, wakers, and futures. + +use std::collections::BTreeSet; + +use crate::abi::{self, Abi, Ty}; +use crate::c::decl; +use crate::ir::{Function, Int, Literal, Receiver, Traits, Type}; + +const RUNTIME: &str = include_str!("../runtime/rt.hpp"); + +/// The header for `abi`, as `.hpp`, or the members two items name alike. +pub fn header(abi: &Abi<'_>, packages: &str) -> Result { + let mut h = Header { + abi, + ns: abi.prefix.clone(), + out: String::new(), + defs: String::new(), + defined: BTreeSet::new(), + errors: Vec::new(), + }; + h.write(packages); + match h.errors.is_empty() { + true => Ok(h.out), + false => Err(h.errors.join("\n")), + } +} + +/// How a method's type holds it. +#[derive(Clone, Copy, PartialEq, Eq)] +enum Owner { + /// A class's member. + Member, + /// A free function whose first parameter is the value: an enum's. + Free, +} + +struct Header<'a> { + abi: &'a Abi<'a>, + ns: String, + /// The declarations, in the order C++ needs them. + out: String, + /// The definitions, after every type is complete. + defs: String, + /// The value types written so far, so each is written after what it holds. + defined: BTreeSet, + errors: Vec, +} + +impl<'a> Header<'a> { + fn line(&mut self, line: impl AsRef) { + self.out.push_str(line.as_ref()); + self.out.push('\n'); + } + + fn def(&mut self, line: impl AsRef) { + self.defs.push_str(line.as_ref()); + self.defs.push('\n'); + } + + /// A C name without the prefix, as C++ names it. + fn name(&self, c: &str) -> String { + escape(&c[self.abi.prefix.len() + 1..]) + } + + /// A C name's C++ name, qualified. + fn q(&self, c: &str) -> String { + format!("::{}::{}", self.ns, self.name(c)) + } + + /// The namespace's `detail`, qualified. + fn d(&self) -> String { + format!("::{}::detail", self.ns) + } + + /// The C++ type of `ty` as a value: a field, or what a function returns, owning what + /// it holds. + fn owned(&self, ty: &Type) -> String { + let abi = self.abi; + match ty { + Type::Unit => "void".to_string(), + Type::Bool => "bool".to_string(), + Type::Int(int) => cpp_int(*int).to_string(), + Type::F32 => "float".to_string(), + Type::F64 => "double".to_string(), + Type::Char => "char32_t".to_string(), + Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes => format!("::{}::buf", self.ns), + Type::Duration => format!("::{}::duration", self.ns), + Type::Waker => format!("::{}::waker", self.ns), + Type::Option(inner) => format!("::std::optional<{}>", self.owned(inner)), + Type::Box(inner) | Type::Ref(_, inner) => self.owned(inner), + Type::Record(i) => self.q(&abi.record(*i)), + Type::Enum(i) => self.q(&abi.enumeration(*i)), + Type::Object(i) => self.q(&abi.object(*i)), + Type::Callback(i, _) => format!("::std::unique_ptr<{}>", self.q(&abi.callback(*i))), + Type::Closure(..) => unreachable!("a closure is a template parameter"), + Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => self.q(&abi.range(ty)), + Type::Tuple(elements) => { + let elements: Vec = elements.iter().map(|e| self.owned(e)).collect(); + format!("::std::tuple<{}>", elements.join(", ")) + } + } + } + + /// The C++ type of a parameter of type `ty`. + fn param(&self, ty: &Type) -> String { + let abi = self.abi; + if Abi::is_buf(ty) { + return format!("::{}::view", self.ns); + } + match ty { + Type::Option(inner) if Abi::is_buf(inner) => format!("::std::optional<::{}::view>", self.ns), + Type::Option(inner) => match &**inner { + // Lent, or copied out: a pointer, null for none. + Type::Ref(m, object) if matches!(**object, Type::Object(_)) => { + let constant = match m { + crate::ir::Mutability::Not => "const ", + crate::ir::Mutability::Mut => "", + }; + format!("{constant}{} *", self.owned(object)) + } + Type::Object(i) if abi.api.objects[*i].copy => format!("const {} *", self.owned(inner)), + // Moved out of, as a handle taken by value is. + _ if matches!(inner.base(), Type::Object(_)) => format!("::std::optional<{}>", self.owned(inner)), + _ => format!("const ::std::optional<{}> &", self.owned(inner)), + }, + Type::Waker => format!("const ::{}::waker &", self.ns), + Type::Ref(m, inner) if matches!(**inner, Type::Object(_)) => match m { + crate::ir::Mutability::Not => format!("const {} &", self.owned(inner)), + crate::ir::Mutability::Mut => format!("{} &", self.owned(inner)), + }, + Type::Ref(_, inner) | Type::Box(inner) => self.param(inner), + Type::Object(i) if abi.api.objects[*i].copy => format!("const {} &", self.owned(ty)), + Type::Record(_) | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => { + format!("const {} &", self.owned(ty)) + } + Type::Enum(i) if !abi.api.enums[*i].plain() => format!("const {} &", self.owned(ty)), + ty => self.owned(ty), + } + } + + /// The C value of the C++ value `e` of type `ty`, as a parameter or a field passes it. + fn lower(&self, ty: &Type, e: &str) -> String { + let abi = self.abi; + let d = self.d(); + let ns = &self.ns; + if Abi::is_buf(ty) { + return format!("{d}::access::raw(::{ns}::view({e}))"); + } + match ty { + Type::Unit => unreachable!("no value is unit"), + Type::Bool | Type::Int(_) | Type::F32 | Type::F64 => e.to_string(), + Type::Char => format!("static_cast({e})"), + Type::Duration | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => e.to_string(), + Type::Waker => format!("{d}::give({d}::access::raw({e}))"), + Type::Option(inner) => match inner.base() { + Type::Object(_) => format!("({e} ? {d}::access::raw(*{e}) : nullptr)"), + // Through a view, so an empty buffer C++ made crosses as `Some`, not as null. + _ if Abi::is_buf(inner) => format!("({e} ? {d}::access::raw(::{ns}::view(*{e})) : {d}::none())"), + _ => { + let c = abi.option(inner); + let value = self.lower(inner, &format!("(*{e})")); + format!("({e} ? ::{c}{{true, {value}}} : ::{c}{{}})") + } + }, + Type::Box(inner) | Type::Ref(_, inner) => self.lower(inner, e), + Type::Record(_) => format!("{d}::lower({e})"), + Type::Enum(i) => match abi.api.enums[*i].plain() { + true => format!("static_cast<::{}>({e})", abi.enumeration(*i)), + false => format!("{d}::lower({e})"), + }, + Type::Object(_) => format!("{d}::access::raw({e})"), + Type::Callback(..) => format!("{d}::lower(::std::move({e}))"), + Type::Closure(..) => unreachable!("a closure lowers to its trampoline"), + Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes => unreachable!("a buffer is above"), + Type::Tuple(_) => unreachable!("a tuple is only returned"), + } + } + + /// The C++ value of the C value `e` of type `ty`, which it takes ownership of. `e` is + /// named, so it may be read more than once. + fn lift(&self, ty: &Type, e: &str) -> String { + let abi = self.abi; + let d = self.d(); + if Abi::is_buf(ty) { + return format!("{d}::access::adopt({e})"); + } + match ty { + Type::Bool | Type::Int(_) | Type::F32 | Type::F64 => e.to_string(), + Type::Char => format!("static_cast({e})"), + Type::Duration | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => e.to_string(), + Type::Option(inner) => { + let owned = self.owned(inner); + match inner.base() { + Type::Object(_) => { + format!("({e} ? ::std::optional<{owned}>({d}::access::wrap<{owned}>({e})) : ::std::nullopt)") + } + _ if Abi::is_buf(inner) => format!("{d}::access::adopt_option({e})"), + _ => format!( + "({e}.some ? ::std::optional<{owned}>({}) : ::std::nullopt)", + self.lift(inner, &format!("{e}.value")) + ), + } + } + Type::Box(inner) | Type::Ref(_, inner) => self.lift(inner, e), + Type::Record(_) => format!("{d}::lift({e})"), + Type::Enum(i) => match abi.api.enums[*i].plain() { + true => format!("static_cast<{}>({e})", self.owned(ty)), + false => format!("{d}::lift({e})"), + }, + Type::Object(_) => format!("{d}::access::wrap<{}>({e})", self.owned(ty)), + other => unreachable!("{other:?} is never returned"), + } + } + + /// The C++ type of a callback's parameter of type `ty`, lent for the call. + fn lent(&self, ty: &Type) -> String { + match ty { + ty if Abi::is_buf(ty) => format!("::{}::view", self.ns), + Type::Option(inner) => format!("::std::optional<{}>", self.lent(inner)), + ty => self.owned(ty), + } + } + + /// The C++ value of a callback's C parameter `e` of type `ty`, lent for the call. + fn lift_lent(&self, ty: &Type, e: &str) -> String { + match ty { + ty if Abi::is_buf(ty) => format!("::{}::view({e}.ptr, {e}.len)", self.ns), + Type::Option(inner) if Abi::is_buf(inner) => format!( + "({e}.ptr ? ::std::optional<::{ns}::view>(::{ns}::view({e}.ptr, {e}.len)) : ::std::nullopt)", + ns = self.ns + ), + Type::Option(inner) => format!( + "({e}.some ? ::std::optional<{}>({}) : ::std::nullopt)", + self.lent(inner), + self.lift_lent(inner, &format!("{e}.value")) + ), + ty => self.lift(ty, e), + } + } + + fn write(&mut self, packages: &str) { + let abi = self.abi; + let api = abi.api; + let p = abi.prefix.clone(); + let ns = self.ns.clone(); + let guard = format!("{}_HPP", p.to_uppercase()); + self.line(format!( + "// Generated by rust2-ffi: C++ over the C ABI of the pub API of {packages}. Do not edit.\n" + )); + self.line(format!("#ifndef {guard}\n#define {guard}\n")); + self.line(format!("#include \"{p}.h\"\n")); + for include in [ + "atomic", + "condition_variable", + "cstddef", + "cstdint", + "cstdio", + "cstdlib", + "cstring", + "memory", + "mutex", + "optional", + "string_view", + "thread", + "tuple", + "type_traits", + "utility", + "variant", + ] { + self.line(format!("#include <{include}>")); + } + self.line( + "#if defined(__cpp_impl_coroutine) && __cpp_impl_coroutine >= 201902L && __has_include()\n#include \n#endif\n", + ); + self.line(format!("namespace {ns} {{\n")); + self.line(format!( + "namespace detail {{\n\nusing c_buf = ::{p}_buf;\nusing c_waker = ::{p}_waker;\n\ninline void c_buf_free(c_buf buf) noexcept {{\n\t::{p}_buf_free(buf);\n}}\n\n}} // namespace detail\n" + )); + self.out.push_str(RUNTIME); + self.line(format!( + "\nnamespace detail {{\n\n// Checked at load, before any other call: a header and a library from different builds\n// must not mix.\ninline const bool contract = ::{p}_contract() == {upper}_CONTRACT ||\n\t(fail(\"{p}.hpp and the library are from different builds\"), false);\n\n}} // namespace detail\n", + upper = p.to_uppercase() + )); + self.line(format!("using duration = ::{p}_duration;")); + if abi.ranges.values().any(|ty| matches!(ty, Type::Bound(_))) { + self.line(format!("using bound = ::{};", abi.rt("bound"))); + } + for name in abi.ranges.keys() { + self.line(format!("using {} = ::{name};", self.name(name))); + } + self.line(""); + + // Plain enums, complete at once. + for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| e.plain()) { + let name = self.name(&abi.enumeration(i)); + let variants: Vec = e + .variants + .iter() + .map(|v| format!("\t{} = {},", escape(&abi::snake(&v.name)), v.discriminant)) + .collect(); + self.line(format!( + "{}enum class {name} {{\n{}\n}};\n", + docs(&e.docs, ""), + variants.join("\n") + )); + } + + // Every class and struct, declared so any signature may name it. + for i in 0..api.records.len() { + self.line(format!("struct {};", self.name(&abi.record(i)))); + } + for i in 0..api.objects.len() { + self.line(format!("class {};", self.name(&abi.object(i)))); + } + for i in 0..api.callbacks.len() { + self.line(format!("class {};", self.name(&abi.callback(i)))); + } + for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| !e.plain()) { + let name = abi.enumeration(i); + let payloads: Vec = e + .variants + .iter() + .map(|v| self.name(&format!("{name}_{}", abi::snake(&v.name)))) + .collect(); + for payload in &payloads { + self.line(format!("struct {payload};")); + } + self.line(format!( + "{}using {} = ::std::variant<{}>;", + docs(&e.docs, ""), + self.name(&name), + payloads.join(", ") + )); + } + self.line(""); + + // Each future's type, by the operations it polls with. + let futures = self.functions(); + for (function, owner) in &futures { + let export = abi.export(function, owner.as_ref()); + if let Some((handle, _, _)) = &export.future { + let name = self.name(handle); + self.line(format!( + "namespace detail {{\nstruct {name}_op;\n}}\nusing {name} = ::{ns}::future;" + )); + } + } + self.line(""); + + for constant in &api.constants { + let ty = match constant.value { + Literal::Bool(_) => "bool", + Literal::Int(int, _) => cpp_int(int), + }; + self.line(format!( + "{}inline constexpr {ty} {} = {};", + docs(&constant.docs, ""), + self.name(&abi.name(&constant.path)), + abi.constant(&constant.path) + )); + } + if !api.constants.is_empty() { + self.line(""); + } + + for i in 0..api.objects.len() { + self.object(i); + } + for i in 0..api.callbacks.len() { + self.callback(i); + } + + // Value types, each after the values it holds. + for i in 0..api.records.len() { + self.value(&Type::Record(i)); + } + for (i, e) in api.enums.iter().enumerate() { + match e.plain() { + true => self.enumeration(i), + false => self.value(&Type::Enum(i)), + } + } + + self.conversions(); + for (function, owner) in &futures { + self.future(function, owner.as_ref()); + } + + let defs = std::mem::take(&mut self.defs); + self.out.push_str(&defs); + for function in &api.functions { + self.function(function, None, None); + } + let defs = std::mem::take(&mut self.defs); + self.out.push_str(&defs); + self.line(format!("}} // namespace {ns}\n")); + self.line(format!("#endif // {guard}")); + } + + /// Every exported function, with the C type of its owner if a method. + fn functions(&self) -> Vec<(&'a Function, Option)> { + let abi = self.abi; + let api = abi.api; + let mut functions = Vec::new(); + for (i, record) in api.records.iter().enumerate() { + let owner = Ty::Struct(abi.record(i)); + functions.extend(record.methods.iter().map(|m| (m, Some(owner.clone())))); + } + for (i, e) in api.enums.iter().enumerate() { + let owner = abi.ty(&Type::Enum(i)); + functions.extend(e.methods.iter().map(|m| (m, Some(owner.clone())))); + } + for (i, object) in api.objects.iter().enumerate() { + let owner = Ty::Handle { + name: abi.object(i), + constant: false, + }; + functions.extend(object.methods.iter().map(|m| (m, Some(owner.clone())))); + } + functions.extend(api.functions.iter().map(|f| (f, None))); + functions + } + + /// The member name of the C function `c` of the type named `owner` in C, kept apart from + /// the class's name and its fields. + fn member(&self, c: &str, owner: &str, taken: &[String]) -> String { + let bare = match c.strip_prefix(owner).and_then(|rest| rest.strip_prefix('_')) { + Some(rest) => escape(rest), + None => self.name(c), + }; + match taken.contains(&bare) { + true => format!("{bare}_"), + false => bare, + } + } + + /// Check that no two members of `class`, the Rust type `rust`, share a name. + fn distinct(&mut self, class: &str, rust: &str, members: &[String]) { + let mut seen = BTreeSet::new(); + for member in members { + if !seen.insert(member) { + self.errors.push(format!( + "two members of `{rust}` are both `{}::{class}::{member}` in C++: rename one in the config", + self.ns + )); + } + } + } + + fn object(&mut self, i: usize) { + let abi = self.abi; + let object = &abi.api.objects[i]; + let c = abi.object(i); + let name = self.name(&c); + let t = object.traits; + let text = format!("{}\n\n{}", abi.api.rust(&object.path, &object.args), object.docs); + let mut body = vec![ + format!("\t::{c} *raw_;\n"), + format!("\texplicit {name}(::{c} *raw) noexcept : raw_(raw) {{}}\n"), + format!("\tfriend struct {}::access;\n", self.d()), + "public:".to_string(), + format!( + "\t{name}({name} &&other) noexcept : raw_(::std::exchange(other.raw_, nullptr)) {{}}\n\t{name} &operator=({name} &&other) noexcept {{\n\t\t::std::swap(raw_, other.raw_);\n\t\treturn *this;\n\t}}\n\t~{name}() {{\n\t\t::{c}_free(raw_);\n\t}}" + ), + ]; + if t.clone { + body.push(format!( + "\t{name}(const {name} &other) : raw_(::{c}_clone(other.raw_)) {{}}\n\t{name} &operator=(const {name} &other) {{\n\t\tif (this != &other) {{\n\t\t\t*this = {name}(other);\n\t\t}}\n\t\treturn *this;\n\t}}" + )); + } else { + body.push(format!( + "\t{name}(const {name} &) = delete;\n\t{name} &operator=(const {name} &) = delete;" + )); + } + if t.eq { + body.push(format!( + "\tfriend bool operator==(const {name} &a, const {name} &b) {{\n\t\treturn ::{c}_eq(a.raw_, b.raw_);\n\t}}\n\tfriend bool operator!=(const {name} &a, const {name} &b) {{\n\t\treturn !(a == b);\n\t}}" + )); + } + let mut members = Vec::new(); + self.traits(&name, &c, t, true, &mut body, &mut members); + let owner = Ty::Handle { + name: c.clone(), + constant: false, + }; + let taken = vec![name.clone()]; + for method in &object.methods { + let (decl, member) = self.function(method, Some(&owner), Some((&taken, Owner::Member))); + body.push(decl); + members.push(member); + } + self.distinct(&name, &abi.api.rust(&object.path, &object.args), &members); + self.line(format!( + "{}class {name} {{\n{}\n}};\n", + docs(text.trim(), ""), + body.join("\n") + )); + } + + /// The members a type's std traits export beyond its operators: an object's, which + /// holds a handle, or a record's, which is lowered. + fn traits( + &mut self, + name: &str, + c: &str, + t: Traits, + object: bool, + body: &mut Vec, + members: &mut Vec, + ) { + let ns = self.ns.clone(); + let d = self.d(); + let (this, lower) = match object { + true => ("raw_", String::new()), + false => ("&c_self_", format!("\tauto c_self_ = {d}::lower(*this);\n")), + }; + if t.display { + body.push(format!("\t::{ns}::buf to_string() const;")); + members.push("to_string".to_string()); + self.def(format!( + "inline ::{ns}::buf {name}::to_string() const {{\n{lower}\treturn {d}::access::adopt(::{c}_to_string({this}));\n}}\n" + )); + } + if t.debug { + body.push(format!("\t::{ns}::buf debug() const;")); + members.push("debug".to_string()); + self.def(format!( + "inline ::{ns}::buf {name}::debug() const {{\n{lower}\treturn {d}::access::adopt(::{c}_debug({this}));\n}}\n" + )); + } + if t.default { + body.push(format!("\tstatic {name} default_();")); + members.push("default_".to_string()); + let make = match object { + true => format!("{d}::access::wrap<{name}>(c_ret_)"), + false => format!("{d}::lift(c_ret_)"), + }; + self.def(format!( + "inline {name} {name}::default_() {{\n\tauto c_ret_ = ::{c}_default();\n\treturn {make};\n}}\n" + )); + } + } + + fn callback(&mut self, i: usize) { + let abi = self.abi; + let callback = &abi.api.callbacks[i]; + let c = abi.callback(i); + let name = self.name(&c); + let text = format!( + "{}: implemented in C++. Rust deletes it once it drops the implementation, and may\ncall its methods from any thread.\n\n{}", + callback.path.join("::"), + callback.docs + ); + let mut body = vec!["public:".to_string(), format!("\tvirtual ~{name}() = default;")]; + let mut members = Vec::new(); + let mut trampolines = vec![format!( + "\t\tstatic void free(void *data) noexcept {{\n\t\t\tdelete static_cast<::{}::{name} *>(data);\n\t\t}}", + self.ns + )]; + let mut table = vec!["&t::free".to_string()]; + for (n, method) in callback.methods.iter().enumerate() { + let mut member = escape(method.name()); + if member == name { + member.push('_'); + } + members.push(member.clone()); + let constant = match method.receiver { + Some(Receiver::Mut) => "", + _ => " const", + }; + let params: Vec = method + .params + .iter() + .map(|p| declare(&self.lent(&p.ty), &escape(&p.name))) + .collect(); + body.push(format!( + "{}\tvirtual {} {member}({}){constant} = 0;", + docs(&method.docs, "\t"), + self.owned(&method.ok), + params.join(", ") + )); + let c_params: Vec = std::iter::once("void *data".to_string()) + .chain( + method + .params + .iter() + .enumerate() + .map(|(k, p)| decl(abi, &abi.ty(&p.ty), &format!("p{k}"))), + ) + .collect(); + let args: Vec = method + .params + .iter() + .enumerate() + .map(|(k, p)| self.lift_lent(&p.ty, &format!("p{k}"))) + .collect(); + let call = format!( + "static_cast<::{}::{name}{constant} *>(data)->{member}({})", + self.ns, + args.join(", ") + ); + let ret = match &method.ok { + Type::Unit => format!("{call};"), + ok => format!("return {};", self.lower(ok, &call)), + }; + trampolines.push(format!( + "\t\tstatic {} m{n}({}) noexcept {{\n\t\t\t{ret}\n\t\t}}", + decl(abi, &abi.ty(&method.ok), ""), + c_params.join(", ") + )); + table.push(format!("&t::m{n}")); + } + self.distinct(&name, &callback.path.join("::"), &members); + self.line(format!( + "{}class {name} {{\n{}\n}};\n", + docs(text.trim(), ""), + body.join("\n") + )); + self.def(format!( + "namespace detail {{\n\ninline ::{c} lower(::std::unique_ptr<::{ns}::{name}> impl) {{\n\tif (!impl) {{\n\t\tfail(\"{c}: a null implementation\");\n\t}}\n\tstruct t {{\n{}\n\t}};\n\tstatic const ::{c}_vtable vtable = {{{}}};\n\treturn ::{c}{{&vtable, impl.release()}};\n}}\n\n}} // namespace detail\n", + trampolines.join("\n"), + table.join(", "), + ns = self.ns, + )); + } + + /// A record's struct or a data enum's payloads, after the values they hold. + fn value(&mut self, ty: &Type) { + let abi = self.abi; + let c = match ty { + Type::Record(i) => abi.record(*i), + Type::Enum(i) if !abi.api.enums[*i].plain() => abi.enumeration(*i), + Type::Option(inner) | Type::Box(inner) | Type::Ref(_, inner) => return self.value(inner), + Type::Tuple(elements) => { + for element in elements { + self.value(element); + } + return; + } + _ => return, + }; + if !self.defined.insert(c.clone()) { + return; + } + match ty { + Type::Record(i) => { + let record = &abi.api.records[*i]; + for field in &record.fields { + self.value(&field.ty); + } + let name = self.name(&c); + let fields: Vec = record.fields.iter().map(|f| escape(&f.name)).collect(); + let mut body: Vec = record + .fields + .iter() + .zip(&fields) + .map(|(f, field)| format!("{}\t{} {field}{};", docs(&f.docs, "\t"), self.owned(&f.ty), init(&f.ty))) + .collect(); + body.push(String::new()); + let mut members = fields.clone(); + let t = record.traits; + if t.eq { + body.push(format!( + "\tbool operator==(const {name} &other) const;\n\tbool operator!=(const {name} &other) const {{\n\t\treturn !(*this == other);\n\t}}" + )); + self.def(format!( + "inline bool {name}::operator==(const {name} &other) const {{\n\tauto a = {d}::lower(*this);\n\tauto b = {d}::lower(other);\n\treturn ::{c}_eq(&a, &b);\n}}\n", + d = self.d() + )); + } + self.traits(&name, &c, t, false, &mut body, &mut members); + let owner = Ty::Struct(c.clone()); + let mut taken = fields.clone(); + taken.push(name.clone()); + for method in &record.methods { + let (decl, member) = self.function(method, Some(&owner), Some((&taken, Owner::Member))); + body.push(decl); + members.push(member); + } + self.distinct(&name, &abi.api.rust(&record.path, &record.args), &members); + while body.last().is_some_and(String::is_empty) { + body.pop(); + } + self.line(format!( + "{}struct {name} {{\n{}\n}};\n", + docs(&record.docs, ""), + body.join("\n") + )); + } + Type::Enum(i) => { + let e = &abi.api.enums[*i]; + for variant in &e.variants { + for field in &variant.fields { + self.value(&field.ty); + } + } + for variant in &e.variants { + let payload = self.name(&format!("{c}_{}", abi::snake(&variant.name))); + let fields: Vec = variant + .fields + .iter() + .map(|f| format!("\t{} {}{};", self.owned(&f.ty), escape(&f.name), init(&f.ty))) + .collect(); + self.line(format!("struct {payload} {{\n{}\n}};\n", fields.join("\n")).replace("{\n\n}", "{}")); + } + self.enumeration(*i); + } + _ => unreachable!(), + } + } + + /// An enum's methods and std traits, as free functions taking it first: C++ enums + /// hold no members. + fn enumeration(&mut self, i: usize) { + let abi = self.abi; + let e = &abi.api.enums[i]; + let c = abi.enumeration(i); + let name = self.name(&c); + let ns = self.ns.clone(); + let ty = Type::Enum(i); + let param = self.param(&ty); + let lifted = self.lift(&ty, "c_ret_"); + let lower = |e: &str| self.lower(&ty, e); + let (a, b, this) = (lower("a"), lower("b"), lower("self")); + let t = e.traits; + if t.eq { + let (a_, b_) = (declare(¶m, "a"), declare(¶m, "b")); + self.def(format!( + "inline bool operator==({a_}, {b_}) {{\n\tauto c_a_ = {a};\n\tauto c_b_ = {b};\n\treturn ::{c}_eq(&c_a_, &c_b_);\n}}\n\ninline bool operator!=({a_}, {b_}) {{\n\treturn !(a == b);\n}}\n" + )); + } + for (on, trait_name) in [(t.display, "to_string"), (t.debug, "debug")] { + if on { + self.def(format!( + "inline ::{ns}::buf {name}_{trait_name}({}) {{\n\tauto c_self_ = {this};\n\treturn {d}::access::adopt(::{c}_{trait_name}(&c_self_));\n}}\n", + declare(¶m, "self"), + d = self.d() + )); + } + } + if t.default { + self.def(format!( + "inline {name} {name}_default() {{\n\tauto c_ret_ = ::{c}_default();\n\treturn {lifted};\n}}\n" + )); + } + let owner = abi.ty(&ty); + for method in &e.methods { + self.function(method, Some(&owner), Some((&[], Owner::Free))); + } + } + + /// Each record's and data enum's conversions to and from C. + fn conversions(&mut self) { + let abi = self.abi; + let api = abi.api; + let ns = self.ns.clone(); + self.line("namespace detail {\n"); + for i in 0..api.records.len() { + let c = abi.record(i); + let name = self.name(&c); + self.line(format!("inline ::{c} lower(const ::{ns}::{name} &v);")); + self.line(format!("inline ::{ns}::{name} lift(const ::{c} &c);")); + } + for (i, _) in api.enums.iter().enumerate().filter(|(_, e)| !e.plain()) { + let c = abi.enumeration(i); + let name = self.name(&c); + self.line(format!("inline ::{c} lower(const ::{ns}::{name} &v);")); + self.line(format!("inline ::{ns}::{name} lift(const ::{c} &c);")); + } + for i in 0..api.callbacks.len() { + let c = abi.callback(i); + let name = self.name(&c); + self.line(format!("inline ::{c} lower(::std::unique_ptr<::{ns}::{name}> impl);")); + } + self.line(""); + for (i, record) in api.records.iter().enumerate() { + let c = abi.record(i); + let name = self.name(&c); + let lowered: Vec = record + .fields + .iter() + .map(|f| self.lower(&f.ty, &format!("v.{}", escape(&f.name)))) + .collect(); + let lifted: Vec = record + .fields + .iter() + .map(|f| self.lift(&f.ty, &format!("c.{}", abi::escape(&f.name)))) + .collect(); + let (v, cc) = match record.fields.is_empty() { + true => ("", ""), + false => (" &v", " &c"), + }; + self.line(format!( + "inline ::{c} lower(const ::{ns}::{name}{v}) {{\n\treturn ::{c}{{{}}};\n}}\n", + lowered.join(", ") + )); + self.line(format!( + "inline ::{ns}::{name} lift(const ::{c}{cc}) {{\n\treturn ::{ns}::{name}{{{}}};\n}}\n", + lifted.join(", ") + )); + } + for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| !e.plain()) { + let c = abi.enumeration(i); + let name = self.name(&c); + let upper = c.to_uppercase(); + let mut lower = Vec::new(); + let mut lift = Vec::new(); + for (n, variant) in e.variants.iter().enumerate() { + let tag = format!("{upper}_{}", abi::snake(&variant.name).to_uppercase()); + let payload = self.name(&format!("{c}_{}", abi::snake(&variant.name))); + let member = abi::escape(&abi::snake(&variant.name)); + let mut set = vec![format!("c.tag = {tag};")]; + let mut fields = Vec::new(); + for field in &variant.fields { + set.push(format!( + "c.{member}.{} = {};", + abi::escape(&field.name), + self.lower(&field.ty, &format!("p.{}", escape(&field.name))) + )); + fields.push(self.lift(&field.ty, &format!("c.{member}.{}", abi::escape(&field.name)))); + } + let bind = match variant.fields.is_empty() { + true => String::new(), + false => format!("const auto &p = *::std::get_if<{n}>(&v);\n\t\t"), + }; + lower.push(format!( + "\tcase {n}: {{\n\t\t{bind}{}\n\t\tbreak;\n\t}}", + set.join("\n\t\t") + )); + lift.push(format!( + "\tcase {tag}:\n\t\treturn ::{ns}::{name}(::std::in_place_index<{n}>, ::{ns}::{payload}{{{}}});", + fields.join(", ") + )); + } + self.line(format!( + "inline ::{c} lower(const ::{ns}::{name} &v) {{\n\t::{c} c{{}};\n\tswitch (v.index()) {{\n{}\n\t}}\n\treturn c;\n}}\n", + lower.join("\n") + )); + self.line(format!( + "inline ::{ns}::{name} lift(const ::{c} &c) {{\n\tswitch (c.tag) {{\n{}\n\t}}\n\tfail(\"{c}: an invalid tag\");\n}}\n", + lift.join("\n") + )); + } + self.line("} // namespace detail\n"); + } + + /// The return type a C++ function or future gives for `function`'s result. + fn output(&self, function: &Function) -> String { + let ok = self.owned(&function.ok); + match &function.err { + Some(err) => format!("::{}::result<{ok}, {}>", self.ns, self.owned(err)), + None => ok, + } + } + + /// Declarations of the out values a C call writes through `outs`, and the C++ value they + /// make, ok then error, for a result `output`. + fn outs(&self, function: &Function, outs: &[(String, Ty)], output: &str) -> (Vec, String, Option) { + let abi = self.abi; + let declared: Vec = outs + .iter() + .map(|(name, ty)| { + let Ty::Out(inner) = ty else { + unreachable!("an out parameter is a pointer") + }; + format!("{}{{}};", decl(abi, inner, &format!("c_{name}_"))) + }) + .collect(); + let owned = strip_refs; + let ok = match &function.ok { + Type::Unit => String::new(), + Type::Tuple(elements) => { + let lifted: Vec = elements + .iter() + .enumerate() + .map(|(n, e)| self.lift(&owned(e), &format!("c_out{n}_"))) + .collect(); + format!("{}({})", self.owned(&function.ok), lifted.join(", ")) + } + ok => self.lift(&owned(ok), "c_out_"), + }; + let ok = match function.err.is_some() { + true => format!("{output}::ok({ok})"), + false => ok, + }; + let err = function + .err + .as_ref() + .map(|err| format!("{output}::err({})", self.lift(&owned(err), "c_err_"))); + (declared, ok, err) + } + + /// `function`'s declaration in its class, and its member name, with its definition + /// among the definitions; or as a free function if it has no class. + fn function( + &mut self, + function: &Function, + owner: Option<&Ty>, + class: Option<(&[String], Owner)>, + ) -> (String, String) { + let abi = self.abi; + let export = abi.export(function, owner); + let d = self.d(); + let owner_c = match owner { + Some(Ty::Struct(n) | Ty::Enum(n) | Ty::Handle { name: n, .. }) => Some(n.clone()), + _ => None, + }; + let member = match (class, &owner_c) { + (Some((taken, Owner::Member)), Some(owner)) => self.member(&export.call.name, owner, taken), + _ => self.name(&export.call.name), + }; + let free = !matches!(class, Some((_, Owner::Member))); + let ret = match &export.future { + Some((handle, _, _)) => self.q(handle), + None => self.output(function), + }; + let mut params: Vec = Vec::new(); + let mut args: Vec = Vec::new(); + let mut prelude = Vec::new(); + let receiver = function.receiver.filter(|_| owner.is_some()); + let mut c_params = export.call.params.iter(); + if receiver.is_some() { + let (_, ty) = c_params.next().expect("a method has its receiver"); + match (ty, free) { + (Ty::Handle { .. }, _) => args.push("raw_".to_string()), + (_, false) => { + prelude.push(format!("auto c_self_ = {d}::lower(*this);")); + args.push("&c_self_".to_string()); + } + (_, true) => { + let ty = enumeration(abi, owner_c.as_deref().expect("a free method has its enum")); + params.push(declare(&self.param(&ty), "self")); + prelude.push(format!("auto c_self_ = {};", self.lower(&ty, "self"))); + args.push("&c_self_".to_string()); + } + } + } + let mut templates = Vec::new(); + for param in &function.params { + let (_, c_ty) = c_params.next().expect("each parameter has its C one"); + let name = escape(¶m.name); + if let (Type::Closure(lent, ret), Ty::Fn(c_lent, c_ret)) = (¶m.ty, c_ty) { + c_params.next().expect("a closure has its data"); + let f = format!("F{}", templates.len()); + params.push(format!("{f} &&{name}")); + prelude.push(self.closure(&f, &name, (lent, ret), (c_lent, c_ret))); + args.push(format!("c_{name}_")); + args.push(format!( + "const_cast(static_cast(::std::addressof({name})))" + )); + templates.push(format!("class {f}")); + continue; + } + params.push(declare(&self.param(¶m.ty), &name)); + args.push(self.lower(¶m.ty, &name)); + } + let outs: Vec<(String, Ty)> = c_params.cloned().collect(); + for (name, _) in &outs { + args.push(format!("&c_{name}_")); + } + let call = format!("::{}({})", export.call.name, args.join(", ")); + let mut body = prelude; + if let Some((handle, _, _)) = &export.future { + body.push(format!("return {d}::access::wrap<{}>({call});", self.q(handle))); + } else { + let (declared, ok, err) = self.outs(function, &outs, &ret); + body.extend(declared); + match (&function.err, &function.ok) { + (Some(_), _) => { + body.push(format!("if ({call}) {{\n\t\treturn {ok};\n\t}}")); + body.push(format!("return {};", err.expect("an error lifts"))); + } + (None, Type::Tuple(_)) => { + body.push(format!("{call};")); + body.push(format!("return {ok};")); + } + (None, Type::Unit) => body.push(format!("{call};")), + (None, ok_ty) => { + body.push(format!("auto c_out_ = {call};")); + let lifted = self.lift(&strip_refs(ok_ty), "c_out_"); + body.push(format!("return {lifted};")); + } + } + } + let qualifier = match (receiver, free) { + (_, true) | (None, _) => String::new(), + (Some(Receiver::Ref), _) => " const".to_string(), + (Some(Receiver::Mut), _) => String::new(), + (Some(Receiver::Owned), _) => match owner { + Some(Ty::Handle { name, .. }) if !copy(abi, name) => " &&".to_string(), + _ => " const".to_string(), + }, + }; + let is_static = receiver.is_none() && !free; + let class_name = owner_c.as_deref().map(|c| self.name(c)); + let scope = match (&class_name, free) { + (Some(class), false) => format!("{class}::"), + _ => String::new(), + }; + let template = match templates.is_empty() { + true => String::new(), + false => format!("template <{}>\n", templates.join(", ")), + }; + self.def(format!( + "{template}inline {ret} {scope}{member}({}){qualifier} {{\n\t{}\n}}\n", + params.join(", "), + body.join("\n\t") + )); + let mut text = function.docs.clone(); + for param in &function.params { + if let Type::Closure(lent, _) = ¶m.ty { + let name = escape(¶m.name); + text.push_str(&format!( + "\n\nRust calls `{name}` only during the call, from any thread." + )); + if lent.iter().any(|p| matches!(p.base(), Type::Object(_))) { + text.push_str(&format!( + "\nAn object it lends lives only for that call of `{name}`: move none out of it." + )); + } + } + } + let declaration = format!( + "{}\t{}{}{ret} {member}({}){qualifier};", + docs(text.trim(), "\t"), + template.replace('\n', "\n\t"), + match is_static { + true => "static ", + false => "", + }, + params.join(", ") + ); + (declaration, member) + } + + /// The trampoline C calls for the closure parameter `name`, of type `f`, taking `lent` + /// and returning `ret`, which C declares as `c_lent` and `c_ret`: it lends each object + /// as its class. + fn closure(&self, f: &str, name: &str, (lent, ret): (&[Type], &Type), (c_lent, c_ret): (&[Ty], &Ty)) -> String { + let abi = self.abi; + let d = self.d(); + let c_params: Vec = std::iter::once("void *data".to_string()) + .chain(c_lent.iter().enumerate().map(|(k, ty)| decl(abi, ty, &format!("p{k}")))) + .collect(); + let mut body = vec![format!( + "auto &f = *static_cast<::std::remove_reference_t<{f}> *>(data);" + )]; + let mut args = Vec::new(); + for (k, (ty, c_ty)) in lent.iter().zip(c_lent).enumerate() { + let p = format!("p{k}"); + match (ty, c_ty) { + (Type::Ref(m, object), Ty::Handle { name: c, constant }) => { + let constant = match constant { + true => "const ", + false => "", + }; + body.push(format!("{d}::lent<{}, {constant}::{c}> l{k}({p});", self.owned(object))); + args.push(match m { + crate::ir::Mutability::Not => format!("::std::as_const(l{k}.get())"), + crate::ir::Mutability::Mut => format!("l{k}.get()"), + }); + } + _ => args.push(self.lift_lent(ty, &p)), + } + } + let call = format!("f({})", args.join(", ")); + body.push(match ret { + Type::Unit => format!("{call};"), + ret => format!("return {};", self.lower(ret, &call)), + }); + format!( + "auto c_{name}_ = []({}) noexcept -> {} {{\n\t\t{}\n\t}};", + c_params.join(", "), + decl(abi, c_ret, ""), + body.join("\n\t\t") + ) + } + + /// The operations a future's type polls with. + fn future(&mut self, function: &Function, owner: Option<&Ty>) { + let abi = self.abi; + let export = abi.export(function, owner); + let Some((handle, poll, free)) = &export.future else { + return; + }; + let name = self.name(handle); + let output = self.output(function); + let outs: Vec<(String, Ty)> = poll.params[2..].to_vec(); + let (declared, ok, err) = self.outs(function, &outs, &output); + let ok = match (&function.err, &function.ok) { + (None, Type::Unit) => "out.emplace();".to_string(), + _ => format!("out.emplace({ok});"), + }; + let mut args = vec!["f".to_string(), "w".to_string()]; + args.extend(outs.iter().map(|(name, _)| format!("&c_{name}_"))); + let upper = abi.prefix.to_uppercase(); + let mut cases = vec![format!("\t\tcase {upper}_POLL_READY:\n\t\t\t{ok}\n\t\t\tbreak;")]; + if let Some(err) = err { + cases.push(format!( + "\t\tcase {upper}_POLL_ERROR:\n\t\t\tout.emplace({err});\n\t\t\tbreak;" + )); + } + cases.push("\t\tdefault:\n\t\t\tbreak;".to_string()); + let declared: String = declared.iter().map(|d| format!("\t\t{d}\n")).collect(); + self.line(format!( + "namespace detail {{\n\nstruct {name}_op {{\n\tusing raw = ::{handle};\n\tusing output = {output};\n\n\tstatic void free(raw *f) noexcept {{\n\t\t::{}(f);\n\t}}\n\n\tstatic void poll(raw *f, c_waker w, slot &out) {{\n{declared}\t\tswitch (::{}({})) {{\n{}\n\t\t}}\n\t}}\n}};\n\n}} // namespace detail\n", + free.name, + poll.name, + args.join(", "), + cases.join("\n") + )); + } +} + +/// The enum named `c` in C. +fn enumeration(abi: &Abi<'_>, c: &str) -> Type { + let i = (0..abi.api.enums.len()).find(|&i| abi.enumeration(i) == c); + Type::Enum(i.expect("a free method's owner is an enum")) +} + +/// Whether the object named `c` in C is `Copy`. +fn copy(abi: &Abi<'_>, c: &str) -> bool { + (0..abi.api.objects.len()).any(|i| abi.api.objects[i].copy && abi.object(i) == c) +} + +/// `ty` returned: a borrow is returned as a clone, so owned. +fn strip_refs(ty: &Type) -> Type { + match ty { + Type::Ref(_, inner) => strip_refs(inner), + Type::Option(inner) => Type::Option(Box::new(strip_refs(inner))), + Type::Box(inner) => Type::Box(Box::new(strip_refs(inner))), + ty => ty.clone(), + } +} + +/// A parameter of C++ type `ty` named `name`. +fn declare(ty: &str, name: &str) -> String { + match ty.ends_with('&') || ty.ends_with('*') { + true => format!("{ty}{name}"), + false => format!("{ty} {name}"), + } +} + +/// A field's initializer, so a default-constructed struct holds no garbage: none for a +/// type with no default constructor. +fn init(ty: &Type) -> &'static str { + match ty { + Type::Object(_) | Type::Enum(_) | Type::Record(_) => "", + Type::Box(inner) => init(inner), + _ => "{}", + } +} + +/// C++ comments holding `docs`, each line indented by `indent`, or nothing for none. +fn docs(docs: &str, indent: &str) -> String { + docs.lines() + .map(|line| match line.is_empty() { + true => format!("{indent}///\n"), + false => format!("{indent}/// {line}\n"), + }) + .collect() +} + +fn cpp_int(int: Int) -> &'static str { + match int { + Int::U8 => "::std::uint8_t", + Int::U16 => "::std::uint16_t", + Int::U32 => "::std::uint32_t", + Int::U64 => "::std::uint64_t", + Int::Usize => "::std::size_t", + Int::I8 => "::std::int8_t", + Int::I16 => "::std::int16_t", + Int::I32 => "::std::int32_t", + Int::I64 => "::std::int64_t", + Int::Isize => "::std::ptrdiff_t", + } +} + +/// A name C++ would read as a keyword with `_` appended, and one starting with a digit +/// with `_` prepended, as C's are. +pub fn escape(name: &str) -> String { + const KEYWORDS: &[&str] = &[ + "alignas", + "alignof", + "and", + "and_eq", + "asm", + "auto", + "bitand", + "bitor", + "bool", + "break", + "case", + "catch", + "char", + "char8_t", + "char16_t", + "char32_t", + "class", + "compl", + "concept", + "const", + "consteval", + "constexpr", + "constinit", + "const_cast", + "continue", + "co_await", + "co_return", + "co_yield", + "decltype", + "default", + "delete", + "do", + "double", + "dynamic_cast", + "else", + "enum", + "explicit", + "export", + "extern", + "false", + "float", + "for", + "friend", + "goto", + "if", + "inline", + "int", + "long", + "mutable", + "namespace", + "new", + "noexcept", + "not", + "not_eq", + "nullptr", + "operator", + "or", + "or_eq", + "private", + "protected", + "public", + "register", + "reinterpret_cast", + "requires", + "restrict", + "return", + "short", + "signed", + "sizeof", + "static", + "static_assert", + "static_cast", + "struct", + "switch", + "template", + "this", + "thread_local", + "throw", + "true", + "try", + "typedef", + "typeid", + "typename", + "union", + "unsigned", + "using", + "virtual", + "void", + "volatile", + "wchar_t", + "while", + "xor", + "xor_eq", + // What the generated code names unqualified. + "std", + "self", + ]; + match name.chars().next() { + Some(c) if c.is_ascii_digit() => format!("_{name}"), + _ if KEYWORDS.contains(&name) => format!("{name}_"), + _ => name.to_string(), + } +} diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 4fe597ab4..15bae186b 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -38,7 +38,7 @@ impl Crate<'_> { names.join(", ") } - /// Write the crate into `out`: `Cargo.toml`, `src/`, and `include/.h`. + /// Write the crate into `out`: `Cargo.toml`, `src/`, and `include/.h` and `.hpp`. pub fn write(&self, out: &Path) -> Result<(), String> { // Cargo unifies in what the configured package enables in each other export. let dependencies: String = (self.exports.iter()) @@ -78,6 +78,7 @@ impl Crate<'_> { lib = self.abi.prefix, ); let (header, contract) = crate::c::header(self.abi, &self.packages()); + let cpp = crate::cpp::header(self.abi, &self.packages())?; let mut generator = Gen { abi: self.abi, packages: self.packages(), @@ -89,7 +90,8 @@ impl Crate<'_> { crate::driver::write(&out.join("Cargo.toml"), &manifest)?; crate::driver::write(&out.join("src/lib.rs"), &generator.out)?; crate::driver::write(&out.join("src/rt.rs"), RUNTIME)?; - crate::driver::write(&out.join("include").join(format!("{}.h", self.abi.prefix)), &header) + crate::driver::write(&out.join("include").join(format!("{}.h", self.abi.prefix)), &header)?; + crate::driver::write(&out.join("include").join(format!("{}.hpp", self.abi.prefix)), &cpp) } } diff --git a/ffi/src/main.rs b/ffi/src/main.rs index d004395cd..5e6345db8 100644 --- a/ffi/src/main.rs +++ b/ffi/src/main.rs @@ -24,6 +24,7 @@ mod census; mod cli; mod collect; mod config; +mod cpp; mod driver; mod glue; mod ir; diff --git a/ffi/tests/api.c b/ffi/tests/api.c index be2cdd1e6..173679fd0 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -143,6 +143,9 @@ static int script(void) { api_counter_free(c); print("label ", api_label_debug(&label), "\n"); api_label_free(&label); + /* Empty text is not none: only a null pointer is. */ + api_note empty = {.text = {.ptr = (const uint8_t *)"", .len = 0}}; + printf("note %s %s\n", api_has_text(empty) ? "true" : "false", api_has_text((api_note){0}) ? "true" : "false"); /* A tuple returns through one out pointer per element. */ api_counter *whole = api_counter_new(str("s"), 7); diff --git a/ffi/tests/api.cpp b/ffi/tests/api.cpp new file mode 100644 index 000000000..f61a3485e --- /dev/null +++ b/ffi/tests/api.cpp @@ -0,0 +1,523 @@ +// The api fixture's C++ test: the script fixtures/api/examples/transcript.rs runs +// natively, through the generated C++ header. tests/fixtures.rs compares the transcripts. +// +// With an argument, it instead checks the futures' semantics, or breaks a contract of the +// ABI, which must abort. + +#include +#include +#include +#include +#include +#include +#include + +#include "api.hpp" + +namespace { + +// Print a returned buffer. +void print(const char *before, const api::buf &buf, const char *after) { + std::printf("%s%.*s%s", before, static_cast(buf.size()), reinterpret_cast(buf.data()), after); +} + +int wakes = 0; + +// The Log callback: keeps even levels. +class print_log final : public api::log { +public: + bool log_(std::uint8_t level, api::view line) const override { + std::printf("log %u %.*s\n", level, static_cast(line.size()), reinterpret_cast(line.data())); + return level % 2 == 0; + } + ~print_log() override { + std::printf("freed\n"); + } +}; + +// A bound, as Rust's Debug prints it. +void print_bound(api::bound_u64 bound) { + switch (bound.kind) { + case API_BOUND_INCLUDED: + std::printf("Included(%llu)", static_cast(bound.value)); + break; + case API_BOUND_EXCLUDED: + std::printf("Excluded(%llu)", static_cast(bound.value)); + break; + case API_BOUND_UNBOUNDED: + std::printf("Unbounded"); + break; + } +} + +const char *yes(bool b) { + return b ? "true" : "false"; +} + +unsigned long long ull(std::uint64_t v) { + return static_cast(v); +} + +// A queue of jobs that a test runs when it chooses: the executor futures run on. +struct queue { + std::mutex mutex; + std::deque> jobs; + + auto executor() { + return [this](std::function job) { + std::lock_guard lock(mutex); + jobs.push_back(std::move(job)); + }; + } + + // Run jobs until none are left. + void drain() { + for (;;) { + std::function job; + { + std::lock_guard lock(mutex); + if (jobs.empty()) { + return; + } + job = std::move(jobs.front()); + jobs.pop_front(); + } + job(); + } + } +}; + +int script() { + std::printf("limit %llu\n", ull(api::limit)); + + api::point start{1, 2}; + api::point p = start.offset(2, 3); + std::printf("offset %d %d\n", p.x, p.y); + print("debug ", p.debug(), "\n"); + std::printf("eq %s\n", yes(p == api::point{3, 5})); + api::point d = api::point::default_(); + std::printf("default %d %d\n", d.x, d.y); + + api::counter c = api::counter::new_("c", 5); + std::printf("get %llu\n", ull(c.get())); + print("name ", c.name(), "\n"); + if (auto v = c.add(10)) { + std::printf("add ok %llu\n", ull(*v)); + } + if (auto v = c.add(2000); !v) { + print("add err ", api::error_to_string(v.error()), " "); + print("", api::error_debug(v.error()), "\n"); + } + if (auto v = c.sub(20); !v) { + std::printf("sub err underflow by %llu ", ull(std::get(v.error()).by)); + print("", api::error_debug(v.error()), "\n"); + } + c.rename("d"); + print("name ", c.name(), "\n"); + std::printf("is d %s\n", yes(c.is("d"))); + { + api::counter copy = c; + (void)copy.add(1); + std::printf("clone %llu original %llu\n", ull(copy.get()), ull(c.get())); + } + print("debug ", c.debug(), "\n"); + api::label label = std::move(c).into_label(p); + print("label ", label.debug(), "\n"); + // An empty buffer C++ made is not none. + std::printf("note %s %s\n", yes(api::has_text(api::note{api::buf()})), yes(api::has_text(api::note{}))); + + // A tuple returns through one out pointer per element. + auto [below, above] = api::counter::new_("s", 7).split(5); + print("split ", below.name(), " "); + std::printf("%llu ", ull(below.get())); + print("", above.name(), " "); + std::printf("%llu\n", ull(above.get())); + auto [only] = api::only(api::counter::new_("o", 3)); + print("only ", only.name(), " "); + std::printf("%llu\n", ull(only.get())); + for (std::uint64_t divisor : {2, 0}) { + if (auto r = api::divide(7, divisor)) { + std::printf("divide %llu %llu\n", ull(std::get<0>(*r)), ull(std::get<1>(*r))); + } else { + print("divide err ", api::error_to_string(r.error()), "\n"); + } + } + + // Each lent counter is a new handle to a clone. + api::registry registry = api::registry::new_(api::counter::new_("first", 1)); + std::printf("last %s\n", yes(registry.last().has_value())); + registry.push(api::counter::new_("last", 2)); + { + api::counter first = registry.first(); + (void)first.add(10); + std::printf("first %llu lent %llu\n", ull(registry.first().get()), ull(first.get())); + api::counter last = *registry.last(); + (void)last.add(10); + std::printf("last %llu lent %llu\n", ull(registry.last()->get()), ull(last.get())); + } + // A closure lent for the call edits the first counter through its class. + std::uint64_t by = 5; + bool edited = registry.edit([&](api::counter &counter) { + (void)counter.add(by); + return counter.edited() && counter.get() == 6; + }); + std::printf("edit %s %llu\n", yes(edited), ull(registry.first().get())); + std::printf("walk %llu\n", ull(api::walk(3, [](const api::cursor &cursor) { return cursor.at() * 2; }))); + std::printf("offset %u\n", api::offset([] { return 7u; }, 3)); + + // A type generic only over lifetimes is a handle to its 'static form. + { + api::name name = api::name::owned("a"); + api::name joined = name.join(api::name::owned("b")); + print("joined ", joined.as_str(), " "); + print("", joined.debug(), " "); + std::printf("%s\n", yes(joined == name)); + std::string text = "c"; + joined.rename(text); + // The name took a copy: the caller's buffer is its own again. + text[0] = 'x'; + print("renamed ", joined.as_str(), "\n"); + api::name longest = api::longer(std::move(joined), api::name::owned("dd")); + print("longer ", longest.as_str(), "\n"); + print("unnamed [", api::unnamed().as_str(), "]\n"); + } + + std::printf("total %llu\n", ull(api::total({2, 5}))); + api::range_u64 wide = api::widen({2, 5}, 1); + std::printf("widen %llu %llu\n", ull(wide.start), ull(wide.end)); + api::bounds_u64 ranges[] = { + {{API_BOUND_INCLUDED, 2}, {API_BOUND_EXCLUDED, 5}}, {{API_BOUND_INCLUDED, 2}, {API_BOUND_INCLUDED, 5}}, + {{API_BOUND_INCLUDED, 3}, {API_BOUND_UNBOUNDED, 0}}, {{API_BOUND_UNBOUNDED, 0}, {API_BOUND_UNBOUNDED, 0}}, + {{API_BOUND_EXCLUDED, 2}, {API_BOUND_INCLUDED, 4}}, + }; + std::printf("count"); + for (const auto &range : ranges) { + std::printf(" %zu", api::count(range)); + } + std::printf("\n"); + std::printf("end "); + print_bound(api::end(3)); + std::printf(" "); + print_bound(api::end(0)); + std::printf("\n"); + api::window window{{2, 8}, api::end(5)}; + std::printf("window %s %s ", yes(window.contains(4)), yes(window.contains(6))); + print("", window.debug(), "\n"); + + print("", api::greet("x", api::shape::square), "\n"); + std::printf("len %zu\n", api::len("abc")); + api::event events[] = {api::event_moved{p}, api::event_named{api::buf("n")}, api::event_done{}}; + for (const auto &event : events) { + print("", api::describe(event), "\n"); + } + + // A `Copy` handle passed by value is copied, so it stays usable. + { + api::stamp stamp = api::stamp::from_millis(2500); + std::printf("secs %llu\n", ull(stamp.secs())); + std::printf("later %s\n", yes(api::stamp::from_millis(3000).later(stamp))); + std::printf("secs %llu\n", ull(stamp.secs())); + api::message message = api::message::new_(&stamp, "body"); + print("payload ", message.payload(), "\n"); + print("stamp ", message.stamp()->debug(), "\n"); + std::printf("sent %s\n", yes(message.sent())); + } + + std::uint8_t levels[] = {1, 2, 3, 4}; + std::printf("kept %u\n", api::emit(std::make_unique(), api::view(levels, sizeof levels))); + { + api::logger logger = api::logger::new_(std::make_unique()); + std::printf("write %s\n", yes(logger.write("hi"))); + } + std::printf("dropped\n"); + // Rust calls it on another thread, before the call returns. + std::uint8_t threshold = 2; + std::printf("filtered %u\n", api::filter(api::view(levels, sizeof levels), [threshold](std::uint8_t level, api::view line) { + std::printf("filter %u %.*s\n", level, static_cast(line.size()), reinterpret_cast(line.data())); + return level > threshold; + })); + + { + api::channel channel = api::channel::new_(); + api::waker waker([]() { wakes++; }); + { + api::channel_recv_future recv = channel.recv(); + std::printf("recv pending %s\n", yes(!recv.poll(waker).has_value())); + channel.send("hi"); + std::printf("woken %d\n", wakes); + if (auto payload = recv.poll(waker)) { + print("recv ", *payload, "\n"); + } + } + channel.send(""); + { + api::channel_recv_nonempty_future nonempty = channel.recv_nonempty(); + if (auto r = nonempty.poll(waker)) { + if (*r) { + std::printf("nonempty %zu\n", r->value().size()); + } else { + print("nonempty err ", api::error_to_string(r->error()), "\n"); + } + } else { + std::printf("nonempty pending\n"); + } + } + + // The send happens at the call: the future is dropped unpolled. + channel.send_later("eager"); + { + api::channel_recv_future recv = channel.recv(); + if (auto payload = recv.poll(waker)) { + print("recv ", *payload, "\n"); + } + } + channel.send("sized"); + { + api::channel_recv_sized_future sized = channel.recv_sized(); + if (auto r = sized.poll(waker)) { + print("sized ", std::get<0>(*r), " "); + std::printf("%zu\n", std::get<1>(*r)); + } + } + // The waker moves into Rust, which keeps it until the send wakes it. + channel.notify(waker); + channel.send("rung"); + std::printf("woken %d\n", wakes); + } + + // A value that holds itself is an object. + { + api::node list = api::node::new_(1, std::nullopt); + list.push(2); + std::printf("node %llu\n", ull(list.sum())); + } + + { + api::tally tally = api::tally::new_(); + tally.bump(); + std::uint32_t count = tally.bump(); + std::printf("tally %u %s\n", count, yes(tally == tally)); + std::printf("both %u\n", api::bump_both(tally, tally)); + std::printf("peek %u\n", api::peek(tally, [](const api::tally &lent) { return lent.bump(); })); + } + + // Another export's types, which this export's function takes and returns. + { + api::area area = api::grow(api::area::new_({2, 3}), 1); + api::size size = area.size(); + std::printf("area %u %u %llu\n", size.width, size.height, ull(area.pixels())); + } + + // Generic types, each at the instances the config names under their own names. + api::pair pair{2, 5}; + api::pair swapped = pair.swap(); + std::printf("pair %u %u sum %u ", swapped.left, swapped.right, pair.sum()); + print("", pair.debug(), " "); + std::printf("%s\n", yes(pair == swapped)); + std::printf("even %s %s\n", yes(pair.even()), yes(api::pair{7, 7}.even())); + api::size_pair sizes{{1, 2}, 3}; + api::pair_size flipped = sizes.swap(); + std::printf("sized %u %u ", flipped.left, flipped.right.width); + print("", flipped.debug(), "\n"); + api::pair_size beside = api::pair{258, 9}.beside(sizes.left); + std::printf("beside %u ", beside.left); + print("", beside.debug(), "\n"); + { + api::counters stack = api::counters::new_(); + const char *names[] = {"a", "b"}; + for (int i = 0; i < 2; i++) { + stack.push(api::counter::new_(names[i], static_cast(i) + 1)); + } + std::optional top = stack.pop(); + std::printf("stack %zu Some(%llu)", stack.depth(), ull(top->get())); + std::printf(" %s", yes(stack.pop().has_value())); + std::printf(" %s\n", yes(!stack.pop().has_value())); + // Generic functions and methods, at each instance the config names, by its own name. + api::counter from_point = api::counter::seeded_point("p", {-3, 4}); + api::counter from_size = api::counter::seeded_size("s", {5, 6}); + std::printf("seeded %llu %llu past %llu seeds %llu\n", ull(from_point.get()), ull(from_size.get()), + ull(stack.depth_past_point({1, 2})), ull(api::seeds({2, 3}))); + } + + // Its Drop runs when C++ destroys the handle, not before. + { + api::token token = api::token::new_(7); + std::printf("token %u dropped %u\n", token.id(), api::dropped()); + } + std::printf("dropped %u\n", api::dropped()); + + // A field and the method of its name, each its own member. + api::retry retry = api::retry::new_(5u); + std::optional limit = retry.limit_setting(); + std::printf("retry %d %u %u %u\n", limit.has_value(), limit.value_or(0), retry.limit(), retry.delay()); + std::printf("slot %u\n", api::byte_slot::new_(200).value()); + return 0; +} + +// The futures' semantics beyond the transcript, each checked by an assertion. +int check(bool ok, const char *what) { + if (!ok) { + std::fprintf(stderr, "failed: %s\n", what); + std::exit(1); + } + return 0; +} + +int futures() { + api::channel channel = api::channel::new_(); + + // Blocking: the send lands from another thread while it waits. + { + std::thread sender([&]() { channel.send("blocked"); }); + api::buf payload = channel.recv().get(); + sender.join(); + check(payload.str() == "blocked", "get returns the payload sent"); + } + + // On an executor: polled there, and called back there once ready. + queue q; + { + std::string got; + api::task task = channel.recv().then(q.executor(), [&](api::buf payload) { got = payload.str(); }); + q.drain(); + check(got.empty(), "then waits for a send"); + channel.send("then"); + check(got.empty(), "then never polls inside the wake"); + q.drain(); + check(got == "then", "then calls back with the payload"); + } + + // A wake that lands while the future polls, before it returns pending, is kept: the + // future polls again rather than waiting for a wake that already happened. + { + std::uint32_t got = 0; + api::task task = api::yielded(7).then(q.executor(), [&](std::uint32_t value) { got = value; }); + q.drain(); + check(got == 7, "a wake during the poll polls again"); + } + + // Cancelled between its wake and its poll, a receive loses nothing: the payload stays + // for the next. + { + bool called = false; + { + api::task task = channel.recv().then(q.executor(), [&](api::buf) { called = true; }); + q.drain(); + channel.send("kept"); + } + q.drain(); + check(!called, "a cancelled task never calls back"); + auto next = channel.recv(); + auto payload = next.poll(api::waker([]() {})); + check(payload && payload->str() == "kept", "a cancelled receive loses nothing"); + } + + // Cancelled from its own callback, it finishes. + { + api::task task; + bool called = false; + channel.send("self"); + task = channel.recv().then(q.executor(), [&](api::buf) { + called = true; + task = api::task(); + }); + q.drain(); + check(called, "a task cancelled in its callback finishes"); + } + +#if defined(__cpp_impl_coroutine) && __cpp_impl_coroutine >= 201902L && __has_include() + // Awaited in a coroutine, resumed on the executor. + { + struct detached { + struct promise_type { + detached get_return_object() { + return {std::coroutine_handle::from_promise(*this)}; + } + std::suspend_never initial_suspend() noexcept { + return {}; + } + std::suspend_always final_suspend() noexcept { + return {}; + } + void return_void() {} + void unhandled_exception() { + std::abort(); + } + }; + std::coroutine_handle handle; + }; + std::string got; + auto read = [&](api::channel &ch) -> detached { + api::buf payload = co_await ch.recv().via(q.executor()); + got = payload.str(); + std::uint32_t value = co_await api::yielded(3).via(q.executor()); + got += std::to_string(value); + }; + detached coroutine = read(channel); + channel.send("awaited"); + q.drain(); + check(coroutine.handle.done() && got == "awaited3", "co_await resumes with each output"); + coroutine.handle.destroy(); + + // Destroyed while suspended, the coroutine cancels its receive, which loses nothing. + got.clear(); + detached cancelled = read(channel); + q.drain(); + channel.send("again"); + cancelled.handle.destroy(); + q.drain(); + check(got.empty(), "a destroyed coroutine never resumes"); + auto payload = channel.recv().get(); + check(payload.str() == "again", "a destroyed coroutine's receive loses nothing"); + } +#endif + std::printf("futures ok\n"); + return 0; +} + +// Each breaks a contract, which must abort with a message naming the function. +int broken(const char *which) { + if (std::strcmp(which, "moved") == 0) { + api::counter c = api::counter::new_("c", 0); + api::label label = std::move(c).into_label(std::nullopt); + c.get(); + } else if (std::strcmp(which, "value") == 0) { + api::counter c = api::counter::new_("c", 0); + c.sub(1).value(); + } else if (std::strcmp(which, "finished") == 0) { + api::channel channel = api::channel::new_(); + channel.send("x"); + api::channel_recv_future recv = channel.recv(); + api::waker waker([]() {}); + recv.poll(waker); + recv.poll(waker); + } else if (std::strcmp(which, "null view") == 0) { + api::len(api::view(nullptr, 1)); + } else if (std::strcmp(which, "lent moved") == 0) { + api::registry registry = api::registry::new_(api::counter::new_("c", 0)); + registry.edit([](api::counter &counter) { + api::label label = std::move(counter).into_label(std::nullopt); + return false; + }); + } else if (std::strcmp(which, "lent kept") == 0) { + static std::optional kept; + api::registry registry = api::registry::new_(api::counter::new_("c", 0)); + registry.edit([](api::counter &counter) { + kept.emplace(std::move(counter)); + return false; + }); + } + return 0; +} + +} // namespace + +int main(int argc, char **argv) { + if (argc > 1 && std::strcmp(argv[1], "futures") == 0) { + return futures(); + } + if (argc > 1) { + return broken(argv[1]); + } + return script(); +} diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 6da207ce0..fd59b4440 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -1,5 +1,6 @@ //! The api fixture is exported, built as a static library, and driven from C by -//! `tests/api.c`, whose transcript must match the fixture's own script run natively. +//! `tests/api.c` and from C++ by `tests/api.cpp`, whose transcripts must match the +//! fixture's own script run natively. //! The reject fixture's export must fail at each item it cannot export. use std::path::{Path, PathBuf}; @@ -95,6 +96,75 @@ fn api() { "the C transcript differs from the native one" ); + // The C++ header at each standard, with exceptions and RTTI on and off between them, + // runs the same script, then checks its futures' semantics. + let cxx = std::env::var_os("CXX").unwrap_or_else(|| "c++".into()); + for (standard, flags) in [ + ("c++17", &["-fno-exceptions", "-fno-rtti"][..]), + ("c++20", &[]), + ("c++23", &["-fno-exceptions", "-fno-rtti"]), + ] { + let exe = scratch().join("api").join(format!("api-{standard}")); + run(Command::new(&cxx) + .arg(format!("-std={standard}")) + .args(flags) + .args(["-pedantic", "-Wall", "-Wextra", "-Werror", "-I"]) + .arg(out.join("include")) + .arg(manifest_dir().join("tests").join("api.cpp")) + .arg(target.join("debug").join("libapi.a")) + .args(["-lpthread", "-ldl", "-lm", "-o"]) + .arg(&exe)); + let cpp = run(&mut Command::new(&exe)); + assert_eq!( + String::from_utf8_lossy(&cpp.stdout), + String::from_utf8_lossy(&native.stdout), + "the {standard} transcript differs from the native one" + ); + run(Command::new(&exe).arg("futures")); + for (case, message) in [ + ("moved", "api_counter_get: a handle's value was moved out"), + ("value", "value() of a result that holds an error"), + ( + "finished", + "api_channel_recv_poll: a future is polled after it finished", + ), + ( + "lent moved", + "api_counter_into_label: a lent handle's value cannot move out", + ), + ("lent kept", "a lent object was moved out of"), + ("null view", "a view of null bytes has a length"), + ] { + let output = Command::new(&exe).arg(case).output().unwrap(); + assert!(!output.status.success(), "{standard} {case} did not abort"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(stderr.contains(message), "{standard} {case} printed {stderr}"); + } + } + + // A C++ program whose header names another contract than its library's aborts at load. + let mismatched = scratch().join("api").join("contract.cpp"); + std::fs::write( + &mismatched, + "#include \"api.h\"\n#undef API_CONTRACT\n#define API_CONTRACT ((uint64_t)0)\n#include \"api.hpp\"\nint main() {}\n", + ) + .unwrap(); + let contract = scratch().join("api").join("contract"); + run(Command::new(&cxx) + .args(["-std=c++17", "-I"]) + .arg(out.join("include")) + .arg(&mismatched) + .arg(target.join("debug").join("libapi.a")) + .args(["-lpthread", "-ldl", "-lm", "-o"]) + .arg(&contract)); + let output = Command::new(&contract).output().unwrap(); + assert!(!output.status.success(), "a mismatched contract did not abort"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!( + stderr.contains("api.hpp and the library are from different builds"), + "a mismatched contract printed {stderr}" + ); + // Each broken contract aborts, naming the function and what broke. for (case, message) in [ ("moved", "api_counter_get: a handle's value was moved out"), diff --git a/quest/m1/ffi-export/README.md b/quest/m1/ffi-export/README.md index 10877ed86..57e826f86 100644 --- a/quest/m1/ffi-export/README.md +++ b/quest/m1/ffi-export/README.md @@ -51,5 +51,5 @@ Every generator on the C ABI: - [moq-clock's C names once it moves into kio](/quest/m1/ffi-export/crates.md) - `moq_now` and `moq_origin` become the clock's, after moq moves it into `kio::clock` - [Sessions on moq-tokio](/quest/m1/ffi-export/session-tokio.md) - bindings connect and accept with one call, the library running moq-tokio inside - [Sessions on sans-IO QUIC](/quest/m1/ffi-export/session-quic.md) - bindings move UDP datagrams and drive the session's poll themselves -- [C++ bindings](/quest/m1/ffi-export/cpp.md) - C++17, 20, and 23 over the C ABI, with native futures +- [C++ bindings on MSVC and Clang](/quest/m1/ffi-export/cpp.md) - the C++ header built and tested beyond GCC on Linux - [Kotlin bindings](/quest/m1/ffi-export/kotlin.md) - JNI or Panama over the C ABI, with native futures diff --git a/quest/m1/ffi-export/cpp.md b/quest/m1/ffi-export/cpp.md index 4e25b6d6f..b3dc5336a 100644 --- a/quest/m1/ffi-export/cpp.md +++ b/quest/m1/ffi-export/cpp.md @@ -1,12 +1,17 @@ -# [L] C++ bindings +# [M] C++ bindings on MSVC and Clang ## Goal -The exporter generates C++ over its one C ABI, per standard (17, 20, 23), compiled with -GCC, Clang, and MSVC, with and without exceptions and RTTI, including OBS's C17 and C++17 -builds, meeting the [epic's](/quest/m1/ffi-export/README.md) rules for every generator, -native futures included. +The exporter's C++ header, which GCC builds and tests on Linux in `just ffi test` and +`just ffi moq`, builds and passes the same tests with MSVC on Windows and Clang on Linux +and macOS, at C++17, 20, and 23, with and without exceptions and RTTI, in CI at least +nightly. ## Plan -Public API: a new generator. +- One nightly job per platform, as `uniffi-cpp` runs the fork's. The exporter is a rustc + driver that runs on the host, so Windows either runs it there or builds an export made + on Linux; the tests' link flags (`-lpthread -ldl -lm`) and compiler flags are GCC's and + need MSVC's. +- Clang 21 passed every configuration locally when the generator landed; CI has no Clang + yet.