From 46d96c9117e3fde1b517dfb1e03a1f340a322258 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 18:42:29 -0700 Subject: [PATCH 01/16] chore(quest): claim quest/m1/ffi-export-spike.md Quest-Claim: e91720a4b3e28762 From 376a865e43eb189f8f1b02b09375fcbf316f9f0f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 18:51:16 -0700 Subject: [PATCH 02/16] refactor(ts): move the rustc driver front end into a shared crate Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/Cargo.toml | 20 ++++++++ driver/rust-toolchain.toml | 1 + driver/src/cargo.rs | 97 ++++++++++++++++++++++++++++++++++++++ driver/src/lib.rs | 14 ++++++ driver/src/rustc.rs | 49 +++++++++++++++++++ ts/Cargo.lock | 5 ++ ts/Cargo.toml | 1 + ts/src/cli.rs | 89 ++++++---------------------------- ts/src/driver.rs | 28 ++--------- ts/src/main.rs | 5 +- 10 files changed, 206 insertions(+), 103 deletions(-) create mode 100644 driver/Cargo.toml create mode 120000 driver/rust-toolchain.toml create mode 100644 driver/src/cargo.rs create mode 100644 driver/src/lib.rs create mode 100644 driver/src/rustc.rs diff --git a/driver/Cargo.toml b/driver/Cargo.toml new file mode 100644 index 000000000..0047687c7 --- /dev/null +++ b/driver/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "rust2-driver" +description = "The rustc driver front end that rust2's drivers share" +version = "0.0.0" +edition = "2024" +license = "MIT OR Apache-2.0" +repository = "https://github.com/kixelated/rust2" +# A path dependency of the drivers: it only builds on their pinned nightly. +publish = false + +[package.metadata.rust-analyzer] +rustc_private = true + +# Its own workspace, apart from the repo's, on the drivers' nightly: rust-toolchain.toml +# links ts's pin, which flake.nix reads. +[workspace] + +[lints.clippy] +# Every suppression says why, so the next lint audit can judge it. +allow_attributes_without_reason = "warn" diff --git a/driver/rust-toolchain.toml b/driver/rust-toolchain.toml new file mode 120000 index 000000000..6a0f853eb --- /dev/null +++ b/driver/rust-toolchain.toml @@ -0,0 +1 @@ +../ts/rust-toolchain.toml \ No newline at end of file diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs new file mode 100644 index 000000000..8cf75fbf3 --- /dev/null +++ b/driver/src/cargo.rs @@ -0,0 +1,97 @@ +//! The binary as a CLI: run cargo on a package with this binary as rustc. + +use std::ffi::OsStr; +use std::path::{Path, PathBuf}; +use std::process::{Command, ExitCode}; + +/// A `cargo check` of one package's library, with this executable as rustc. +pub struct Check<'a> { + /// The driver's name, which names its target directory. + pub tool: &'a str, + /// The package's `Cargo.toml`, absolute. + pub manifest: &'a Path, + /// The cargo package whose library the driver handles. + pub package: &'a str, + /// The target to check for, or `None` for the host. + pub target: Option<&'a str>, + /// Passed on to `cargo check`, such as `--features`. + pub args: &'a [String], + /// The environment the wrapper reads its job from. + pub env: &'a [(&'a str, &'a OsStr)], +} + +impl Check<'_> { + /// Run it, after cleaning the package: cargo can't tell the driver's output is + /// stale, so the package always recompiles. + pub fn run(&self) -> Result { + let exe = std::env::current_exe().map_err(|err| format!("finding this executable: {err}"))?; + let target_dir = match std::env::var_os("CARGO_TARGET_DIR") { + Some(dir) => PathBuf::from(dir), + // Apart from the workspace's own builds, which a different rustc would invalidate. + None => workspace_root(self.manifest)?.join("target").join(self.tool), + }; + let package_dir = self.manifest.parent().expect("a manifest path has a parent"); + let cargo = |subcommand: &str| { + let mut cmd = cargo(); + // Cargo reads its config from where it runs, so run where the package is. + cmd.current_dir(package_dir); + cmd.arg(subcommand) + .arg("--manifest-path") + .arg(self.manifest) + .arg("--package") + .arg(self.package) + .arg("--target-dir") + .arg(&target_dir); + if let Some(target) = self.target { + cmd.arg("--target").arg(target); + } + cmd + }; + run_cargo(cargo("clean").arg("--quiet"))?; + let status = cargo("check") + .arg("--lib") + .args(self.args) + .env("RUSTC_WRAPPER", &exe) + .envs(self.env.iter().copied()) + .status() + .map_err(|err| format!("running cargo: {err}"))?; + Ok(match status.success() { + true => ExitCode::SUCCESS, + false => ExitCode::FAILURE, + }) + } +} + +/// `path`, absolute. +pub fn absolute(path: &Path) -> Result { + std::path::absolute(path).map_err(|err| format!("resolving {}: {err}", path.display())) +} + +fn cargo() -> Command { + Command::new(std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into())) +} + +fn run_cargo(cmd: &mut Command) -> Result<(), String> { + let status = cmd.status().map_err(|err| format!("running cargo: {err}"))?; + match status.success() { + true => Ok(()), + false => Err(format!("{cmd:?} failed")), + } +} + +/// The directory of the workspace `manifest` belongs to. +fn workspace_root(manifest: &Path) -> Result { + let output = cargo() + .args(["locate-project", "--workspace", "--message-format", "plain", "--manifest-path"]) + .arg(manifest) + .output() + .map_err(|err| format!("running cargo: {err}"))?; + if !output.status.success() { + return Err(String::from_utf8_lossy(&output.stderr).into_owned()); + } + let root = String::from_utf8(output.stdout).map_err(|_| "cargo printed a non-UTF-8 path".to_string())?; + Ok(Path::new(root.trim()) + .parent() + .expect("a manifest path has a parent") + .to_path_buf()) +} diff --git a/driver/src/lib.rs b/driver/src/lib.rs new file mode 100644 index 000000000..ef4657ee3 --- /dev/null +++ b/driver/src/lib.rs @@ -0,0 +1,14 @@ +//! The front end rust2's rustc drivers share. +//! +//! A driver binary is two programs. Run directly, it is a CLI that runs cargo on a +//! package with itself as `RUSTC_WRAPPER` ([`cargo`]). Run by cargo as that wrapper, it +//! is rustc ([`rustc`]), which compiles every crate as rustc would and hands the +//! configured library to the driver's callbacks. + +#![feature(rustc_private)] + +extern crate rustc_driver; +extern crate rustc_session; + +pub mod cargo; +pub mod rustc; diff --git a/driver/src/rustc.rs b/driver/src/rustc.rs new file mode 100644 index 000000000..ca7aa5568 --- /dev/null +++ b/driver/src/rustc.rs @@ -0,0 +1,49 @@ +//! The binary as rustc, run by cargo as its `RUSTC_WRAPPER`. + +use std::path::Path; +use std::process::ExitCode; + +use rustc_driver::Callbacks; +use rustc_session::EarlyDiagCtxt; +use rustc_session::config::ErrorOutputType; + +const BUG_REPORT_URL: &str = "https://github.com/kixelated/rust2/issues/new"; + +/// Whether cargo ran this binary as its wrapper, which it does with the rustc it would +/// have run as the first argument. +pub fn wrapped(args: &[String]) -> bool { + args.get(1).map(Path::new).and_then(Path::file_stem) == Some("rustc".as_ref()) +} + +/// The callbacks for one rustc invocation. +pub type Job = Box; + +/// Run as rustc, with `args` as cargo passed them. `job` picks the callbacks from +/// rustc's own arguments, or `None` to compile the crate as rustc would; its error ends +/// the run before rustc starts, prefixed with `tool`. +pub fn run(tool: &str, mut args: Vec, job: impl FnOnce(&[String]) -> Result, String>) -> ExitCode { + args.remove(1); + let early_dcx = EarlyDiagCtxt::new(ErrorOutputType::default()); + rustc_driver::init_rustc_env_logger(&early_dcx); + rustc_driver::install_ice_hook(BUG_REPORT_URL, |_| ()); + let job = match job(&args) { + Ok(job) => job, + Err(err) => early_dcx.early_fatal(format!("{tool}: {err}")), + }; + rustc_driver::catch_with_exit_code(|| match job { + Some(mut job) => rustc_driver::compiler_entrypoint(&args, job.as_mut()), + None => rustc_driver::compiler_entrypoint(&args, &mut Plain), + }) +} + +/// Compiles a crate as rustc would. +struct Plain; + +impl Callbacks for Plain {} + +/// Whether rustc's `args` compile the library of `crate_name`, not its tests. +pub fn compiles_lib(args: &[String], crate_name: &str) -> bool { + let name = args.windows(2).find(|w| w[0] == "--crate-name").map(|w| w[1].as_str()); + let lib = args.windows(2).any(|w| w[0] == "--crate-type" && w[1] == "lib"); + name == Some(crate_name) && lib && !args.iter().any(|a| a == "--test") +} diff --git a/ts/Cargo.lock b/ts/Cargo.lock index 2744d27e9..40fe0c304 100644 --- a/ts/Cargo.lock +++ b/ts/Cargo.lock @@ -133,11 +133,16 @@ dependencies = [ name = "reject-fixture" version = "0.0.0" +[[package]] +name = "rust2-driver" +version = "0.0.0" + [[package]] name = "rust2-ts" version = "0.0.0" dependencies = [ "oxc_sourcemap", + "rust2-driver", "serde", "toml", ] diff --git a/ts/Cargo.toml b/ts/Cargo.toml index d5cb007fa..581b54cbc 100644 --- a/ts/Cargo.toml +++ b/ts/Cargo.toml @@ -29,6 +29,7 @@ allow_attributes_without_reason = "warn" [dependencies] oxc_sourcemap = "9.0.0" +rust2-driver = { path = "../driver" } serde = { version = "1.0.228", features = ["derive"] } toml = "1.1.8" diff --git a/ts/src/cli.rs b/ts/src/cli.rs index 33e104c24..5b58b2df4 100644 --- a/ts/src/cli.rs +++ b/ts/src/cli.rs @@ -1,7 +1,7 @@ //! The command line: run cargo on the configured package with this binary as rustc. -use std::path::{Path, PathBuf}; -use std::process::{Command, ExitCode}; +use std::path::Path; +use std::process::ExitCode; use crate::config::{self, Config}; @@ -49,7 +49,7 @@ fn try_run(args: &[String]) -> Result { "--census" => &mut census, _ => &mut manifest, }; - *slot = Some(absolute(Path::new(value))?); + *slot = Some(rust2_driver::cargo::absolute(Path::new(value))?); } "--" => { cargo_args = rest; @@ -76,77 +76,16 @@ fn try_run(args: &[String]) -> Result { .expect("an absolute file path has a parent") .join("Cargo.toml"), }; - let exe = std::env::current_exe().map_err(|err| format!("finding this executable: {err}"))?; - let target_dir = match std::env::var_os("CARGO_TARGET_DIR") { - Some(dir) => PathBuf::from(dir), - // Apart from the workspace's own builds, which a different rustc would invalidate. - None => workspace_root(&manifest)?.join("target").join("rust2-ts"), - }; - - let package_dir = manifest.parent().expect("a manifest path has a parent").to_path_buf(); - let cargo = |subcommand: &str| { - let mut cmd = Command::new(std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into())); - // Cargo reads its config from where it runs, so run where the package is. - cmd.current_dir(&package_dir); - cmd.arg(subcommand) - .arg("--manifest-path") - .arg(&manifest) - .arg("--package") - .arg(&config.package) - .arg("--target") - .arg(TARGET) - .arg("--target-dir") - .arg(&target_dir); - cmd - }; - - // Cargo can't tell the TypeScript is stale, so the package always recompiles. - run_cargo(cargo("clean").arg("--quiet"))?; - let status = cargo("check") - .arg("--lib") - .args(cargo_args) - .env("RUSTC_WRAPPER", &exe) - .env(config::env::CONFIG, &config_path) - .env(output_env, &output) - .status() - .map_err(|err| format!("running cargo: {err}"))?; - Ok(match status.success() { - true => ExitCode::SUCCESS, - false => ExitCode::FAILURE, - }) -} - -fn run_cargo(cmd: &mut Command) -> Result<(), String> { - let status = cmd.status().map_err(|err| format!("running cargo: {err}"))?; - match status.success() { - true => Ok(()), - false => Err(format!("{cmd:?} failed")), - } -} - -fn absolute(path: &Path) -> Result { - std::path::absolute(path).map_err(|err| format!("resolving {}: {err}", path.display())) -} - -/// The directory of the workspace `manifest` belongs to. -fn workspace_root(manifest: &Path) -> Result { - let output = Command::new(std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into())) - .args([ - "locate-project", - "--workspace", - "--message-format", - "plain", - "--manifest-path", - ]) - .arg(manifest) - .output() - .map_err(|err| format!("running cargo: {err}"))?; - if !output.status.success() { - return Err(String::from_utf8_lossy(&output.stderr).into_owned()); + rust2_driver::cargo::Check { + tool: "rust2-ts", + manifest: &manifest, + package: &config.package, + target: Some(TARGET), + args: cargo_args, + env: &[ + (config::env::CONFIG, config_path.as_os_str()), + (output_env, output.as_os_str()), + ], } - let root = String::from_utf8(output.stdout).map_err(|_| "cargo printed a non-UTF-8 path".to_string())?; - Ok(Path::new(root.trim()) - .parent() - .expect("a manifest path has a parent") - .to_path_buf()) + .run() } diff --git a/ts/src/driver.rs b/ts/src/driver.rs index 6694e2406..2f75d0232 100644 --- a/ts/src/driver.rs +++ b/ts/src/driver.rs @@ -7,35 +7,17 @@ use std::process::ExitCode; use rustc_driver::{Callbacks, Compilation}; use rustc_interface::interface::Compiler; use rustc_middle::ty::TyCtxt; -use rustc_session::EarlyDiagCtxt; -use rustc_session::config::ErrorOutputType; use crate::config::{self, Config}; use crate::{lower, program}; -const BUG_REPORT_URL: &str = "https://github.com/kixelated/rust2/issues/new"; - /// Run as rustc, with `args` as cargo passed them: the wrapped rustc's path first. -pub fn run(mut args: Vec) -> ExitCode { - args.remove(1); - let early_dcx = EarlyDiagCtxt::new(ErrorOutputType::default()); - rustc_driver::init_rustc_env_logger(&early_dcx); - rustc_driver::install_ice_hook(BUG_REPORT_URL, |_| ()); - let job = match Translate::for_args(&args) { - Ok(job) => job, - Err(err) => early_dcx.early_fatal(format!("rust2-ts: {err}")), - }; - rustc_driver::catch_with_exit_code(|| match job { - Some(mut job) => rustc_driver::compiler_entrypoint(&args, &mut job), - None => rustc_driver::compiler_entrypoint(&args, &mut Plain), +pub fn run(args: Vec) -> ExitCode { + rust2_driver::rustc::run("rust2-ts", args, |args| { + Ok(Translate::for_args(args)?.map(|job| Box::new(job) as rust2_driver::rustc::Job)) }) } -/// Compiles a crate as rustc would. -struct Plain; - -impl Callbacks for Plain {} - /// Compiles the configured crate, translating it after analysis. struct Translate { config: Config, @@ -57,9 +39,7 @@ impl Translate { return Ok(None); }; let config = Config::load(path.as_ref())?; - let crate_name = args.windows(2).find(|w| w[0] == "--crate-name").map(|w| w[1].as_str()); - let lib = args.windows(2).any(|w| w[0] == "--crate-type" && w[1] == "lib"); - if crate_name != Some(config.crate_name().as_str()) || !lib || args.iter().any(|a| a == "--test") { + if !rust2_driver::rustc::compiles_lib(args, &config.crate_name()) { return Ok(None); } let output = match ( diff --git a/ts/src/main.rs b/ts/src/main.rs index b245fd7dc..725885c93 100644 --- a/ts/src/main.rs +++ b/ts/src/main.rs @@ -17,7 +17,6 @@ extern crate rustc_index; extern crate rustc_infer; extern crate rustc_interface; extern crate rustc_middle; -extern crate rustc_session; extern crate rustc_span; extern crate rustc_trait_selection; @@ -30,13 +29,11 @@ mod print; mod program; mod ts; -use std::path::Path; use std::process::ExitCode; fn main() -> ExitCode { let args: Vec = std::env::args().collect(); - // Cargo runs a wrapper with the rustc it would have run as the first argument. - if args.get(1).map(Path::new).and_then(Path::file_stem) == Some("rustc".as_ref()) { + if rust2_driver::rustc::wrapped(&args) { return driver::run(args); } cli::run(&args[1..]) From 6bbbe2e3b26805df4728a288bac0067f8923d7b5 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:03:50 -0700 Subject: [PATCH 03/16] wip(ffi): exporter skeleton, census, ABI, glue, and header generators Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/src/cargo.rs | 83 +++- ffi/Cargo.lock | 170 +++++++ ffi/Cargo.toml | 30 ++ ffi/fixtures/api/Cargo.toml | 13 + ffi/fixtures/api/src/lib.rs | 8 + ffi/justfile | 48 ++ ffi/moq/ffi.toml | 2 + ffi/runtime/rt.rs | 512 +++++++++++++++++++ ffi/rust-toolchain.toml | 1 + ffi/src/abi.rs | 443 +++++++++++++++++ ffi/src/c.rs | 327 +++++++++++++ ffi/src/census.rs | 150 ++++++ ffi/src/cli.rs | 48 ++ ffi/src/collect.rs | 953 ++++++++++++++++++++++++++++++++++++ ffi/src/config.rs | 46 ++ ffi/src/driver.rs | 177 +++++++ ffi/src/glue.rs | 745 ++++++++++++++++++++++++++++ ffi/src/ir.rs | 234 +++++++++ ffi/src/main.rs | 38 ++ justfile | 3 + ts/src/cli.rs | 65 +-- 21 files changed, 4041 insertions(+), 55 deletions(-) create mode 100644 ffi/Cargo.lock create mode 100644 ffi/Cargo.toml create mode 100644 ffi/fixtures/api/Cargo.toml create mode 100644 ffi/fixtures/api/src/lib.rs create mode 100644 ffi/justfile create mode 100644 ffi/moq/ffi.toml create mode 100644 ffi/runtime/rt.rs create mode 120000 ffi/rust-toolchain.toml create mode 100644 ffi/src/abi.rs create mode 100644 ffi/src/c.rs create mode 100644 ffi/src/census.rs create mode 100644 ffi/src/cli.rs create mode 100644 ffi/src/collect.rs create mode 100644 ffi/src/config.rs create mode 100644 ffi/src/driver.rs create mode 100644 ffi/src/glue.rs create mode 100644 ffi/src/ir.rs create mode 100644 ffi/src/main.rs diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs index 8cf75fbf3..82ed64613 100644 --- a/driver/src/cargo.rs +++ b/driver/src/cargo.rs @@ -4,6 +4,86 @@ use std::ffi::OsStr; use std::path::{Path, PathBuf}; use std::process::{Command, ExitCode}; +/// The command line every driver takes: +/// `--config (--out | --census ) [--manifest-path ] [-- ]`. +pub struct Args { + /// The driver's config file, absolute. + pub config: PathBuf, + /// What to write. + pub output: Output, + /// The package's `Cargo.toml`, absolute: beside the config unless given. + pub manifest: PathBuf, + /// Passed on to `cargo check`. + pub cargo: Vec, +} + +/// What a driver writes, absolute. +pub enum Output { + /// Its output, into this directory. + Dir(PathBuf), + /// A census of what it refuses, to this file, instead. + Census(PathBuf), +} + +impl Args { + /// Parse `args`, without the program name, or `None` after printing `usage` for + /// `--help`. An error ends with `usage`. + pub fn parse(args: &[String], usage: &str) -> Result, String> { + let mut config = None; + let mut out = None; + let mut census = None; + let mut manifest = None; + let mut cargo: &[String] = &[]; + let mut rest = args; + while let [arg, tail @ ..] = rest { + rest = tail; + match arg.as_str() { + "--config" | "--out" | "--census" | "--manifest-path" => { + let [value, tail @ ..] = rest else { + return Err(format!("{arg} needs a value\n\n{usage}")); + }; + rest = tail; + let slot = match arg.as_str() { + "--config" => &mut config, + "--out" => &mut out, + "--census" => &mut census, + _ => &mut manifest, + }; + *slot = Some(absolute(Path::new(value))?); + } + "--" => { + cargo = rest; + break; + } + "-h" | "--help" => { + println!("{usage}"); + return Ok(None); + } + _ => return Err(format!("unexpected argument {arg}\n\n{usage}")), + } + } + let config: PathBuf = config.ok_or_else(|| format!("--config is required\n\n{usage}"))?; + let output = match (out, census) { + (Some(out), None) => Output::Dir(out), + (None, Some(census)) => Output::Census(census), + _ => return Err(format!("one of --out and --census is required\n\n{usage}")), + }; + let manifest = match manifest { + Some(manifest) => manifest, + None => config + .parent() + .expect("an absolute file path has a parent") + .join("Cargo.toml"), + }; + Ok(Some(Self { + config, + output, + manifest, + cargo: cargo.to_vec(), + })) + } +} + /// A `cargo check` of one package's library, with this executable as rustc. pub struct Check<'a> { /// The driver's name, which names its target directory. @@ -62,8 +142,7 @@ impl Check<'_> { } } -/// `path`, absolute. -pub fn absolute(path: &Path) -> Result { +fn absolute(path: &Path) -> Result { std::path::absolute(path).map_err(|err| format!("resolving {}: {err}", path.display())) } diff --git a/ffi/Cargo.lock b/ffi/Cargo.lock new file mode 100644 index 000000000..0f377369e --- /dev/null +++ b/ffi/Cargo.lock @@ -0,0 +1,170 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "api-fixture" +version = "0.0.0" +dependencies = [ + "bytes", +] + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "rust2-driver" +version = "0.0.0" + +[[package]] +name = "rust2-ffi" +version = "0.0.0" +dependencies = [ + "rust2-driver", + "serde", + "toml", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_spanned" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7523beb55eece201a2356bee0bbca0d1ab466c14c07703b2e0ee6d42cb0c2c" +dependencies = [ + "serde_core", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "toml" +version = "1.1.8+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20489e00e4d8741d6be680764cc12e270655e375a20d1011e844a9c3379e678d" +dependencies = [ + "indexmap", + "serde_core", + "serde_spanned", + "toml_datetime", + "toml_parser", + "toml_writer", + "winnow", +] + +[[package]] +name = "toml_datetime" +version = "1.1.2+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow", +] + +[[package]] +name = "toml_writer" +version = "1.1.3+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06bdbd8cfc056b8d2e2e85f29b56a3bdbecb527cef81eb39e3e7b98af4652770" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "winnow" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81" diff --git a/ffi/Cargo.toml b/ffi/Cargo.toml new file mode 100644 index 000000000..327555d90 --- /dev/null +++ b/ffi/Cargo.toml @@ -0,0 +1,30 @@ +[package] +name = "rust2-ffi" +description = "Export a crate's pub API as a C ABI and header" +version = "0.0.0" +edition = "2024" +license = "MIT OR Apache-2.0" +repository = "https://github.com/kixelated/rust2" +# Distributed through the flake: it only builds on the pinned nightly. +publish = false + +[package.metadata.rust-analyzer] +rustc_private = true + +[workspace] +# Its own workspace, apart from the repo's: the driver builds on ts's pinned nightly, +# which rust-toolchain.toml links. +members = ["fixtures/*"] +resolver = "3" + +[workspace.lints.clippy] +# Every suppression says why, so the next lint audit can judge it. +allow_attributes_without_reason = "warn" + +[dependencies] +rust2-driver = { path = "../driver" } +serde = { version = "1.0.228", features = ["derive"] } +toml = "1.1.8" + +[lints] +workspace = true diff --git a/ffi/fixtures/api/Cargo.toml b/ffi/fixtures/api/Cargo.toml new file mode 100644 index 000000000..78c79a72b --- /dev/null +++ b/ffi/fixtures/api/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "api-fixture" +description = "Each construct rust2-ffi exports, driven from C by tests/api.c" +version = "0.0.0" +edition = "2024" +license = "MIT OR Apache-2.0" +publish = false + +[dependencies] +bytes = "1.11.1" + +[lints] +workspace = true diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs new file mode 100644 index 000000000..33acea8ea --- /dev/null +++ b/ffi/fixtures/api/src/lib.rs @@ -0,0 +1,8 @@ +//! Each construct rust2-ffi exports, for `tests/api.c` to drive through the C ABI. + +/// A point: a record, since every field is `pub`. +#[derive(Clone, Copy, Debug, PartialEq, Default)] +pub struct Point { + pub x: i32, + pub y: i32, +} diff --git a/ffi/justfile b/ffi/justfile new file mode 100644 index 000000000..126c4d76f --- /dev/null +++ b/ffi/justfile @@ -0,0 +1,48 @@ +#!/usr/bin/env just --justfile +# +# The C exporter, invoked from the repo root as `just ffi `. Its crates are their +# own workspace on ts/rust-toolchain.toml's nightly, which the dev shell exports as +# RUST2_TS_TOOLCHAIN; without it, rustup reads the same file through the link here. + +set shell := ["bash", "-euo", "pipefail", "-c"] + +export PATH := if env("RUST2_TS_TOOLCHAIN", "") == "" { env("PATH") } else { env("RUST2_TS_TOOLCHAIN") / "bin:" + env("PATH") } + +default: + @just --list + +# Lint and format-check the exporter, its fixtures, and the shared driver front end. +check: + cargo clippy --locked --all-targets -- -D warnings + cargo fmt --all --check + cargo shear + cargo sort --workspace --check --no-format + cargo clippy --locked --manifest-path ../driver/Cargo.toml -- -D warnings + cargo fmt --manifest-path ../driver/Cargo.toml --check + +# Export each fixture, build it, and run its C test. +test *args: + cargo test --locked {{ args }} + +# Apply formatters without changing program behavior. +fix: + cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets + cargo fmt --all + cargo fmt --manifest-path ../driver/Cargo.toml + cargo shear --fix + cargo sort --workspace --no-format + +# Run the exporter: `just ffi run --config --out `. +run *args: + cargo run --locked --quiet -- {{ args }} + +# Census what moq-net exports into target/census, from the moq revision `just ts moq` pins or a checkout. +census checkout="": + #!/usr/bin/env bash + set -euo pipefail + src="{{ checkout }}" + if [ -z "$src" ]; then + (cd ../ts && just moq-pin) + src=../ts/target/moq + fi + cargo run --locked --quiet -- --config moq/ffi.toml --manifest-path "$src/rs/moq-net/Cargo.toml" --census target/census/moq-net.md diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml new file mode 100644 index 000000000..0bf5faebe --- /dev/null +++ b/ffi/moq/ffi.toml @@ -0,0 +1,2 @@ +package = "moq-net" +prefix = "moq" diff --git a/ffi/runtime/rt.rs b/ffi/runtime/rt.rs new file mode 100644 index 000000000..e064a6e31 --- /dev/null +++ b/ffi/runtime/rt.rs @@ -0,0 +1,512 @@ +//! The runtime every export shares: buffers, handles, wakers, and futures across the +//! C ABI. rust2-ffi copies it beside the generated code. +//! +//! A broken contract across the ABI (a null or consumed handle, a handle borrowed in a +//! way Rust's rules forbid, invalid UTF-8, a future polled after it finished) aborts with +//! a message naming the C function: there is no Rust caller to return an error to. + +use std::cell::UnsafeCell; +use std::ffi::c_void; +use std::mem::ManuallyDrop; +use std::ops::{Deref, DerefMut}; +use std::pin::Pin; +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; +use std::task::{Context, Wake}; + +/// Abort with a message naming the C function whose contract was broken. +#[cold] +pub fn fail(what: &str, msg: &str) -> ! { + eprintln!("{what}: {msg}"); + std::process::abort() +} + +/// Bytes across the ABI. Passed in, a view Rust copies or borrows for the call and never +/// frees. Returned, an owned buffer the caller frees once. A null `ptr` is `None`. +#[repr(C)] +#[derive(Clone, Copy)] +pub struct Buf { + pub ptr: *const u8, + pub len: usize, + pub owner: *mut c_void, +} + +impl Buf { + pub const NONE: Self = Self { + ptr: std::ptr::null(), + len: 0, + owner: std::ptr::null_mut(), + }; + + pub fn is_none(&self) -> bool { + self.ptr.is_null() + } + + /// The bytes a caller passed in, which it keeps. + /// + /// # Safety + /// `ptr` points at `len` readable bytes for `'a`. + pub unsafe fn bytes<'a>(self, what: &str) -> &'a [u8] { + match (self.ptr.is_null(), self.len) { + (_, 0) => &[], + (true, _) => fail(what, "a buffer has a length but no pointer"), + // SAFETY: the caller's contract. + (false, len) => unsafe { std::slice::from_raw_parts(self.ptr, len) }, + } + } + + /// The string a caller passed in, which it keeps. + /// + /// # Safety + /// As [`Self::bytes`]. + pub unsafe fn str<'a>(self, what: &str) -> &'a str { + // SAFETY: the caller's contract. + match std::str::from_utf8(unsafe { self.bytes(what) }) { + Ok(s) => s, + Err(_) => fail(what, "a string is not UTF-8"), + } + } + + /// A view of bytes Rust keeps, for a callback to read during its call. + pub fn view(bytes: &[u8]) -> Self { + Self { + ptr: bytes.as_ptr(), + len: bytes.len(), + owner: std::ptr::null_mut(), + } + } + + /// Bytes handed to the caller, which frees them. + pub fn owned(bytes: bytes::Bytes) -> Self { + let ptr = bytes.as_ptr(); + let len = bytes.len(); + let owner = Box::into_raw(Box::new(bytes)).cast(); + Self { ptr, len, owner } + } + + pub fn string(string: String) -> Self { + Self::owned(string.into()) + } + + pub fn vec(vec: Vec) -> Self { + Self::owned(vec.into()) + } + + /// Free a buffer Rust returned; a view or `None` frees nothing. + /// + /// # Safety + /// `owner` is null or came from [`Self::owned`], and is freed once. + pub unsafe fn free(self) { + if !self.owner.is_null() { + // SAFETY: the caller's contract. + drop(unsafe { Box::from_raw(self.owner.cast::()) }); + } + } +} + +#[repr(C)] +#[derive(Clone, Copy)] +pub struct Duration { + pub secs: u64, + pub nanos: u32, +} + +impl Duration { + pub fn lift(self, what: &str) -> std::time::Duration { + if self.nanos >= 1_000_000_000 { + fail(what, "a duration has a billion nanoseconds or more"); + } + std::time::Duration::new(self.secs, self.nanos) + } + + pub fn lower(duration: std::time::Duration) -> Self { + Self { + secs: duration.as_secs(), + nanos: duration.subsec_nanos(), + } + } +} + +pub fn char(code: u32, what: &str) -> char { + char::from_u32(code).unwrap_or_else(|| fail(what, "a char is not a Unicode scalar value")) +} + +const EXCLUSIVE: usize = usize::MAX; +const TAKEN: usize = usize::MAX - 1; + +/// A value behind a handle: shared through an `Arc`, and borrowed as Rust borrows it, with +/// the borrow checked at run time. `state` counts shared borrows, or is [`EXCLUSIVE`] +/// while one exclusive borrow lasts, or [`TAKEN`] once the value moved out. +pub struct Object { + state: AtomicUsize, + value: UnsafeCell>, +} + +// SAFETY: the value moves between threads only by `take` or an exclusive borrow, and is +// shared only by shared borrows, which the export takes only of `Sync` types. +unsafe impl Send for Object {} +// SAFETY: as above. +unsafe impl Sync for Object {} + +impl Object { + /// A new handle owning `value`. + pub fn new(value: T) -> *const c_void { + Arc::into_raw(Arc::new(Self { + state: AtomicUsize::new(0), + value: UnsafeCell::new(ManuallyDrop::new(value)), + })) + .cast() + } + + /// # Safety + /// `handle` is null or a live handle of this type. + unsafe fn get<'a>(handle: *const c_void, what: &str) -> &'a Self { + if handle.is_null() { + fail(what, "a handle is null"); + } + // SAFETY: the caller's contract. + unsafe { &*handle.cast::() } + } + + fn acquire(&self, what: &str) { + let mut state = self.state.load(Ordering::Relaxed); + loop { + match state { + TAKEN => fail(what, "a handle's value was moved out"), + EXCLUSIVE => fail(what, "a handle is borrowed exclusively"), + _ => {} + } + match self + .state + .compare_exchange_weak(state, state + 1, Ordering::Acquire, Ordering::Relaxed) + { + Ok(_) => return, + Err(now) => state = now, + } + } + } + + fn acquire_mut(&self, what: &str) { + if let Err(state) = self + .state + .compare_exchange(0, EXCLUSIVE, Ordering::Acquire, Ordering::Relaxed) + { + match state { + TAKEN => fail(what, "a handle's value was moved out"), + _ => fail(what, "a handle is already borrowed"), + } + } + } + + /// Borrow the value shared for a call. + /// + /// # Safety + /// `handle` is a live handle of this type, kept alive through the borrow. + pub unsafe fn borrow<'a>(handle: *const c_void, what: &str) -> Shared<'a, T> { + // SAFETY: the caller's contract. + let object = unsafe { Self::get(handle, what) }; + object.acquire(what); + Shared { object } + } + + /// Borrow the value exclusively for a call. + /// + /// # Safety + /// As [`Self::borrow`]. + pub unsafe fn borrow_mut<'a>(handle: *const c_void, what: &str) -> Exclusive<'a, T> { + // SAFETY: the caller's contract. + let object = unsafe { Self::get(handle, what) }; + object.acquire_mut(what); + Exclusive { object } + } + + /// Borrow the value shared for as long as a future runs, keeping the handle alive. + /// + /// # Safety + /// `handle` is a live handle of this type. + pub unsafe fn borrow_arc(handle: *const c_void, what: &str) -> SharedArc { + // SAFETY: the caller's contract. + let object = unsafe { Self::arc(handle, what) }; + object.acquire(what); + SharedArc { object } + } + + /// Borrow the value exclusively for as long as a future runs. + /// + /// # Safety + /// As [`Self::borrow_arc`]. + pub unsafe fn borrow_mut_arc(handle: *const c_void, what: &str) -> ExclusiveArc { + // SAFETY: the caller's contract. + let object = unsafe { Self::arc(handle, what) }; + object.acquire_mut(what); + ExclusiveArc { object } + } + + /// # Safety + /// `handle` is a live handle of this type. + unsafe fn arc(handle: *const c_void, what: &str) -> Arc { + // SAFETY: the caller's contract. + unsafe { Self::get(handle, what) }; + let ptr = handle.cast::(); + // SAFETY: a live handle holds a count, so one more keeps it alive. + unsafe { + Arc::increment_strong_count(ptr); + Arc::from_raw(ptr) + } + } + + /// Move the value out, leaving the handle to be freed. + /// + /// # Safety + /// As [`Self::borrow`]. + pub unsafe fn take(handle: *const c_void, what: &str) -> T { + // SAFETY: the caller's contract. + let object = unsafe { Self::get(handle, what) }; + if let Err(state) = object + .state + .compare_exchange(0, TAKEN, Ordering::Acquire, Ordering::Relaxed) + { + match state { + TAKEN => fail(what, "a handle's value was moved out"), + _ => fail(what, "a handle is borrowed"), + } + } + // SAFETY: TAKEN excludes every other access, and the value is never read again. + unsafe { ManuallyDrop::take(&mut *object.value.get()) } + } + + /// Release the caller's handle. + /// + /// # Safety + /// `handle` is null or a live handle of this type, released once. + pub unsafe fn free(handle: *const c_void) { + if !handle.is_null() { + // SAFETY: the caller's contract. + drop(unsafe { Arc::from_raw(handle.cast::()) }); + } + } +} + +impl Drop for Object { + fn drop(&mut self) { + if *self.state.get_mut() != TAKEN { + // SAFETY: the last reference is gone and the value was never taken. + unsafe { ManuallyDrop::drop(self.value.get_mut()) }; + } + } +} + +pub struct Shared<'a, T> { + object: &'a Object, +} + +impl Deref for Shared<'_, T> { + type Target = T; + fn deref(&self) -> &T { + // SAFETY: a shared borrow is held. + unsafe { &*self.object.value.get() } + } +} + +impl Drop for Shared<'_, T> { + fn drop(&mut self) { + self.object.state.fetch_sub(1, Ordering::Release); + } +} + +pub struct Exclusive<'a, T> { + object: &'a Object, +} + +impl Deref for Exclusive<'_, T> { + type Target = T; + fn deref(&self) -> &T { + // SAFETY: the exclusive borrow is held. + unsafe { &*self.object.value.get() } + } +} + +impl DerefMut for Exclusive<'_, T> { + fn deref_mut(&mut self) -> &mut T { + // SAFETY: the exclusive borrow is held. + unsafe { &mut *self.object.value.get() } + } +} + +impl Drop for Exclusive<'_, T> { + fn drop(&mut self) { + self.object.state.store(0, Ordering::Release); + } +} + +pub struct SharedArc { + object: Arc>, +} + +impl Deref for SharedArc { + type Target = T; + fn deref(&self) -> &T { + // SAFETY: a shared borrow is held. + unsafe { &*self.object.value.get() } + } +} + +impl Drop for SharedArc { + fn drop(&mut self) { + self.object.state.fetch_sub(1, Ordering::Release); + } +} + +pub struct ExclusiveArc { + object: Arc>, +} + +impl Deref for ExclusiveArc { + type Target = T; + fn deref(&self) -> &T { + // SAFETY: the exclusive borrow is held. + unsafe { &*self.object.value.get() } + } +} + +impl DerefMut for ExclusiveArc { + fn deref_mut(&mut self) -> &mut T { + // SAFETY: the exclusive borrow is held. + unsafe { &mut *self.object.value.get() } + } +} + +impl Drop for ExclusiveArc { + fn drop(&mut self) { + self.object.state.store(0, Ordering::Release); + } +} + +/// A foreign waker: `wake` may be called from any thread, any number of times, until +/// `drop` releases `data`. Either function may be null. +#[repr(C)] +#[derive(Clone, Copy)] +pub struct Waker { + pub wake: Option, + pub drop: Option, + pub data: *mut c_void, +} + +impl Waker { + /// Whether `other` is this waker again, which a poll reuses rather than wrapping anew. + fn same(&self, other: &Self) -> bool { + self.wake.map(|f| f as usize) == other.wake.map(|f| f as usize) && self.data == other.data + } +} + +struct Foreign(Waker); + +// SAFETY: the waker's contract: `wake` and `drop` may be called from any thread. +unsafe impl Send for Foreign {} +// SAFETY: as above. +unsafe impl Sync for Foreign {} + +impl Wake for Foreign { + fn wake(self: Arc) { + self.wake_by_ref(); + } + + fn wake_by_ref(self: &Arc) { + if let Some(wake) = self.0.wake { + // SAFETY: the waker's contract. + unsafe { wake(self.0.data) }; + } + } +} + +impl Drop for Foreign { + fn drop(&mut self) { + if let Some(drop) = self.0.drop { + // SAFETY: the waker's contract; this is the last reference. + unsafe { drop(self.0.data) }; + } + } +} + +/// Writes a finished future's result through the poll's out pointers, returning the poll. +pub type Done = Box i32 + Send>; + +pub const PENDING: i32 = 0; +pub const READY: i32 = 1; +pub const ERROR: i32 = 2; + +/// A future behind a handle, polled from C. +pub struct Future { + future: Option + Send>>>, + /// The last foreign waker, and the Rust waker around it. + waker: Option<(Waker, std::task::Waker)>, + polling: AtomicBool, +} + +impl Future { + pub fn new(future: impl std::future::Future + Send + 'static) -> *mut Self { + Box::into_raw(Box::new(Self { + future: Some(Box::pin(future)), + waker: None, + polling: AtomicBool::new(false), + })) + } + + /// Poll it once with `waker`, writing the result through `out` and `err` when ready. + /// + /// # Safety + /// `future` is a live future handle, and `out` and `err` are null or point where the + /// function's result types go. + pub unsafe fn poll(future: *mut Self, waker: Waker, out: *mut c_void, err: *mut c_void, what: &str) -> i32 { + if future.is_null() { + fail(what, "a future is null"); + } + // SAFETY: the caller's contract; only the flag is touched before it is held. + if unsafe { &*future }.polling.swap(true, Ordering::Acquire) { + fail(what, "a future is polled concurrently"); + } + // SAFETY: the flag makes this the only access. + let this = unsafe { &mut *future }; + let Some(inner) = this.future.as_mut() else { + fail(what, "a future is polled after it finished"); + }; + if !this.waker.as_ref().is_some_and(|(last, _)| last.same(&waker)) { + this.waker = Some((waker, std::task::Waker::from(Arc::new(Foreign(waker))))); + } + let (_, rust) = this.waker.as_ref().expect("set above"); + let mut cx = Context::from_waker(rust); + let poll = inner.as_mut().poll(&mut cx); + let result = match poll { + std::task::Poll::Pending => PENDING, + std::task::Poll::Ready(done) => { + this.future = None; + this.waker = None; + done(out, err) + } + }; + this.polling.store(false, Ordering::Release); + result + } + + /// Drop the future, cancelling it if it has not finished. + /// + /// # Safety + /// `future` is null or a live future handle, freed once and not being polled. + pub unsafe fn free(future: *mut Self) { + if !future.is_null() { + // SAFETY: the caller's contract. + drop(unsafe { Box::from_raw(future) }); + } + } +} + +/// Write `value` through `out` if the caller wants it, or drop it. +/// +/// # Safety +/// `out` is null or points where a `T` goes. +pub unsafe fn write(out: *mut c_void, value: impl FnOnce() -> T) { + if !out.is_null() { + // SAFETY: the caller's contract. + unsafe { out.cast::().write(value()) }; + } +} diff --git a/ffi/rust-toolchain.toml b/ffi/rust-toolchain.toml new file mode 120000 index 000000000..6a0f853eb --- /dev/null +++ b/ffi/rust-toolchain.toml @@ -0,0 +1 @@ +../ts/rust-toolchain.toml \ No newline at end of file diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs new file mode 100644 index 000000000..ebcbab05e --- /dev/null +++ b/ffi/src/abi.rs @@ -0,0 +1,443 @@ +//! The C ABI the IR becomes: every C name, and every function's C signature, decided +//! once so the header and the Rust side agree. +//! +//! Names follow one rule: the prefix, then the item's path from the crate root, each +//! segment in snake case, joined by `_`; a method's path goes through its type's. Joining +//! loses where segments split (`audio_encoder::finish` and `audio::encoder_finish` are both +//! `moq_audio_encoder_finish`), so every name is registered, and a second item claiming +//! one is a compile error at both spans rather than a silent clash. + +use std::collections::{BTreeMap, HashMap}; + +use rustc_span::Span; + +use crate::ir::{Api, Dyn, Function, Int, Receiver, Type}; + +/// A C type, as a parameter, field, or return value takes it. +#[derive(Clone, PartialEq, Eq, Debug)] +pub enum Ty { + Void, + Bool, + Int(Int), + F32, + F64, + /// A `char`, as its code point. + Char, + /// `_buf`: a view of bytes passed in, an owned buffer returned. + Buf, + /// `_duration` + Duration, + /// A struct: a record, a data enum, an option, or a callback's table and data. + Struct(String), + /// A plain enum, passed as its C enum, which is an `int`. + Enum(String), + /// A handle: `const` when only borrowed. + Handle { name: String, constant: bool }, + /// A future's handle. + Future(String), + /// `_waker` + Waker, + /// `_poll` + Poll, + /// A pointer the callee writes a result through. + Out(Box), + /// A pointer the callee only reads through: a value's receiver. + In(Box), +} + +/// A C function: its name, parameters, and return type. +pub struct Sig { + pub name: String, + pub params: Vec<(String, Ty)>, + pub ret: Ty, +} + +/// The C side of an exported function. +pub struct Export { + /// The function itself: for a future, the call that makes it. + pub call: Sig, + /// For a future: its handle type, its poll, and its free. + pub future: Option<(String, Sig, Sig)>, +} + +pub struct Abi<'a> { + pub api: &'a Api, + pub prefix: String, + /// Each `Option` struct by C name, with `T`. + pub options: BTreeMap, + /// Every C name claimed, with what claimed it. + names: HashMap, + /// Each name claimed twice: the name, then both claimants. + pub clashes: Vec<(String, (String, Span), (String, Span))>, +} + +impl<'a> Abi<'a> { + pub fn new(api: &'a Api, prefix: &str) -> Self { + let mut abi = Self { + api, + prefix: prefix.to_string(), + options: BTreeMap::new(), + names: HashMap::new(), + clashes: Vec::new(), + }; + abi.claim_all(); + abi + } + + /// The C name for a path from the crate root. + pub fn name(&self, path: &[String]) -> String { + let mut name = self.prefix.clone(); + for segment in path { + name.push('_'); + name.push_str(&snake(segment)); + } + name + } + + /// A constant's name for a path: the name in upper case. + pub fn constant(&self, path: &[String]) -> String { + self.name(path).to_uppercase() + } + + pub fn record(&self, i: usize) -> String { + self.name(&self.api.records[i].path) + } + + pub fn enumeration(&self, i: usize) -> String { + self.name(&self.api.enums[i].path) + } + + pub fn object(&self, i: usize) -> String { + self.name(&self.api.objects[i].path) + } + + pub fn callback(&self, i: usize) -> String { + self.name(&self.api.callbacks[i].path) + } + + /// The prefixed name of a runtime item: `buf` is `moq_buf`. + pub fn rt(&self, name: &str) -> String { + format!("{}_{name}", self.prefix) + } + + /// The C name of `Option`'s struct. + pub fn option(&self, inner: &Type) -> String { + format!("{}_option_{}", self.prefix, self.key(inner)) + } + + /// A type's name within the prefix, for naming the structs built from it. + fn key(&self, ty: &Type) -> String { + let strip = |name: String| name[self.prefix.len() + 1..].to_string(); + match ty { + Type::Bool => "bool".to_string(), + Type::Int(int) => int.rust().to_string(), + Type::F32 => "f32".to_string(), + Type::F64 => "f64".to_string(), + Type::Char => "char".to_string(), + Type::Duration => "duration".to_string(), + Type::Record(i) => strip(self.record(*i)), + Type::Enum(i) => strip(self.enumeration(*i)), + Type::Ref(_, inner) | Type::Box(inner) => self.key(inner), + other => unreachable!("no option struct holds {other:?}"), + } + } + + /// Whether `ty` crosses as a `_buf`. + pub fn is_buf(ty: &Type) -> bool { + matches!( + ty.base(), + Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes + ) + } + + /// The C type of `ty` as a value: a parameter, field, or what a function returns. + pub fn ty(&self, ty: &Type) -> Ty { + match ty { + Type::Unit => Ty::Void, + Type::Bool => Ty::Bool, + Type::Int(int) => Ty::Int(*int), + Type::F32 => Ty::F32, + Type::F64 => Ty::F64, + Type::Char => Ty::Char, + Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes => Ty::Buf, + Type::Duration => Ty::Duration, + Type::Option(inner) => match inner.base() { + Type::Object(_) => self.ty(inner), + base if Self::is_buf(base) => Ty::Buf, + _ => Ty::Struct(self.option(inner)), + }, + Type::Box(inner) => self.ty(inner), + Type::Ref(m, inner) => match &**inner { + Type::Object(i) => Ty::Handle { + name: self.object(*i), + constant: *m == crate::ir::Mutability::Not, + }, + inner => self.ty(inner), + }, + Type::Record(i) => Ty::Struct(self.record(*i)), + Type::Enum(i) => match self.api.enums[*i].plain() { + true => Ty::Enum(self.enumeration(*i)), + false => Ty::Struct(self.enumeration(*i)), + }, + Type::Object(i) => Ty::Handle { + name: self.object(*i), + constant: false, + }, + Type::Callback(i, _) => Ty::Struct(self.callback(*i)), + } + } + + /// The C signature of `function`, a method of the type named `owner` if it has one. + pub fn export(&self, function: &Function, owner: Option<&Ty>) -> Export { + let name = self.name(&function.path); + let mut params = Vec::new(); + if let (Some(receiver), Some(owner)) = (function.receiver, owner) { + let ty = match owner { + Ty::Handle { name, .. } => Ty::Handle { + name: name.clone(), + constant: receiver == Receiver::Ref, + }, + // A value's receiver is read through a pointer, and never changed. + value => Ty::In(Box::new(value.clone())), + }; + params.push(("self".to_string(), ty)); + } + for param in &function.params { + params.push((escape(¶m.name), self.ty(¶m.ty))); + } + let mut outs = Vec::new(); + if function.ok != Type::Unit { + outs.push(("out".to_string(), Ty::Out(Box::new(self.ty(&function.ok))))); + } + if let Some(err) = &function.err { + outs.push(("err".to_string(), Ty::Out(Box::new(self.ty(err))))); + } + if function.future { + let handle = format!("{name}_future"); + let mut poll_params = vec![ + ("future".to_string(), Ty::Future(handle.clone())), + ("waker".to_string(), Ty::Waker), + ]; + poll_params.extend(outs); + let poll = Sig { + name: format!("{name}_poll"), + params: poll_params, + ret: Ty::Poll, + }; + let free = Sig { + name: format!("{name}_future_free"), + params: vec![("future".to_string(), Ty::Future(handle.clone()))], + ret: Ty::Void, + }; + return Export { + call: Sig { + name, + params, + ret: Ty::Future(handle.clone()), + }, + future: Some((handle, poll, free)), + }; + } + let ret = match &function.err { + Some(_) => { + params.extend(outs); + Ty::Bool + } + None => self.ty(&function.ok), + }; + Export { + call: Sig { name, params, ret }, + future: None, + } + } + + fn claim(&mut self, name: String, what: String, span: Span) { + match self.names.get(&name) { + Some(first) => self.clashes.push((name, first.clone(), (what, span))), + None => { + self.names.insert(name, (what, span)); + } + } + } + + /// Claim every name the export defines, and note each option struct. + fn claim_all(&mut self) { + let api = self.api; + let crate_span = api + .records + .first() + .map(|r| r.span) + .or_else(|| api.objects.first().map(|o| o.span)) + .unwrap_or(rustc_span::DUMMY_SP); + for runtime in ["buf", "buf_free", "duration", "waker", "poll"] { + self.claim(self.rt(runtime), "the runtime".to_string(), crate_span); + } + for constant in ["POLL_PENDING", "POLL_READY", "POLL_ERROR"] { + let name = format!("{}_{constant}", self.prefix.to_uppercase()); + self.claim(name, "the runtime".to_string(), crate_span); + } + let mut types: Vec<&Type> = Vec::new(); + let mut functions: Vec<(&Function, Option)> = Vec::new(); + for (i, record) in api.records.iter().enumerate() { + let name = self.record(i); + let what = format!("struct `{}`", record.path.join("::")); + self.claim_traits(&name, &what, record.span, record.traits, true); + self.claim(name.clone(), what, record.span); + types.extend(record.fields.iter().map(|f| &f.ty)); + functions.extend(record.methods.iter().map(|m| (m, Some(Ty::Struct(name.clone()))))); + } + for (i, e) in api.enums.iter().enumerate() { + let name = self.enumeration(i); + let what = format!("enum `{}`", e.path.join("::")); + let upper = name.to_uppercase(); + for variant in &e.variants { + self.claim(format!("{upper}_{}", snake(&variant.name).to_uppercase()), what.clone(), e.span); + types.extend(variant.fields.iter().map(|f| &f.ty)); + } + 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()) { + self.claim(format!("{name}_{}", snake(&variant.name)), what.clone(), e.span); + } + } + self.claim_traits(&name, &what, e.span, e.traits, !plain); + self.claim(name.clone(), what, e.span); + let owner = match plain { + true => Ty::Enum(name.clone()), + false => Ty::Struct(name.clone()), + }; + functions.extend(e.methods.iter().map(|m| (m, Some(owner.clone())))); + } + for (i, object) in api.objects.iter().enumerate() { + let name = self.object(i); + let what = format!("type `{}`", object.path.join("::")); + self.claim(format!("{name}_free"), what.clone(), object.span); + self.claim_traits(&name, &what, object.span, object.traits, false); + self.claim(name.clone(), what, object.span); + let owner = Ty::Handle { name, constant: false }; + functions.extend(object.methods.iter().map(|m| (m, Some(owner.clone())))); + } + for (i, callback) in api.callbacks.iter().enumerate() { + let name = self.callback(i); + let what = format!("trait `{}`", callback.path.join("::")); + self.claim(format!("{name}_vtable"), what.clone(), callback.span); + self.claim(name, what, callback.span); + for method in &callback.methods { + types.extend(method.params.iter().map(|p| &p.ty)); + types.push(&method.ok); + types.extend(&method.err); + } + } + functions.extend(api.functions.iter().map(|f| (f, None))); + for (function, owner) in functions { + let export = self.export(function, owner.as_ref()); + let what = format!("fn `{}`", function.path.join("::")); + self.claim(export.call.name.clone(), what.clone(), function.span); + if let Some((handle, poll, free)) = &export.future { + self.claim(handle.clone(), what.clone(), function.span); + self.claim(poll.name.clone(), what.clone(), function.span); + self.claim(free.name.clone(), what.clone(), function.span); + } + types.extend(function.params.iter().map(|p| &p.ty)); + types.push(&function.ok); + types.extend(&function.err); + } + for constant in &api.constants { + self.claim( + self.constant(&constant.path), + format!("const `{}`", constant.path.join("::")), + constant.span, + ); + } + let mut options = BTreeMap::new(); + let mut stack = types; + while let Some(ty) = stack.pop() { + match ty { + Type::Option(inner) => { + if !matches!(inner.base(), Type::Object(_)) && !Self::is_buf(inner) { + options.insert(self.option(inner), (**inner).clone()); + } + stack.push(inner); + } + Type::Ref(_, inner) | Type::Box(inner) => stack.push(inner), + _ => {} + } + } + for (name, _) in &options { + self.claim(name.clone(), "an option".to_string(), crate_span); + } + self.options = options; + } + + /// Claim the functions a type's std traits export. + fn claim_traits(&mut self, name: &str, what: &str, span: Span, traits: crate::ir::Traits, owned: bool) { + let mut claim = |suffix: &str| self.claim(format!("{name}_{suffix}"), what.to_string(), span); + if traits.clone && !owned { + claim("clone"); + } + if traits.eq { + claim("eq"); + } + if traits.display { + claim("to_string"); + } + if traits.debug { + claim("debug"); + } + if traits.default { + claim("default"); + } + if owned { + claim("free"); + } + } +} + +/// A Rust identifier in snake case: `TrackProducer` is `track_producer`, and a name +/// already in snake case stays as it is. +pub fn snake(name: &str) -> String { + let chars: Vec = name.chars().collect(); + let mut out = String::new(); + for (i, &c) in chars.iter().enumerate() { + if c.is_uppercase() { + let prev = i.checked_sub(1).map(|j| chars[j]); + let next = chars.get(i + 1); + let boundary = match prev { + Some(p) if p.is_lowercase() || p.is_ascii_digit() => true, + Some(p) if p.is_uppercase() => next.is_some_and(|n| n.is_lowercase()), + _ => false, + }; + if boundary && !out.ends_with('_') { + out.push('_'); + } + out.extend(c.to_lowercase()); + } else { + out.push(c); + } + } + out +} + +/// A name that C would read as a keyword, with `_` appended. +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", + ]; + match KEYWORDS.contains(&name) || name.chars().next().is_some_and(|c| c.is_ascii_digit()) { + true => format!("_{name}"), + false => name.to_string(), + } +} + +/// What a callback parameter needs, by the form it takes. +pub fn dyn_wrap(form: Dyn, expr: &str) -> String { + match form { + Dyn::Impl => expr.to_string(), + Dyn::Box => format!("::std::boxed::Box::new({expr})"), + Dyn::Arc => format!("::std::sync::Arc::new({expr})"), + } +} diff --git a/ffi/src/c.rs b/ffi/src/c.rs new file mode 100644 index 000000000..8c5ef9c67 --- /dev/null +++ b/ffi/src/c.rs @@ -0,0 +1,327 @@ +//! The C header: the declarations of everything [`crate::glue`] defines. + +use std::collections::BTreeSet; + +use crate::abi::{self, Abi, Sig, Ty}; +use crate::ir::{Function, Int, Literal, Traits, Type}; + +/// The header for `abi`, as `.h`. +pub fn header(abi: &Abi<'_>, package: &str) -> String { + let mut h = Header { + abi, + out: String::new(), + defined: BTreeSet::new(), + }; + h.write(package); + h.out +} + +struct Header<'a> { + abi: &'a Abi<'a>, + out: String, + /// The value structs written so far, so each is written after what it holds. + defined: BTreeSet, +} + +impl Header<'_> { + fn line(&mut self, line: impl AsRef) { + self.out.push_str(line.as_ref()); + 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}"))), + } + } + + fn prototype(&self, sig: &Sig) -> String { + let params: Vec = sig.params.iter().map(|(n, ty)| self.decl(ty, n)).collect(); + let params = match params.is_empty() { + true => "void".to_string(), + false => params.join(", "), + }; + format!("{};", self.decl(&sig.ret, &format!("{}({params})", sig.name))) + } + + fn write(&mut self, package: &str) { + let abi = self.abi; + let api = abi.api; + let p = abi.prefix.clone(); + let guard = format!("{}_H", p.to_uppercase()); + let upper = p.to_uppercase(); + self.line(format!( + "/* Generated by rust2-ffi: the C ABI of {package}'s pub API. Do not edit. */\n" + )); + self.line(format!("#ifndef {guard}\n#define {guard}\n")); + self.line("#include \n#include \n#include \n"); + self.line("#ifdef __cplusplus\nextern \"C\" {\n#endif\n"); + self.line(format!( + "/* Bytes. Passed in, a view Rust reads during the call and never frees. Returned,\n * an owned buffer to free once with {p}_buf_free. A null ptr is None. */\ntypedef struct {p}_buf {{\n\tconst uint8_t *ptr;\n\tsize_t len;\n\tvoid *owner;\n}} {p}_buf;\n\nvoid {p}_buf_free({p}_buf buf);\n" + )); + self.line(format!( + "typedef struct {p}_duration {{\n\tuint64_t secs;\n\tuint32_t nanos;\n}} {p}_duration;\n" + )); + self.line(format!( + "/* Wakes a future's poller: wake may be called from any thread, any number of\n * times, until drop releases data. A poll passing the same wake and data again\n * reuses the waker. Either function may be null. */\ntypedef struct {p}_waker {{\n\tvoid (*wake)(void *data);\n\tvoid (*drop)(void *data);\n\tvoid *data;\n}} {p}_waker;\n" + )); + self.line(format!( + "typedef enum {p}_poll {{\n\t{upper}_POLL_PENDING = 0,\n\t{upper}_POLL_READY = 1,\n\t{upper}_POLL_ERROR = 2,\n}} {p}_poll;\n" + )); + + // Handles, each opaque. + for i in 0..api.objects.len() { + let name = abi.object(i); + self.line(format!("typedef struct {name} {name};")); + } + self.line(""); + + // Plain enums. + for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| e.plain()) { + let name = abi.enumeration(i); + let upper = name.to_uppercase(); + let variants: Vec = e + .variants + .iter() + .map(|v| format!("\t{upper}_{} = {},", abi::snake(&v.name).to_uppercase(), v.discriminant)) + .collect(); + self.line(format!("typedef enum {name} {{\n{}\n}} {name};\n", variants.join("\n"))); + } + + // Value structs, each after the values it holds. + for name in abi.options.keys() { + self.value(&Ty::Struct(name.clone())); + } + for i in 0..api.records.len() { + self.value(&Ty::Struct(abi.record(i))); + } + for (i, _) in api.enums.iter().enumerate().filter(|(_, e)| !e.plain()) { + self.value(&Ty::Struct(abi.enumeration(i))); + } + + for constant in &api.constants { + let value = match constant.value { + Literal::Bool(b) => b.to_string(), + Literal::Int(int, v) => c_literal(int, v), + }; + self.line(format!("#define {} {value}", abi.constant(&constant.path))); + } + if !api.constants.is_empty() { + self.line(""); + } + + for (i, record) in api.records.iter().enumerate() { + let name = abi.record(i); + self.line(format!("/* {} */", record.path.join("::"))); + self.value_functions(&name, Ty::Struct(name.clone()), record.traits, true); + let owner = Ty::Struct(name.clone()); + for method in &record.methods { + self.function(method, Some(&owner)); + } + self.line(""); + } + for (i, e) in api.enums.iter().enumerate() { + let name = abi.enumeration(i); + let ty = abi.ty(&Type::Enum(i)); + if e.methods.is_empty() && !has(e.traits) && e.plain() { + continue; + } + self.line(format!("/* {} */", e.path.join("::"))); + self.value_functions(&name, ty.clone(), e.traits, !e.plain()); + for method in &e.methods { + self.function(method, Some(&ty)); + } + self.line(""); + } + for (i, object) in api.objects.iter().enumerate() { + let name = abi.object(i); + self.line(format!("/* {} */", object.path.join("::"))); + self.line(format!("void {name}_free({name} *self);")); + let t = object.traits; + if t.clone { + self.line(format!("{name} *{name}_clone(const {name} *self);")); + } + if t.eq { + self.line(format!("bool {name}_eq(const {name} *a, const {name} *b);")); + } + if t.display { + self.line(format!("{p}_buf {name}_to_string(const {name} *self);")); + } + if t.debug { + self.line(format!("{p}_buf {name}_debug(const {name} *self);")); + } + if t.default { + self.line(format!("{name} *{name}_default(void);")); + } + let owner = Ty::Handle { + name: name.clone(), + constant: false, + }; + for method in &object.methods { + self.function(method, Some(&owner)); + } + self.line(""); + } + for function in &api.functions { + self.function(function, None); + } + self.line("\n#ifdef __cplusplus\n}\n#endif\n"); + self.line(format!("#endif /* {guard} */")); + } + + /// A value struct, after the structs its fields hold. + fn value(&mut self, ty: &Ty) { + let abi = self.abi; + let Ty::Struct(name) = ty else { + return; + }; + if !self.defined.insert(name.clone()) { + return; + } + if let Some(inner) = abi.options.get(name) { + let inner = abi.ty(inner); + self.value(&inner); + let value = self.decl(&inner, "value"); + self.line(format!("typedef struct {name} {{\n\tbool some;\n\t{value};\n}} {name};\n")); + return; + } + if let Some(i) = (0..abi.api.records.len()).find(|&i| &abi.record(i) == name) { + let record = &abi.api.records[i]; + let fields: Vec = record.fields.iter().map(|f| abi.ty(&f.ty)).collect(); + for field in &fields { + self.value(field); + } + let decls: Vec = record + .fields + .iter() + .zip(&fields) + .map(|(f, ty)| format!("\t{};", self.decl(ty, &abi::escape(&f.name)))) + .collect(); + self.line(format!("typedef struct {name} {{\n{}\n}} {name};\n", decls.join("\n"))); + return; + } + let Some(i) = (0..abi.api.enums.len()).find(|&i| &abi.enumeration(i) == name) else { + return; + }; + let e = &abi.api.enums[i]; + let upper = name.to_uppercase(); + let tags: Vec = e + .variants + .iter() + .enumerate() + .map(|(n, v)| format!("\t{upper}_{} = {n},", abi::snake(&v.name).to_uppercase())) + .collect(); + self.line(format!("typedef enum {name}_tag {{\n{}\n}} {name}_tag;\n", tags.join("\n"))); + let mut members = Vec::new(); + for variant in e.variants.iter().filter(|v| !v.fields.is_empty()) { + let payload = format!("{name}_{}", abi::snake(&variant.name)); + let fields: Vec = variant.fields.iter().map(|f| abi.ty(&f.ty)).collect(); + for field in &fields { + self.value(field); + } + let decls: Vec = variant + .fields + .iter() + .zip(&fields) + .map(|(f, ty)| format!("\t{};", self.decl(ty, &abi::escape(&f.name)))) + .collect(); + self.line(format!("typedef struct {payload} {{\n{}\n}} {payload};\n", decls.join("\n"))); + members.push(format!("\t\t{payload} {};", abi::escape(&abi::snake(&variant.name)))); + } + self.line(format!( + "typedef struct {name} {{\n\t{name}_tag tag;\n\tunion {{\n{}\n\t}};\n}} {name};\n", + members.join("\n") + )); + } + + /// The functions a value type's std traits export, and its `free` if it owns memory. + fn value_functions(&mut self, name: &str, ty: Ty, traits: Traits, free: bool) { + let p = &self.abi.prefix; + let this = self.decl(&Ty::In(Box::new(ty.clone())), "self"); + let a = self.decl(&Ty::In(Box::new(ty.clone())), "a"); + let b = self.decl(&Ty::In(Box::new(ty.clone())), "b"); + if free { + self.line(format!("void {name}_free({name} *self);")); + } + if traits.eq { + self.line(format!("bool {name}_eq({a}, {b});")); + } + if traits.display { + self.line(format!("{p}_buf {name}_to_string({this});")); + } + if traits.debug { + self.line(format!("{p}_buf {name}_debug({this});")); + } + if traits.default { + self.line(format!("{} {name}_default(void);", self.decl(&ty, ""))); + } + } + + fn function(&mut self, function: &Function, owner: Option<&Ty>) { + let export = self.abi.export(function, owner); + if let Some((handle, poll, free)) = &export.future { + self.line(format!("typedef struct {handle} {handle};")); + let call = self.prototype(&export.call); + let poll = self.prototype(poll); + let free = self.prototype(free); + self.line(call); + self.line(poll); + self.line(free); + return; + } + let call = self.prototype(&export.call); + self.line(call); + } +} + +fn has(traits: Traits) -> bool { + traits.eq || traits.display || traits.debug || traits.default +} + +fn c_int(int: Int) -> &'static str { + match int { + Int::U8 => "uint8_t", + Int::U16 => "uint16_t", + Int::U32 => "uint32_t", + Int::U64 => "uint64_t", + Int::Usize => "size_t", + Int::I8 => "int8_t", + Int::I16 => "int16_t", + Int::I32 => "int32_t", + Int::I64 => "int64_t", + Int::Isize => "ptrdiff_t", + } +} + +/// An integer constant, typed as its Rust type. +fn c_literal(int: Int, v: i128) -> String { + match int { + Int::U64 | Int::Usize => format!("(({}){v}ULL)", c_int(int)), + Int::I64 | Int::Isize if v == i64::MIN as i128 => format!("(({})(-9223372036854775807LL - 1))", c_int(int)), + Int::I64 | Int::Isize => format!("(({}){v}LL)", c_int(int)), + Int::U32 => format!("(({}){v}U)", c_int(int)), + _ => format!("(({}){v})", c_int(int)), + } +} diff --git a/ffi/src/census.rs b/ffi/src/census.rs new file mode 100644 index 000000000..0b82ae61a --- /dev/null +++ b/ffi/src/census.rs @@ -0,0 +1,150 @@ +//! The census: what a crate's `pub` API exports, and every item the export refuses, +//! ranked by why, so the next mapping to build is picked from numbers. + +use std::collections::BTreeMap; +use std::fmt::Write; + +use rustc_span::Span; + +use crate::collect::{Collected, Refusal}; + +/// The census of `krate` as Markdown; `at` locates a span. +pub fn render(krate: &str, collected: &Collected, at: &dyn Fn(Span) -> String) -> String { + let api = &collected.api; + let refused = |kinds: &[&str]| collected.refusals.iter().filter(|r| kinds.contains(&r.kind)).count(); + let methods: usize = api.objects.iter().map(|o| o.methods.len()).sum::() + + api.records.iter().map(|r| r.methods.len()).sum::() + + api.enums.iter().map(|e| e.methods.len()).sum::(); + let types = api.records.len() + api.enums.len() + api.objects.len(); + + let mut out = String::new(); + let _ = writeln!(out, "# Export census of `{krate}`\n"); + let _ = writeln!(out, "| Item | Exported | Refused | Share exported |\n| --- | ---: | ---: | ---: |"); + let mut row = |name: &str, exported: usize, refused: usize| { + let total = exported + refused; + let share = match total { + 0 => "-".to_string(), + _ => format!("{}%", exported * 100 / total), + }; + let _ = writeln!(out, "| {name} | {exported} | {refused} | {share} |"); + }; + row("Types", types, refused(&["struct", "enum", "union"])); + row("Functions", api.functions.len(), refused(&["fn"])); + row("Methods of exported types", methods, refused(&["method"])); + row("Traits", api.callbacks.len(), refused(&["trait"])); + row("Constants", api.constants.len(), refused(&["const"])); + row("Other items", 0, refused(&["use", "macro", "static", "item"])); + let _ = writeln!( + out, + "\nExported types: {} records, {} enums, {} objects. A refused type's methods are not counted.", + api.records.len(), + api.enums.len(), + api.objects.len() + ); + + // Each item counts once per construct, however many times it hits it. + let mut constructs: BTreeMap<&str, Vec<&Refusal>> = BTreeMap::new(); + let mut details: BTreeMap<(&str, &str), Vec<&Refusal>> = BTreeMap::new(); + let mut occurrences: BTreeMap<&str, usize> = BTreeMap::new(); + for refusal in &collected.refusals { + let mut seen = Vec::new(); + for why in &refusal.why { + *occurrences.entry(why.construct).or_default() += 1; + if !seen.contains(&why.construct) { + seen.push(why.construct); + constructs.entry(why.construct).or_default().push(refusal); + } + if !why.detail.is_empty() { + let list = details.entry((why.construct, &why.detail)).or_default(); + if !list.iter().any(|r| std::ptr::eq(*r, refusal)) { + list.push(refusal); + } + } + } + } + + let _ = writeln!(out, "\n## Refusals by construct\n"); + let _ = writeln!( + out, + "Items refused for each construct; an item refused for several counts under each.\n" + ); + let _ = writeln!(out, "| Items | Uses | Construct | First |\n| ---: | ---: | --- | --- |"); + for (construct, list) in ranked(&constructs) { + let _ = writeln!( + out, + "| {} | {} | {} | {} |", + list.len(), + occurrences[construct], + construct, + at(list[0].span) + ); + } + + let _ = writeln!(out, "\n## Refusals by type or path\n"); + let _ = writeln!(out, "| Items | Construct | Names | First |\n| ---: | --- | --- | --- |"); + for ((construct, detail), list) in ranked(&details) { + let _ = writeln!( + out, + "| {} | {} | `{}` | {} |", + list.len(), + construct, + detail.replace('|', "\\|"), + at(list[0].span) + ); + } + + let _ = writeln!(out, "\n## Refused items\n"); + let mut refusals: Vec<&Refusal> = collected.refusals.iter().collect(); + refusals.sort_by(|a, b| a.path.cmp(&b.path)); + for refusal in refusals { + let reasons: Vec = refusal + .why + .iter() + .map(|why| match why.detail.is_empty() { + true => why.construct.to_string(), + false => format!("{} `{}`", why.construct, why.detail), + }) + .collect(); + let _ = writeln!( + out, + "- {} `{}` at {}: {}", + refusal.kind, + refusal.path, + at(refusal.span), + reasons.join("; ") + ); + } + + if !collected.opaque.is_empty() { + let _ = writeln!(out, "\n## Values exported as objects, since a field does not map\n"); + for (path, why) in &collected.opaque { + let _ = writeln!(out, "- `{path}`: {} `{}`", why.construct, why.detail); + } + } + if !collected.excluded.is_empty() { + let _ = writeln!(out, "\n## Excluded by the config\n"); + for (path, count) in &collected.excluded { + let _ = writeln!(out, "- `{path}`: {count} items"); + } + } + if !collected.hidden.is_empty() { + let _ = writeln!(out, "\n## `#[doc(hidden)]`, left out\n"); + for path in &collected.hidden { + let _ = writeln!(out, "- `{path}`"); + } + } + if !collected.aliases.is_empty() { + let _ = writeln!(out, "\n## Type aliases, which export nothing of their own\n"); + for path in &collected.aliases { + let _ = writeln!(out, "- `{path}`"); + } + } + out +} + +/// Groups by count, most first, then by key. +fn ranked<'a, K: Ord, V>(groups: &'a BTreeMap>) -> Vec<(&'a K, &'a Vec)> { + let mut ranked: Vec<_> = groups.iter().collect(); + ranked.sort_by(|a, b| b.1.len().cmp(&a.1.len()).then_with(|| a.0.cmp(b.0))); + ranked +} diff --git a/ffi/src/cli.rs b/ffi/src/cli.rs new file mode 100644 index 000000000..8ffa09670 --- /dev/null +++ b/ffi/src/cli.rs @@ -0,0 +1,48 @@ +//! The command line: run cargo on the configured package with this binary as rustc. + +use std::process::ExitCode; + +use rust2_driver::cargo::{Args, Check, Output}; + +use crate::config::{self, Config}; + +const USAGE: &str = "usage: rust2-ffi --config (--out | --census ) [--manifest-path ] [-- ] + +Exports the pub API of the library of the package that ffi.toml names: a crate in +that builds the C ABI, with its C header in /include. The package's Cargo.toml is +beside ffi.toml unless --manifest-path says where. Cargo args, such as --features, are +passed to `cargo check`. + +--census writes a Markdown report of what exports and of every construct the export +refuses, instead of exporting."; + +pub fn run(args: &[String]) -> ExitCode { + match try_run(args) { + Ok(code) => code, + Err(err) => { + eprintln!("rust2-ffi: {err}"); + ExitCode::FAILURE + } + } +} + +fn try_run(args: &[String]) -> Result { + let Some(args) = Args::parse(args, USAGE)? else { + return Ok(ExitCode::SUCCESS); + }; + let config = Config::load(&args.config)?; + let output = match &args.output { + Output::Dir(out) => (config::env::OUT, out.as_os_str()), + Output::Census(census) => (config::env::CENSUS, census.as_os_str()), + }; + Check { + tool: "rust2-ffi", + manifest: &args.manifest, + package: &config.package, + // The host's: a C ABI is the platform's. + target: None, + args: &args.cargo, + env: &[(config::env::CONFIG, args.config.as_os_str()), output], + } + .run() +} diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs new file mode 100644 index 000000000..161ef566e --- /dev/null +++ b/ffi/src/collect.rs @@ -0,0 +1,953 @@ +//! The crate's `pub` API, as rustc checked it, to the [IR](crate::ir). +//! +//! Every `pub` item reachable from the crate root is exported by fixed rules, or refused +//! with its span. Nothing is opted in by attribute and nothing is skipped silently: the +//! config's `exclude` is the only way to leave an item out, and `#[doc(hidden)]` items, +//! which are no part of the documented API, are listed in the census. + +use std::collections::VecDeque; + +use rustc_hir::def::{DefKind, Res}; +use rustc_hir::def_id::{CRATE_DEF_ID, DefId}; +use rustc_infer::infer::TyCtxtInferExt; +use rustc_infer::traits::{Obligation, ObligationCause}; +use rustc_middle::ty::{self, GenericArgKind, Ty, TyCtxt, TypingEnv}; +use rustc_span::{Span, sym}; +use rustc_trait_selection::infer::InferCtxtExt; +use rustc_trait_selection::traits::query::evaluate_obligation::InferCtxtExt as _; + +use crate::config::Config; +use crate::ir::{ + Api, Callback, Constant, Dyn, Enum, Field, Function, Int, Literal, Mutability, Object, Param, Path, Receiver, + Record, Traits, Type, Variant, +}; + +/// Why something is refused: a construct, ranked by the census, and what it names. +#[derive(Clone, Debug)] +pub struct Why { + pub construct: &'static str, + pub detail: String, +} + +fn why(construct: &'static str, detail: impl Into) -> Why { + Why { + construct, + detail: detail.into(), + } +} + +/// An item the export refuses, with every reason found. +pub struct Refusal { + /// Its path from the crate root. + pub path: String, + /// What kind of item it is: `fn`, `method`, `struct`, ... + pub kind: &'static str, + pub span: Span, + pub why: Vec, +} + +/// What collection found. +pub struct Collected { + pub api: Api, + pub refusals: Vec, + /// Records and enums exported as objects, since a field does not map: the first. + pub opaque: Vec<(String, Why)>, + /// `#[doc(hidden)]` items, by path. + pub hidden: Vec, + /// Excluded paths, and how many items each left out. + pub excluded: Vec<(String, usize)>, + /// Type aliases, which export nothing of their own. + pub aliases: Vec, +} + +/// How a local type is exported, once decided. +#[derive(Clone)] +enum Decl { + Record(usize), + Enum(usize), + Object(usize), + Callback(usize), + Refused(Why), +} + +struct Collector<'a, 'tcx> { + tcx: TyCtxt<'tcx>, + config: &'a Config, + /// Each `pub` item and its shortest path, in the order the walk met them. + items: Vec<(DefId, Path)>, + decls: rustc_data_structures::fx::FxHashMap, + refusals: Vec, + hidden: Vec, + excluded: Vec<(String, usize)>, + aliases: Vec, + /// Local items the walk left out, and why: `excluded` or `doc(hidden)`. + left_out: rustc_data_structures::fx::FxHashMap, + opaque: Vec<(String, Why)>, + bytes: Option, + api: Api, +} + +/// Collect the crate's exported API. +pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config) -> Collected { + let bytes = tcx + .crates(()) + .iter() + .find(|&&krate| tcx.crate_name(krate).as_str() == "bytes") + .and_then(|&krate| { + tcx.module_children(krate.as_def_id()) + .iter() + .find(|child| child.ident.as_str() == "Bytes") + .and_then(|child| child.res.opt_def_id()) + }); + let mut c = Collector { + tcx, + config, + items: Vec::new(), + decls: Default::default(), + refusals: Vec::new(), + hidden: Vec::new(), + excluded: config.exclude.iter().map(|path| (path.clone(), 0)).collect(), + aliases: Vec::new(), + left_out: Default::default(), + opaque: Vec::new(), + bytes, + api: Api { + krate: config.crate_name(), + records: Vec::new(), + enums: Vec::new(), + objects: Vec::new(), + callbacks: Vec::new(), + functions: Vec::new(), + constants: Vec::new(), + }, + }; + c.walk(); + c.declare(); + c.define(); + Collected { + api: c.api, + refusals: c.refusals, + opaque: c.opaque, + hidden: c.hidden, + excluded: c.excluded, + aliases: c.aliases, + } +} + +impl<'a, 'tcx> Collector<'a, 'tcx> { + /// Whether the config excludes `path`, counting the exclusion. + fn exclude(&mut self, path: &[String]) -> bool { + let joined = path.join("::"); + for (excluded, count) in &mut self.excluded { + if joined == *excluded || joined.starts_with(&format!("{excluded}::")) { + *count += 1; + return true; + } + } + false + } + + fn refuse(&mut self, path: &[String], kind: &'static str, span: Span, why: Vec) { + self.refusals.push(Refusal { + path: path.join("::"), + kind, + span, + why, + }); + } + + /// Every `pub` item reachable from the crate root, breadth first so each keeps its + /// shortest path. + fn walk(&mut self) { + let tcx = self.tcx; + let mut queue = VecDeque::from([(CRATE_DEF_ID, Vec::new())]); + let mut seen = rustc_data_structures::fx::FxHashSet::default(); + while let Some((module, path)) = queue.pop_front() { + for child in tcx.module_children_local(module) { + if !child.vis.is_public() || child.ident.name == rustc_span::kw::Underscore { + continue; + } + let Res::Def(kind, def_id) = child.res else { + continue; + }; + // Variants and constructors come along with their type. + if matches!(kind, DefKind::Ctor(..) | DefKind::Variant) { + continue; + } + let mut path = path.clone(); + path.push(child.ident.to_string()); + if !seen.insert(def_id) { + continue; + } + if self.exclude(&path) { + self.left_out.insert(def_id, "excluded type"); + continue; + } + if tcx.is_doc_hidden(def_id) { + self.hidden.push(path.join("::")); + self.left_out.insert(def_id, "doc(hidden) type"); + continue; + } + let span = child + .reexport_chain + .first() + .and_then(|reexport| reexport.id()) + .map_or_else(|| tcx.def_span(def_id), |id| tcx.def_span(id)); + let Some(local) = def_id.as_local() else { + let krate = tcx.crate_name(def_id.krate); + self.refuse( + &path, + "use", + span, + vec![why("re-export of another crate's item", krate.to_string())], + ); + continue; + }; + match kind { + DefKind::Mod => queue.push_back((local, path)), + DefKind::TyAlias => self.aliases.push(path.join("::")), + DefKind::Macro(_) => self.refuse(&path, "macro", span, vec![why("macro", "")]), + DefKind::Static { .. } => self.refuse(&path, "static", span, vec![why("static", "")]), + DefKind::Struct + | DefKind::Enum + | DefKind::Union + | DefKind::Trait + | DefKind::Fn + | DefKind::Const { .. } => self.items.push((def_id, path)), + _ => self.refuse(&path, "item", span, vec![why("item kind", format!("{kind:?}"))]), + } + } + } + } + + /// Decide how each type and trait is exported, before any signature names one: a + /// struct whose fields are all `pub`, or an enum, is a value if its fields map, and + /// any other type is an object. + fn declare(&mut self) { + let tcx = self.tcx; + for (def_id, _) in self.items.clone() { + let generic = || { + tcx.generics_of(def_id) + .own_params + .iter() + .any(|p| p.name != rustc_span::kw::SelfUpper) + }; + let decl = match tcx.def_kind(def_id) { + DefKind::Union => Decl::Refused(why("union", "")), + DefKind::Struct | DefKind::Enum | DefKind::Trait if generic() => Decl::Refused(why("generic type", "")), + DefKind::Struct => { + let variant = tcx.adt_def(def_id).non_enum_variant(); + let record = !variant.fields.is_empty() + && variant.fields.iter().all(|f| f.vis.is_public()) + && !variant.is_field_list_non_exhaustive(); + match record { + true => Decl::Record(0), + false => self.object(def_id), + } + } + DefKind::Enum => Decl::Enum(0), + DefKind::Trait => Decl::Callback(0), + _ => continue, + }; + self.decls.insert(def_id, decl); + } + self.settle(); + // Number each kind in item order, with placeholders filled in by `define`. + for (def_id, path) in self.items.clone() { + let span = tcx.def_span(def_id); + let Some(decl) = self.decls.get_mut(&def_id) else { + continue; + }; + let api = &mut self.api; + match decl { + Decl::Record(i) => { + *i = api.records.len(); + api.records.push(Record { + path, + span, + fields: Vec::new(), + tuple: false, + methods: Vec::new(), + traits: Traits::default(), + }); + } + Decl::Enum(i) => { + *i = api.enums.len(); + api.enums.push(Enum { + path, + span, + variants: Vec::new(), + exhaustive: true, + methods: Vec::new(), + traits: Traits::default(), + }); + } + Decl::Object(i) => { + *i = api.objects.len(); + let sync = implements(tcx, def_id, sym::Sync); + api.objects.push(Object { + path, + span, + sync, + methods: Vec::new(), + traits: Traits::default(), + }); + } + Decl::Callback(i) => { + *i = api.callbacks.len(); + api.callbacks.push(Callback { + path, + span, + methods: Vec::new(), + }); + } + Decl::Refused(_) => {} + } + } + } + + /// An object, if the type can move across threads. Shared borrows of one that is not + /// `Sync` are exclusive. + fn object(&self, def_id: DefId) -> Decl { + match implements(self.tcx, def_id, sym::Send) { + true => Decl::Object(0), + false => Decl::Refused(why("object not Send", "")), + } + } + + /// Make each record or enum whose fields do not map an object, until none changes. + fn settle(&mut self) { + loop { + let mut changed = false; + for (def_id, path) in self.items.clone() { + if !matches!(self.decls.get(&def_id), Some(Decl::Record(_) | Decl::Enum(_))) { + continue; + } + if let Err(why) = self.fields(def_id) { + let first = why.into_iter().next().expect("a refusal has a reason"); + self.opaque.push((path.join("::"), first)); + let decl = self.object(def_id); + self.decls.insert(def_id, decl); + changed = true; + } + } + if !changed { + break; + } + } + } + + /// A struct's or enum's variants, with their fields mapped. + fn fields(&self, def_id: DefId) -> Result, Vec> { + let tcx = self.tcx; + let adt = tcx.adt_def(def_id); + let identity = ty::GenericArgs::identity_for_item(tcx, def_id); + let mut errs = Vec::new(); + let mut variants = Vec::new(); + let discriminants: Vec = match adt.is_enum() { + true => adt.discriminants(tcx).map(|(_, d)| signed(tcx, d.ty, d.val)).collect(), + false => vec![0], + }; + for (variant, discriminant) in adt.variants().iter().zip(discriminants) { + if adt.is_enum() && variant.is_field_list_non_exhaustive() { + errs.push(why("non-exhaustive variant", variant.name.to_string())); + } + let mut fields = Vec::new(); + for field in &variant.fields { + let ty = field.ty(tcx, identity).skip_norm_wip(); + match self.ty(ty, Pos::Field) { + Ok(ty) => fields.push(Field { + name: field.name.to_string(), + ty, + }), + Err(why) => errs.push(why), + } + } + let tuple = variant.ctor_kind() == Some(rustc_hir::def::CtorKind::Fn); + variants.push(Variant { + name: variant.name.to_string(), + discriminant, + fields, + tuple, + }); + } + match errs.is_empty() { + true => Ok(variants), + false => Err(errs), + } + } + + /// Fill in every declaration, then the functions and constants. + fn define(&mut self) { + let tcx = self.tcx; + for (def_id, path) in self.items.clone() { + let span = tcx.def_span(def_id); + let kind = tcx.def_kind(def_id); + match self.decls.get(&def_id).cloned() { + Some(Decl::Refused(why)) => { + let kind = match kind { + DefKind::Trait => "trait", + DefKind::Enum => "enum", + DefKind::Union => "union", + _ => "struct", + }; + self.refuse(&path, kind, span, vec![why]); + } + Some(Decl::Record(index)) => { + let variants = self.fields(def_id).expect("settled"); + let variant = variants.into_iter().next().expect("a struct has a variant"); + let (methods, traits) = self.methods(def_id, &path); + let record = &mut self.api.records[index]; + record.fields = variant.fields; + record.tuple = variant.tuple; + record.methods = methods; + record.traits = traits; + } + Some(Decl::Enum(index)) => { + let variants = self.fields(def_id).expect("settled"); + let exhaustive = !tcx.adt_def(def_id).is_variant_list_non_exhaustive(); + let (methods, traits) = self.methods(def_id, &path); + let e = &mut self.api.enums[index]; + e.variants = variants; + e.exhaustive = exhaustive; + e.methods = methods; + e.traits = traits; + } + Some(Decl::Object(index)) => { + let (methods, traits) = self.methods(def_id, &path); + let object = &mut self.api.objects[index]; + object.methods = methods; + object.traits = traits; + } + Some(Decl::Callback(index)) => match self.callback(def_id, &path) { + Ok(methods) => self.api.callbacks[index].methods = methods, + Err(why) => { + // A trait refused after signatures could name it: those that do + // still compile, and the census counts this one. + self.refuse(&path, "trait", span, why); + } + }, + None => match kind { + DefKind::Fn => match self.function(def_id, path.clone(), None) { + Ok(function) => self.api.functions.push(function), + Err(why) => self.refuse(&path, "fn", span, why), + }, + DefKind::Const { .. } => match self.constant(def_id) { + Ok(value) => self.api.constants.push(Constant { path, span, value }), + Err(why) => self.refuse(&path, "const", span, vec![why]), + }, + _ => {} + }, + } + } + } + + /// A type's inherent `pub` methods, and the std traits it implements. + fn methods(&mut self, def_id: DefId, path: &[String]) -> (Vec, Traits) { + let tcx = self.tcx; + let mut methods = Vec::new(); + let self_ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); + for &imp in tcx.inherent_impls(def_id) { + for item in tcx.associated_items(imp).in_definition_order() { + let ty::AssocKind::Fn { name, .. } = item.kind else { + continue; + }; + if !tcx.visibility(item.def_id).is_public() { + continue; + } + let mut method = path.to_vec(); + method.push(name.to_string()); + if self.exclude(&method) { + continue; + } + if tcx.is_doc_hidden(item.def_id) { + self.hidden.push(method.join("::")); + continue; + } + match self.function(item.def_id, method.clone(), Some(self_ty)) { + Ok(function) => methods.push(function), + Err(why) => self.refuse(&method, "method", tcx.def_span(item.def_id), why), + } + } + } + let env = TypingEnv::post_analysis(tcx, def_id); + let implements = |item| { + tcx.get_diagnostic_item(item).is_some_and(|tr| { + let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(env); + infcx.type_implements_trait(tr, [self_ty], env).must_apply_modulo_regions() + }) + }; + let traits = Traits { + clone: implements(sym::Clone), + eq: tcx.lang_items().eq_trait().is_some_and(|tr| { + let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(env); + infcx.type_implements_trait(tr, [self_ty, self_ty], env).must_apply_modulo_regions() + }), + display: implements(sym::Display), + debug: implements(sym::Debug), + default: implements(sym::Default), + }; + (methods, traits) + } + + /// A trait's required methods, as a callback interface. + fn callback(&mut self, def_id: DefId, path: &[String]) -> Result, Vec> { + let tcx = self.tcx; + let mut errs = Vec::new(); + for clause in tcx.explicit_super_clauses_of(def_id).iter_identity_copied() { + let (clause, _) = clause.skip_norm_wip(); + if let Some(trait_pred) = clause.as_trait_clause() { + let tr = trait_pred.def_id(); + let auto = [sym::Send, sym::Sync].iter().any(|&item| tcx.is_diagnostic_item(item, tr)) + || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); + if !auto { + errs.push(why("supertrait", tcx.def_path_str(tr))); + } + } + } + let mut methods = Vec::new(); + let self_ty = Ty::new_param(tcx, 0, rustc_span::kw::SelfUpper); + for item in tcx.associated_items(def_id).in_definition_order() { + match item.kind { + ty::AssocKind::Fn { name, .. } => { + // A provided method keeps its body: only required ones are foreign. + if item.defaultness(tcx).has_value() { + continue; + } + let mut method = path.to_vec(); + method.push(name.to_string()); + match self.function(item.def_id, method, Some(self_ty)) { + Ok(function) if function.future => errs.push(why("async trait method", name.to_string())), + Ok(function) if function.receiver == Some(Receiver::Owned) || function.receiver.is_none() => { + errs.push(why("trait method without &self", name.to_string())) + } + Ok(function) => methods.push(function), + Err(why) => errs.extend(why), + } + } + // An `impl Trait` return's own type: the method refuses it. + ty::AssocKind::Type { data: ty::AssocTypeData::Rpitit(_) } => {} + ty::AssocKind::Type { .. } => errs.push(why("associated type", item.name().to_string())), + ty::AssocKind::Const { .. } => errs.push(why("associated const", item.name().to_string())), + } + } + match errs.is_empty() { + true => Ok(methods), + false => Err(errs), + } + } + + /// A function or method's signature, with its type parameters chosen. + fn function(&self, def_id: DefId, path: Path, self_ty: Option>) -> Result> { + let tcx = self.tcx; + let mut errs = Vec::new(); + let args = match self.instantiate(def_id, self_ty) { + Ok(args) => args, + Err(why) => return Err(why), + }; + let env = TypingEnv::post_analysis(tcx, def_id); + let sig = tcx.fn_sig(def_id).instantiate(tcx, args).skip_norm_wip(); + let sig = tcx.instantiate_bound_regions_with_erased(sig); + let normalize = |ty: Ty<'tcx>| { + tcx.try_normalize_erasing_regions(env, ty::Unnormalized::new_wip(ty)) + .unwrap_or(ty) + }; + let names = tcx.fn_arg_idents(def_id); + let has_self = matches!(tcx.def_kind(def_id), DefKind::AssocFn) + && matches!(tcx.associated_item(def_id).kind, ty::AssocKind::Fn { has_self: true, .. }); + let mut inputs = sig.inputs().iter().copied().map(normalize).enumerate(); + let receiver = match has_self { + false => None, + true => { + let (_, ty) = inputs.next().expect("a method has self"); + let self_ty = self_ty.map(normalize); + match ty.kind() { + _ if Some(ty) == self_ty => Some(Receiver::Owned), + ty::Ref(_, inner, m) if Some(*inner) == self_ty => Some(match m { + ty::Mutability::Not => Receiver::Ref, + ty::Mutability::Mut => Receiver::Mut, + }), + _ => { + errs.push(why("receiver", ty.to_string())); + None + } + } + } + }; + let mut params = Vec::new(); + for (i, ty) in inputs { + let name = names + .get(i) + .copied() + .flatten() + .map_or_else(|| format!("arg{i}"), |ident| ident.to_string()); + match self.ty(ty, Pos::Param) { + Ok(ty) => params.push(Param { name, ty }), + Err(why) => errs.push(why), + } + } + let mut output = normalize(sig.output()); + let mut future = false; + if let Some(inner) = self.future_output(output, env) { + if !self.is_send(output, env) { + errs.push(why("future not Send", "")); + } + output = normalize(inner); + future = true; + } + let (ok, err) = match output.kind() { + ty::Adt(adt, args) if tcx.is_diagnostic_item(sym::Result, adt.did()) => { + (self.ty(args.type_at(0), Pos::Return), Some(self.ty(args.type_at(1), Pos::Return))) + } + _ => (self.ty(output, Pos::Return), None), + }; + let ok = ok.map_err(|why| errs.push(why)).ok(); + let err = match err { + Some(Ok(err)) => Some(err), + Some(Err(why)) => { + errs.push(why); + None + } + None => None, + }; + match (errs.is_empty(), ok) { + (true, Some(ok)) => Ok(Function { + path, + span: tcx.def_span(def_id), + receiver, + params, + ok, + err, + future, + }), + _ => Err(errs), + } + } + + /// The generic arguments a function is exported with: its parent's own (a trait's + /// `Self`), its lifetimes erased, and each type parameter by the rules in + /// [`Self::choose`]. + fn instantiate(&self, def_id: DefId, self_ty: Option>) -> Result, Vec> { + let tcx = self.tcx; + let generics = tcx.generics_of(def_id); + let identity = ty::GenericArgs::identity_for_item(tcx, def_id); + if !generics.requires_monomorphization(tcx) { + return Ok(identity); + } + let mut errs = Vec::new(); + let mut args: Vec> = identity.to_vec(); + let parent = generics.parent_count; + // A trait method's `Self` stays a parameter: the trait is the callback. + let _ = self_ty; + for (i, arg) in identity.iter().enumerate().skip(parent) { + match arg.kind() { + GenericArgKind::Lifetime(_) => args[i] = tcx.lifetimes.re_erased.into(), + GenericArgKind::Const(_) => errs.push(why("const generic", "")), + GenericArgKind::Type(param) => match self.choose(def_id, param) { + Ok(ty) => args[i] = ty.into(), + Err(why) => errs.push(why), + }, + } + } + match errs.is_empty() { + true => Ok(tcx.mk_args(&args)), + false => Err(errs), + } + } + + /// The type a type parameter is exported as: `X` for `impl Into` or + /// `impl AsRef`, else the first of `String`, `Bytes`, and `Vec` meeting its + /// bounds. + fn choose(&self, def_id: DefId, param: Ty<'tcx>) -> Result, Why> { + let tcx = self.tcx; + let clauses = tcx.clauses_of(def_id); + let identity = clauses.instantiate_identity(tcx); + let bounds: Vec<_> = identity + .clauses + .iter() + .map(|clause| clause.skip_norm_wip()) + .filter_map(|clause| clause.as_trait_clause()) + .filter(|pred| pred.self_ty().skip_binder() == param) + .collect(); + let mut candidates = Vec::new(); + for bound in &bounds { + let tr = bound.def_id(); + if tcx.is_diagnostic_item(sym::Into, tr) || tcx.is_diagnostic_item(sym::AsRef, tr) { + let target = bound.skip_binder().trait_ref.args.type_at(1); + candidates.push(match target.kind() { + ty::Str => Ty::new_imm_ref(tcx, tcx.lifetimes.re_static, target), + ty::Slice(_) => Ty::new_imm_ref(tcx, tcx.lifetimes.re_static, target), + _ => target, + }); + } + } + if let Some(string) = tcx.lang_items().string() { + candidates.push(Ty::new_adt(tcx, tcx.adt_def(string), ty::List::empty())); + } + if let Some(bytes) = self.bytes { + candidates.push(Ty::new_adt(tcx, tcx.adt_def(bytes), ty::List::empty())); + } + if let Some(vec) = tcx.get_diagnostic_item(sym::Vec) { + let alloc = tcx.lang_items().global_alloc_ty(); + if let Some(alloc) = alloc { + let args = tcx.mk_args(&[ + tcx.types.u8.into(), + Ty::new_adt(tcx, tcx.adt_def(alloc), ty::List::empty()).into(), + ]); + candidates.push(Ty::new_adt(tcx, tcx.adt_def(vec), args)); + } + } + let env = TypingEnv::post_analysis(tcx, def_id); + for candidate in candidates { + let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); + let mut args: Vec> = ty::GenericArgs::identity_for_item(tcx, def_id).to_vec(); + let ty::Param(p) = param.kind() else { + unreachable!("a generic type argument is a parameter"); + }; + args[p.index as usize] = candidate.into(); + let instantiated = clauses.instantiate(tcx, tcx.mk_args(&args)); + let holds = instantiated.clauses.iter().all(|clause| { + let clause = clause.skip_norm_wip(); + let obligation = Obligation::new(tcx, ObligationCause::dummy(), param_env, clause); + infcx.predicate_must_hold_modulo_regions(&obligation) + }); + if holds { + return Ok(candidate); + } + } + // A bound on one of the crate's traits takes a foreign implementation. + let local: Vec<_> = bounds + .iter() + .map(|b| b.def_id()) + .filter(|tr| matches!(self.decls.get(tr), Some(Decl::Callback(_)))) + .collect(); + let sized = [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()]; + let names: Vec = bounds + .iter() + .filter(|b| !sized.contains(&Some(b.def_id()))) + .map(|b| tcx.def_path_str(b.def_id())) + .collect(); + match local.as_slice() { + [_] => Err(why("callback bound", names.join(" + "))), + _ => Err(why("generic parameter", names.join(" + "))), + } + } + + /// What `ty` resolves to when awaited, if it is a future. + fn future_output(&self, ty: Ty<'tcx>, env: TypingEnv<'tcx>) -> Option> { + let tcx = self.tcx; + let future = tcx.lang_items().future_trait()?; + let output = tcx.lang_items().future_output()?; + let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); + if !infcx.type_implements_trait(future, [ty], param_env).must_apply_modulo_regions() { + return None; + } + let projection = Ty::new_projection(tcx, ty::IsRigid::No, output, [ty]); + tcx.try_normalize_erasing_regions(env, ty::Unnormalized::new_wip(projection)) + .ok() + } + + fn is_send(&self, ty: Ty<'tcx>, env: TypingEnv<'tcx>) -> bool { + let tcx = self.tcx; + let Some(send) = tcx.get_diagnostic_item(sym::Send) else { + return true; + }; + let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); + infcx.type_implements_trait(send, [ty], param_env).must_apply_modulo_regions() + } + + /// A constant's value, if it is a `bool` or integer. + fn constant(&self, def_id: DefId) -> Result { + let tcx = self.tcx; + let ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); + let int = match ty.kind() { + ty::Bool => None, + ty::Int(_) | ty::Uint(_) => match int(ty) { + Some(int) => Some(int), + None => return Err(why("constant type", ty.to_string())), + }, + _ => return Err(why("constant type", ty.to_string())), + }; + let Ok(value) = tcx.const_eval_poly(def_id) else { + return Err(why("constant value", "")); + }; + let Some(scalar) = value.try_to_scalar_int() else { + return Err(why("constant value", "")); + }; + let bits = scalar.to_bits(scalar.size()); + Ok(match int { + None => Literal::Bool(bits != 0), + Some(int) => Literal::Int(int, signed(tcx, ty, bits)), + }) + } + + /// The exported form of `ty` where it appears. + fn ty(&self, ty: Ty<'tcx>, pos: Pos) -> Result { + let tcx = self.tcx; + Ok(match ty.kind() { + ty::Tuple(list) if list.is_empty() => match pos { + Pos::Return => Type::Unit, + _ => return Err(why("unit outside a return", "")), + }, + ty::Bool => Type::Bool, + ty::Char => Type::Char, + ty::Float(ty::FloatTy::F32) => Type::F32, + ty::Float(ty::FloatTy::F64) => Type::F64, + ty::Int(_) | ty::Uint(_) => Type::Int(int(ty).ok_or_else(|| why("128-bit integer", ty.to_string()))?), + ty::Ref(_, inner, m) => { + let inner_ty = match inner.kind() { + ty::Str => Type::Str, + ty::Slice(elem) if *elem == tcx.types.u8 => Type::Slice, + ty::Slice(elem) => return Err(why("slice", elem.to_string())), + ty::Dynamic(..) => return Err(why("trait object", inner.to_string())), + _ => self.ty(*inner, Pos::Behind)?, + }; + let mutability = match m { + ty::Mutability::Not => Mutability::Not, + ty::Mutability::Mut => Mutability::Mut, + }; + match (&inner_ty, pos, mutability) { + // Returned as a copy: plain data reads the same either way. + (Type::Object(_), Pos::Return, _) => return Err(why("borrowed object return", inner.to_string())), + (_, Pos::Field, _) => return Err(why("reference field", inner.to_string())), + (Type::Object(_), Pos::Param, _) => {} + (_, Pos::Param, Mutability::Mut) => return Err(why("&mut of a value", inner.to_string())), + _ => {} + } + Type::Ref(mutability, Box::new(inner_ty)) + } + ty::Adt(adt, args) => { + let did = adt.did(); + if tcx.lang_items().string() == Some(did) { + Type::String + } else if tcx.is_diagnostic_item(sym::Vec, did) { + match args.type_at(0) == tcx.types.u8 { + true => Type::Vec, + false => return Err(why("Vec", args.type_at(0).to_string())), + } + } else if Some(did) == self.bytes { + Type::Bytes + } else if tcx.is_diagnostic_item(rustc_span::Symbol::intern("Duration"), did) { + Type::Duration + } else if tcx.is_diagnostic_item(sym::Option, did) { + let inner = self.ty(args.type_at(0), Pos::Behind)?; + if matches!(inner, Type::Option(_)) { + return Err(why("nested Option", ty.to_string())); + } + Type::Option(Box::new(inner)) + } else if tcx.is_diagnostic_item(sym::Result, did) { + return Err(why("Result outside a return", "")); + } else if adt.is_box() { + let inner = args.type_at(0); + match inner.kind() { + ty::Dynamic(preds, ..) => { + return self.dynamic(preds.principal_def_id(), Dyn::Box, inner); + } + _ => Type::Box(Box::new(self.ty(inner, Pos::Behind)?)), + } + } else if tcx.is_diagnostic_item(sym::Arc, did) { + let inner = args.type_at(0); + match inner.kind() { + ty::Dynamic(preds, ..) => { + return self.dynamic(preds.principal_def_id(), Dyn::Arc, inner); + } + _ => return Err(why("Arc", strip_args(tcx, did))), + } + } else if !did.is_local() { + return Err(why("foreign type", strip_args(tcx, did))); + } else { + match self.decls.get(&did) { + Some(Decl::Record(i)) => Type::Record(*i), + Some(Decl::Enum(i)) => Type::Enum(*i), + Some(Decl::Object(i)) => Type::Object(*i), + Some(Decl::Refused(_)) => return Err(why("refused type", tcx.def_path_str(did))), + Some(Decl::Callback(_)) | None => { + let construct = self.left_out.get(&did).copied().unwrap_or("type not reachable from the crate root"); + return Err(why(construct, tcx.def_path_str(did))); + } + } + } + } + ty::Tuple(_) => return Err(why("tuple", "")), + ty::Array(..) => return Err(why("array", ty.to_string())), + ty::Slice(_) | ty::Str => return Err(why("unsized type", ty.to_string())), + ty::Dynamic(..) => return Err(why("trait object", ty.to_string())), + ty::Param(_) => match pos { + // A callback method's `Self`. + _ => return Err(why("type parameter", ty.to_string())), + }, + ty::Closure(..) | ty::FnDef(..) | ty::FnPtr(..) => return Err(why("function value", "")), + ty::RawPtr(..) => return Err(why("raw pointer", "")), + ty::Never => return Err(why("never type", "")), + ty::Alias(..) => return Err(why("opaque type", ty.to_string())), + _ => return Err(why("type", ty.to_string())), + }) + } + + /// A trait object of one of the crate's traits, as a foreign implementation. + fn dynamic(&self, principal: Option, form: Dyn, ty: Ty<'tcx>) -> Result { + match principal.and_then(|tr| self.decls.get(&tr)) { + Some(Decl::Callback(i)) => Ok(Type::Callback(*i, form)), + _ => Err(why("trait object", ty.to_string())), + } + } +} + +/// Where a type appears, which decides the forms it may take. +#[derive(Clone, Copy, PartialEq, Eq)] +enum Pos { + Param, + Return, + Field, + /// Inside another type: an `Option`, a `Box`, or behind a reference. + Behind, +} + +fn int(ty: Ty<'_>) -> Option { + Some(match ty.kind() { + ty::Uint(ty::UintTy::U8) => Int::U8, + ty::Uint(ty::UintTy::U16) => Int::U16, + ty::Uint(ty::UintTy::U32) => Int::U32, + ty::Uint(ty::UintTy::U64) => Int::U64, + ty::Uint(ty::UintTy::Usize) => Int::Usize, + ty::Int(ty::IntTy::I8) => Int::I8, + ty::Int(ty::IntTy::I16) => Int::I16, + ty::Int(ty::IntTy::I32) => Int::I32, + ty::Int(ty::IntTy::I64) => Int::I64, + ty::Int(ty::IntTy::Isize) => Int::Isize, + _ => return None, + }) +} + +/// An integer of type `ty` from its bits: sign-extended if `ty` is signed. +fn signed<'tcx>(tcx: TyCtxt<'tcx>, ty: Ty<'tcx>, bits: u128) -> i128 { + let width = match int(ty) { + Some(Int::U8 | Int::I8) => 8, + Some(Int::U16 | Int::I16) => 16, + Some(Int::U32 | Int::I32) => 32, + Some(Int::U64 | Int::I64) => 64, + _ => tcx.data_layout.pointer_size().bits() as u32, + }; + match ty.is_signed() { + true => { + let shift = 128 - width; + ((bits << shift) as i128) >> shift + } + false => bits as i128, + } +} + +/// Whether the local type `def_id` implements the std trait `item`. +fn implements(tcx: TyCtxt<'_>, def_id: DefId, item: rustc_span::Symbol) -> bool { + let ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); + let Some(tr) = tcx.get_diagnostic_item(item) else { + return false; + }; + let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(TypingEnv::post_analysis(tcx, def_id)); + infcx.type_implements_trait(tr, [ty], env).must_apply_modulo_regions() +} + +/// A type's path without generic arguments. +fn strip_args(tcx: TyCtxt<'_>, did: DefId) -> String { + tcx.def_path_str(did) +} diff --git a/ffi/src/config.rs b/ffi/src/config.rs new file mode 100644 index 000000000..890857311 --- /dev/null +++ b/ffi/src/config.rs @@ -0,0 +1,46 @@ +//! The `ffi.toml` that says what to export. + +use std::path::Path; + +use serde::Deserialize; + +/// What to export from one crate. +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "kebab-case")] +pub struct Config { + /// The cargo package whose library is exported. + pub package: String, + /// The prefix of every C name, the crate name by default. + pub prefix: Option, + /// Paths from the crate root left out of the export: a module, an item, or one + /// method (`track::Producer::poll_closed`). Each must name something exported. + #[serde(default)] + pub exclude: Vec, +} + +impl Config { + pub fn load(path: &Path) -> Result { + let text = std::fs::read_to_string(path).map_err(|err| format!("reading {}: {err}", path.display()))?; + toml::from_str(&text).map_err(|err| format!("parsing {}: {err}", path.display())) + } + + /// The library's crate name, as rustc is given it. + pub fn crate_name(&self) -> String { + self.package.replace('-', "_") + } + + /// The prefix of every C name. + pub fn prefix(&self) -> String { + self.prefix.clone().unwrap_or_else(|| self.crate_name()) + } +} + +/// Environment variables the CLI hands the wrapper. +pub mod env { + /// The `ffi.toml` path, absolute. + pub const CONFIG: &str = "RUST2_FFI_CONFIG"; + /// The output directory, absolute. + pub const OUT: &str = "RUST2_FFI_OUT"; + /// Where to write a census instead of exporting, absolute. + pub const CENSUS: &str = "RUST2_FFI_CENSUS"; +} diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs new file mode 100644 index 000000000..cd9f841a8 --- /dev/null +++ b/ffi/src/driver.rs @@ -0,0 +1,177 @@ +//! The binary as rustc: plain for every crate but the configured one, whose API it also +//! collects once rustc has checked it. + +use std::path::{Path, PathBuf}; +use std::process::ExitCode; + +use rustc_driver::{Callbacks, Compilation}; +use rustc_interface::interface::Compiler; +use rustc_middle::ty::TyCtxt; +use rustc_span::Span; + +use crate::config::{self, Config}; +use crate::abi::Abi; +use crate::{c, census, collect, glue}; + +/// Run as rustc, with `args` as cargo passed them: the wrapped rustc's path first. +pub fn run(args: Vec) -> ExitCode { + rust2_driver::rustc::run("rust2-ffi", args, |args| { + Ok(Export::for_args(args)?.map(|job| Box::new(job) as rust2_driver::rustc::Job)) + }) +} + +/// Compiles the configured crate, exporting its API after analysis. +struct Export { + config: Config, + output: Output, + /// The features rustc compiles the crate with, which the export's crate enables. + features: Vec, +} + +/// What the job writes. +enum Output { + /// The export, into this directory. + Dir(PathBuf), + /// A census of the crate, to this file, instead of an export. + Census(PathBuf), +} + +impl Export { + /// The job for this rustc invocation, if it compiles the configured library. + fn for_args(args: &[String]) -> Result, String> { + let Some(path) = std::env::var_os(config::env::CONFIG) else { + return Ok(None); + }; + let config = Config::load(path.as_ref())?; + if !rust2_driver::rustc::compiles_lib(args, &config.crate_name()) { + return Ok(None); + } + let output = match ( + std::env::var_os(config::env::OUT), + std::env::var_os(config::env::CENSUS), + ) { + (Some(out), None) => Output::Dir(out.into()), + (None, Some(census)) => Output::Census(census.into()), + _ => { + return Err(format!( + "exactly one of {} and {} must be set", + config::env::OUT, + config::env::CENSUS + )); + } + }; + let features = args + .windows(2) + .filter(|w| w[0] == "--cfg") + .filter_map(|w| w[1].strip_prefix("feature=\"")) + .filter_map(|f| f.strip_suffix('"')) + .map(str::to_string) + .collect(); + Ok(Some(Self { + config, + output, + features, + })) + } +} + +impl Callbacks for Export { + fn after_analysis<'tcx>(&mut self, _compiler: &Compiler, tcx: TyCtxt<'tcx>) -> Compilation { + if tcx.dcx().has_errors().is_some() { + return Compilation::Stop; + } + let collected = collect::collect(tcx, &self.config); + let written = match &self.output { + Output::Census(path) => { + let text = census::render(&self.config.package, &collected, &|span| at(tcx, span)); + write(path, &text) + } + Output::Dir(out) => { + for refusal in &collected.refusals { + let reasons: Vec = refusal + .why + .iter() + .map(|why| match why.detail.is_empty() { + true => why.construct.to_string(), + false => format!("{} `{}`", why.construct, why.detail), + }) + .collect(); + tcx.dcx().span_err( + refusal.span, + format!( + "rust2-ffi: cannot export {} `{}`: {}; exclude it in the config to leave it out", + refusal.kind, + refusal.path, + reasons.join("; ") + ), + ); + } + for (path, count) in &collected.excluded { + if *count == 0 { + tcx.dcx().err(format!("rust2-ffi: exclude `{path}` names nothing exported")); + } + } + if tcx.dcx().has_errors().is_some() { + return Compilation::Stop; + } + let abi = Abi::new(&collected.api, &self.config.prefix()); + for (name, (first, first_span), (second, second_span)) in &abi.clashes { + tcx.dcx() + .struct_span_err( + *second_span, + format!("rust2-ffi: {second} and {first} are both `{name}` in C"), + ) + .with_span_note(*first_span, format!("{first} is here")) + .with_help("exclude one in the config") + .emit(); + } + if tcx.dcx().has_errors().is_some() { + return Compilation::Stop; + } + let header = c::header(&abi, &self.config.package); + let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default(); + let glue = glue::Crate { + abi: &abi, + header: &header, + package: &self.config.package, + manifest_dir: Path::new(&manifest_dir), + features: &self.features, + }; + glue.write(out) + } + }; + if let Err(err) = written { + tcx.dcx().err(format!("rust2-ffi: {err}")); + } + match tcx.dcx().has_errors() { + None => Compilation::Continue, + Some(_) => Compilation::Stop, + } + } +} + +/// Where `span` starts, relative to the crate's directory when inside it. +fn at(tcx: TyCtxt<'_>, span: Span) -> String { + let sm = tcx.sess.source_map(); + let (file, line, col, ..) = sm.span_to_location_info(span.source_callsite()); + let Some(file) = file else { + return "no location".to_string(); + }; + let name = file + .name + .display(rustc_span::RemapPathScopeComponents::DIAGNOSTICS) + .to_string(); + let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap_or_default(); + let name = match name.strip_prefix(&format!("{dir}/")) { + Some(rel) => rel.to_string(), + None => name, + }; + format!("{name}:{line}:{col}") +} + +pub fn write(path: &Path, text: &str) -> Result<(), String> { + if let Some(dir) = path.parent() { + std::fs::create_dir_all(dir).map_err(|err| format!("creating {}: {err}", dir.display()))?; + } + std::fs::write(path, text).map_err(|err| format!("writing {}: {err}", path.display())) +} diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs new file mode 100644 index 000000000..66a951a21 --- /dev/null +++ b/ffi/src/glue.rs @@ -0,0 +1,745 @@ +//! The Rust side of the C ABI: a crate of `extern "C"` functions over the exported +//! crate, with the runtime beside it and the header in `include/`. +//! +//! Each function lifts its C arguments to Rust values, calls the Rust item by its path, +//! and lowers the result. A value is copied in from the caller's memory, which Rust +//! never frees, and lowered into memory the caller frees. A handle is borrowed as the +//! receiver or parameter is, or moved out of when taken by value. + +use std::fmt::Write; +use std::path::Path; + +use crate::abi::{self, Abi, Ty}; +use crate::ir::{Function, Mutability, Receiver, Traits, Type}; + +const RUNTIME: &str = include_str!("../runtime/rt.rs"); + +/// The crate that builds the C ABI. +pub struct Crate<'a> { + pub abi: &'a Abi<'a>, + pub header: &'a str, + pub package: &'a str, + pub manifest_dir: &'a Path, + pub features: &'a [String], +} + +impl Crate<'_> { + /// Write the crate into `out`: `Cargo.toml`, `src/`, and `include/.h`. + pub fn write(&self, out: &Path) -> Result<(), String> { + let mut features: Vec = self.features.iter().map(|f| format!("{f:?}")).collect(); + features.sort(); + let manifest = format!( + "# Generated by rust2-ffi: the C ABI of {package}'s pub API.\n\ + [package]\n\ + name = \"{package}-ffi\"\n\ + version = \"0.0.0\"\n\ + edition = \"2024\"\n\ + publish = false\n\ + \n\ + [lib]\n\ + name = \"{lib}\"\n\ + crate-type = [\"staticlib\", \"cdylib\"]\n\ + \n\ + [dependencies]\n\ + {package} = {{ path = {path:?}, default-features = false, features = [{features}] }}\n\ + bytes = \"1\"\n\ + \n\ + [workspace]\n", + package = self.package, + lib = self.abi.prefix, + path = self.manifest_dir.display().to_string(), + features = features.join(", "), + ); + let mut generator = Gen { + abi: self.abi, + krate: self.abi.api.krate.clone(), + out: String::new(), + }; + generator.lib(); + 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)), + self.header, + ) + } +} + +struct Gen<'a> { + abi: &'a Abi<'a>, + krate: String, + out: String, +} + +impl Gen<'_> { + fn line(&mut self, line: impl AsRef) { + self.out.push_str(line.as_ref()); + self.out.push('\n'); + } + + fn path(&self, path: &[String]) -> String { + format!("{}::{}", self.krate, path.join("::")) + } + + fn object_path(&self, i: usize) -> String { + self.path(&self.abi.api.objects[i].path) + } + + /// The Rust spelling of a C type. + fn rs(&self, ty: &Ty) -> String { + match ty { + Ty::Void => "()".to_string(), + Ty::Bool => "bool".to_string(), + Ty::Int(int) => int.rust().to_string(), + Ty::F32 => "f32".to_string(), + Ty::F64 => "f64".to_string(), + Ty::Char => "u32".to_string(), + Ty::Buf => "rt::Buf".to_string(), + Ty::Duration => "rt::Duration".to_string(), + Ty::Struct(name) => name.clone(), + // A C enum is an `int`. + Ty::Enum(_) | Ty::Poll => "i32".to_string(), + Ty::Handle { .. } => "*const c_void".to_string(), + Ty::Future(_) => "*mut rt::Future".to_string(), + Ty::Waker => "rt::Waker".to_string(), + Ty::Out(inner) => format!("*mut {}", self.rs(inner)), + Ty::In(inner) => format!("*const {}", self.rs(inner)), + } + } + + /// The Rust value of type `ty` that the C value `e` holds, copied out of it. + fn lift(&self, ty: &Type, e: &str) -> String { + match ty { + Type::Unit => "()".to_string(), + Type::Bool | Type::Int(_) | Type::F32 | Type::F64 => e.to_string(), + Type::Char => format!("rt::char({e}, w)"), + Type::Str | Type::String => format!("unsafe {{ {e}.str(w) }}.to_owned()"), + Type::Slice | Type::Vec => format!("unsafe {{ {e}.bytes(w) }}.to_vec()"), + Type::Bytes => format!("::bytes::Bytes::copy_from_slice(unsafe {{ {e}.bytes(w) }})"), + Type::Duration => format!("{e}.lift(w)"), + Type::Option(inner) => match inner.base() { + Type::Object(_) => format!( + "if {e}.is_null() {{ None }} else {{ Some({}) }}", + self.lift(inner, e) + ), + base if Abi::is_buf(base) => { + format!("if {e}.is_none() {{ None }} else {{ Some({}) }}", self.lift(inner, e)) + } + _ => format!( + "if {e}.some {{ Some({}) }} else {{ None }}", + self.lift(inner, &format!("{e}.value")) + ), + }, + Type::Box(inner) => format!("::std::boxed::Box::new({})", self.lift(inner, e)), + Type::Ref(_, inner) => self.lift(inner, e), + Type::Record(i) => format!("lift_{}(&{e}, w)", self.abi.record(*i)), + Type::Enum(i) => match self.abi.api.enums[*i].plain() { + true => format!("lift_{}({e}, w)", self.abi.enumeration(*i)), + false => format!("lift_{}(&{e}, w)", self.abi.enumeration(*i)), + }, + Type::Object(i) => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), + Type::Callback(i, form) => abi::dyn_wrap(*form, &format!("Foreign_{}({e})", self.abi.callback(*i))), + } + } + + /// The C value of the Rust value `e` of type `ty`, which the caller frees. + fn lower(&self, ty: &Type, e: &str) -> String { + match ty { + Type::Unit => "()".to_string(), + Type::Bool | Type::Int(_) | Type::F32 | Type::F64 => e.to_string(), + Type::Char => format!("{e} as u32"), + Type::Str => format!("rt::Buf::string({e}.to_owned())"), + Type::String => format!("rt::Buf::string({e})"), + Type::Slice => format!("rt::Buf::vec({e}.to_vec())"), + Type::Vec => format!("rt::Buf::vec({e})"), + Type::Bytes => format!("rt::Buf::owned({e})"), + Type::Duration => format!("rt::Duration::lower({e})"), + Type::Option(inner) => { + let none = match inner.base() { + Type::Object(_) => "::std::ptr::null()".to_string(), + base if Abi::is_buf(base) => "rt::Buf::NONE".to_string(), + _ => { + let name = self.abi.option(inner); + return format!( + "match {e} {{ Some(v) => {name} {{ some: true, value: {} }}, None => {name} {{ some: false, value: unsafe {{ ::std::mem::zeroed() }} }} }}", + self.lower(inner, "v") + ); + } + }; + format!("match {e} {{ Some(v) => {}, None => {none} }}", self.lower(inner, "v")) + } + Type::Box(inner) => self.lower(inner, &format!("*{e}")), + Type::Ref(_, inner) => match &**inner { + Type::Str | Type::Slice => self.lower(inner, e), + inner => self.lower(inner, &format!("::std::clone::Clone::clone({e})")), + }, + Type::Record(i) => format!("lower_{}({e})", self.abi.record(*i)), + Type::Enum(i) => format!("lower_{}({e})", self.abi.enumeration(*i)), + Type::Object(_) => format!("rt::Object::new({e})"), + Type::Callback(..) => unreachable!("a callback is never returned"), + } + } + + /// What frees the parts of the C value `e` that Rust allocated, if any. + fn free(&self, ty: &Type, e: &str) -> Option { + match ty { + _ if Abi::is_buf(ty) => Some(format!("unsafe {{ {e}.free() }};")), + Type::Option(inner) => match inner.base() { + base if Abi::is_buf(base) => Some(format!("unsafe {{ {e}.free() }};")), + _ => self + .free(inner, &format!("{e}.value")) + .map(|free| format!("if {e}.some {{ {free} }}")), + }, + Type::Box(inner) => self.free(inner, e), + Type::Record(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.record(*i))), + Type::Enum(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.enumeration(*i))), + _ => None, + } + } + + /// Whether a value of `ty` holds memory Rust allocated. + fn owns(&self, ty: &Type) -> bool { + match ty { + _ if Abi::is_buf(ty) => true, + Type::Option(inner) | Type::Box(inner) => self.owns(inner), + Type::Record(i) => self.abi.api.records[*i].fields.iter().any(|f| self.owns(&f.ty)), + Type::Enum(i) => self.abi.api.enums[*i] + .variants + .iter() + .any(|v| v.fields.iter().any(|f| self.owns(&f.ty))), + _ => false, + } + } + + fn lib(&mut self) { + let api = self.abi.api; + self.line(format!( + "//! Generated by rust2-ffi: the C ABI of `{}`'s pub API. Do not edit.\n", + api.krate + )); + self.line("#![allow(non_camel_case_types, reason = \"the C names\")]"); + self.line("#![allow(unused_unsafe, reason = \"every conversion is in its own block\")]"); + self.line("#![allow(clippy::all, reason = \"generated\")]"); + self.line("#![allow(dead_code, reason = \"the runtime serves every API\")]\n"); + self.line("mod rt;\n"); + self.line("use std::ffi::c_void;\n"); + + let p = self.abi.prefix.clone(); + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {p}_buf_free(buf: rt::Buf) {{\n\tunsafe {{ buf.free() }}\n}}\n" + )); + + for (name, inner) in &self.abi.options.clone() { + let value = self.rs(&self.abi.ty(inner)); + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub struct {name} {{\n\tpub some: bool,\n\tpub value: {value},\n}}\n" + )); + } + for i in 0..api.records.len() { + self.record(i); + } + for i in 0..api.enums.len() { + self.enumeration(i); + } + for i in 0..api.callbacks.len() { + self.callback(i); + } + for i in 0..api.objects.len() { + let object = &api.objects[i]; + let name = self.abi.object(i); + let path = self.object_path(i); + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_free(this: *const c_void) {{\n\tunsafe {{ rt::Object::<{path}>::free(this) }}\n}}\n" + )); + let borrow = match object.sync { + true => "borrow", + false => "borrow_mut", + }; + self.traits(&name, &path, object.traits, |e| { + format!("unsafe {{ rt::Object::<{path}>::{borrow}({e}, w) }}") + }); + let owner = Ty::Handle { + name: name.clone(), + constant: false, + }; + for method in &object.methods { + self.function(method, Some((&owner, Some(i)))); + } + } + for function in &api.functions { + self.function(function, None); + } + } + + /// The functions a type's std traits export; `borrow` reads the receiver `e`. + fn traits(&mut self, name: &str, path: &str, traits: Traits, borrow: impl Fn(&str) -> String) { + let handle = "*const c_void"; + if traits.clone { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_clone(this: {handle}) -> {handle} {{\n\tlet w = \"{name}_clone\";\n\tlet this = {};\n\trt::Object::new(<{path} as ::std::clone::Clone>::clone(&*this))\n}}\n", + borrow("this") + )); + } + if traits.eq { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: {handle}, b: {handle}) -> bool {{\n\tlet w = \"{name}_eq\";\n\tlet a = {};\n\tlet b = {};\n\t<{path} as ::std::cmp::PartialEq>::eq(&*a, &*b)\n}}\n", + borrow("a"), + borrow("b") + )); + } + if traits.display { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_to_string(this: {handle}) -> rt::Buf {{\n\tlet w = \"{name}_to_string\";\n\tlet this = {};\n\trt::Buf::string(::std::string::ToString::to_string(&*this))\n}}\n", + borrow("this") + )); + } + if traits.debug { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_debug(this: {handle}) -> rt::Buf {{\n\tlet w = \"{name}_debug\";\n\tlet this = {};\n\trt::Buf::string(format!(\"{{:?}}\", &*this))\n}}\n", + borrow("this") + )); + } + if traits.default { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_default() -> {handle} {{\n\trt::Object::new(<{path} as ::std::default::Default>::default())\n}}\n" + )); + } + } + + /// The functions every value type has: its std traits, read through a pointer, and + /// `free`. + fn value_traits(&mut self, name: &str, path: &str, ty: &Type, traits: Traits) { + let lift = self.lift(ty, "unsafe { *this }"); + let lift_a = self.lift(ty, "unsafe { *a }"); + let lift_b = self.lift(ty, "unsafe { *b }"); + let c = self.rs(&self.abi.ty(ty)); + if traits.eq { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: *const {c}, b: *const {c}) -> bool {{\n\tlet w = \"{name}_eq\";\n\t<{path} as ::std::cmp::PartialEq>::eq(&{lift_a}, &{lift_b})\n}}\n" + )); + } + if traits.display { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_to_string(this: *const {c}) -> rt::Buf {{\n\tlet w = \"{name}_to_string\";\n\trt::Buf::string(::std::string::ToString::to_string(&{lift}))\n}}\n" + )); + } + if traits.debug { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_debug(this: *const {c}) -> rt::Buf {{\n\tlet w = \"{name}_debug\";\n\trt::Buf::string(format!(\"{{:?}}\", &{lift}))\n}}\n" + )); + } + if traits.default { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_default() -> {c} {{\n\t{}\n}}\n", + self.lower(ty, &format!("<{path} as ::std::default::Default>::default()")) + )); + } + if !matches!(self.abi.ty(ty), Ty::Enum(_)) { + let free = self.free(ty, "unsafe { this.read() }").unwrap_or_default(); + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_free(this: *mut {c}) {{\n\tif this.is_null() {{\n\t\treturn;\n\t}}\n\t{free}\n}}\n" + )); + } + } + + fn record(&mut self, i: usize) { + let record = &self.abi.api.records[i]; + let name = self.abi.record(i); + let path = self.path(&record.path); + let ty = Type::Record(i); + let mut fields = String::new(); + for (n, field) in record.fields.iter().enumerate() { + let _ = writeln!(fields, "\tpub f{n}: {},", self.rs(&self.abi.ty(&field.ty))); + } + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub struct {name} {{\n{fields}}}\n" + )); + let lifted: Vec = record + .fields + .iter() + .enumerate() + .map(|(n, f)| self.lift(&f.ty, &format!("c.f{n}"))) + .collect(); + let build = match record.tuple { + true => format!("{path}({})", lifted.join(", ")), + false => { + let fields: Vec = record + .fields + .iter() + .zip(&lifted) + .map(|(f, l)| format!("{}: {l}", f.name)) + .collect(); + format!("{path} {{ {} }}", fields.join(", ")) + } + }; + self.line(format!( + "fn lift_{name}(c: &{name}, w: &str) -> {path} {{\n\tlet _ = w;\n\t{build}\n}}\n" + )); + let bindings: Vec = (0..record.fields.len()).map(|n| format!("f{n}")).collect(); + let pattern = match record.tuple { + true => format!("{path}({})", bindings.join(", ")), + false => { + let fields: Vec = record + .fields + .iter() + .zip(&bindings) + .map(|(f, b)| format!("{}: {b}", f.name)) + .collect(); + format!("{path} {{ {} }}", fields.join(", ")) + } + }; + let lowered: Vec = record + .fields + .iter() + .enumerate() + .map(|(n, f)| format!("f{n}: {}", self.lower(&f.ty, &format!("f{n}")))) + .collect(); + self.line(format!( + "fn lower_{name}(v: {path}) -> {name} {{\n\tlet {pattern} = v;\n\t{name} {{ {} }}\n}}\n", + lowered.join(", ") + )); + if self.owns(&ty) { + let frees: Vec = record + .fields + .iter() + .enumerate() + .filter_map(|(n, f)| self.free(&f.ty, &format!("c.f{n}"))) + .collect(); + self.line(format!("fn free_{name}(c: {name}) {{\n\t{}\n}}\n", frees.join("\n\t"))); + } + self.value_traits(&name, &path, &ty, record.traits); + let owner = Ty::Struct(name.clone()); + for method in &record.methods { + self.function(method, Some((&owner, None))); + } + } + + fn enumeration(&mut self, i: usize) { + let e = &self.abi.api.enums[i]; + let name = self.abi.enumeration(i); + let path = self.path(&e.path); + let ty = Type::Enum(i); + let wildcard = match e.exhaustive { + true => "", + false => "\n\t\t_ => unreachable!(\"a variant this export does not know\"),", + }; + if e.plain() { + let lift: Vec = e + .variants + .iter() + .map(|v| format!("\n\t\t{} => {path}::{},", v.discriminant, v.name)) + .collect(); + let lower: Vec = e + .variants + .iter() + .map(|v| format!("\n\t\t{path}::{} => {},", v.name, v.discriminant)) + .collect(); + self.line(format!( + "fn lift_{name}(c: i32, w: &str) -> {path} {{\n\tmatch c {{{}\n\t\t_ => rt::fail(w, \"an enum value is invalid\"),\n\t}}\n}}\n", + lift.concat() + )); + self.line(format!( + "fn lower_{name}(v: {path}) -> i32 {{\n\tmatch v {{{}{wildcard}\n\t}}\n}}\n", + lower.concat() + )); + } else { + let mut members = String::new(); + for (n, variant) in e.variants.iter().enumerate().filter(|(_, v)| !v.fields.is_empty()) { + let payload = format!("{name}_{}", abi::snake(&variant.name)); + let mut fields = String::new(); + for (k, field) in variant.fields.iter().enumerate() { + let _ = writeln!(fields, "\tpub f{k}: {},", self.rs(&self.abi.ty(&field.ty))); + } + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub struct {payload} {{\n{fields}}}\n" + )); + let _ = writeln!(members, "\tpub v{n}: {payload},"); + } + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub union {name}_union {{\n{members}}}\n" + )); + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub struct {name} {{\n\tpub tag: i32,\n\tpub u: {name}_union,\n}}\n" + )); + let mut lift = String::new(); + let mut lower = String::new(); + let mut free = String::new(); + for (n, variant) in e.variants.iter().enumerate() { + let bindings: Vec = (0..variant.fields.len()).map(|k| format!("f{k}")).collect(); + let pattern = match (variant.fields.is_empty(), variant.tuple) { + (true, _) => format!("{path}::{}", variant.name), + (false, true) => format!("{path}::{}({})", variant.name, bindings.join(", ")), + (false, false) => { + let fields: Vec = variant + .fields + .iter() + .zip(&bindings) + .map(|(f, b)| format!("{}: {b}", f.name)) + .collect(); + format!("{path}::{} {{ {} }}", variant.name, fields.join(", ")) + } + }; + if variant.fields.is_empty() { + let _ = write!(lift, "\n\t\t{n} => {pattern},"); + let _ = write!( + lower, + "\n\t\t{pattern} => {name} {{ tag: {n}, u: unsafe {{ ::std::mem::zeroed() }} }}," + ); + continue; + } + let payload = format!("{name}_{}", abi::snake(&variant.name)); + let lifted: Vec = variant + .fields + .iter() + .enumerate() + .map(|(k, f)| self.lift(&f.ty, &format!("p.f{k}"))) + .collect(); + let build = match variant.tuple { + true => format!("{path}::{}({})", variant.name, lifted.join(", ")), + false => { + let fields: Vec = variant + .fields + .iter() + .zip(&lifted) + .map(|(f, l)| format!("{}: {l}", f.name)) + .collect(); + format!("{path}::{} {{ {} }}", variant.name, fields.join(", ")) + } + }; + let _ = write!( + lift, + "\n\t\t{n} => {{\n\t\t\tlet p = unsafe {{ c.u.v{n} }};\n\t\t\t{build}\n\t\t}}" + ); + let lowered: Vec = variant + .fields + .iter() + .enumerate() + .map(|(k, f)| format!("f{k}: {}", self.lower(&f.ty, &format!("f{k}")))) + .collect(); + let _ = write!( + lower, + "\n\t\t{pattern} => {name} {{ tag: {n}, u: {name}_union {{ v{n}: {payload} {{ {} }} }} }},", + lowered.join(", ") + ); + let frees: Vec = variant + .fields + .iter() + .enumerate() + .filter_map(|(k, f)| self.free(&f.ty, &format!("p.f{k}"))) + .collect(); + if !frees.is_empty() { + let _ = write!( + free, + "\n\t\t{n} => {{\n\t\t\tlet p = unsafe {{ c.u.v{n} }};\n\t\t\t{}\n\t\t}}", + frees.join("\n\t\t\t") + ); + } + } + self.line(format!( + "fn lift_{name}(c: &{name}, w: &str) -> {path} {{\n\tmatch c.tag {{{lift}\n\t\t_ => rt::fail(w, \"an enum tag is invalid\"),\n\t}}\n}}\n" + )); + self.line(format!( + "fn lower_{name}(v: {path}) -> {name} {{\n\tmatch v {{{lower}{wildcard}\n\t}}\n}}\n" + )); + if self.owns(&ty) { + self.line(format!( + "fn free_{name}(c: {name}) {{\n\tmatch c.tag {{{free}\n\t\t_ => {{}}\n\t}}\n}}\n" + )); + } + } + self.value_traits(&name, &path, &ty, e.traits); + let owner = self.abi.ty(&ty); + for method in &e.methods { + self.function(method, Some((&owner, None))); + } + } + + fn callback(&mut self, _i: usize) {} + + /// An argument: the statement binding it from its C parameter `c` to `local`, and + /// the expression passing it. A future owns its arguments, so it borrows nothing + /// from the caller. + fn arg(&self, ty: &Type, c: &str, local: &str, future: bool) -> (String, String) { + match ty { + Type::Ref(m, inner) => match (&**inner, m, future) { + (Type::Object(i), _, _) => { + let exclusive = *m == Mutability::Mut || !self.abi.api.objects[*i].sync; + let borrow = match (exclusive, future) { + (false, false) => "borrow", + (true, false) => "borrow_mut", + (false, true) => "borrow_arc", + (true, true) => "borrow_mut_arc", + }; + let binding = match exclusive { + true => "let mut", + false => "let", + }; + let pass = match m { + Mutability::Mut => format!("&mut *{local}"), + Mutability::Not => format!("&*{local}"), + }; + ( + format!( + "{binding} {local} = unsafe {{ rt::Object::<{}>::{borrow}({c}, w) }};", + self.object_path(*i) + ), + pass, + ) + } + (Type::Str, Mutability::Not, false) => { + (format!("let {local} = unsafe {{ {c}.str(w) }};"), local.to_string()) + } + (Type::Slice, Mutability::Not, false) => { + (format!("let {local} = unsafe {{ {c}.bytes(w) }};"), local.to_string()) + } + (inner, m, _) => { + let pass = match m { + Mutability::Mut => format!("&mut {local}"), + Mutability::Not => format!("&{local}"), + }; + (format!("let mut {local} = {};", self.lift(inner, c)), pass) + } + }, + _ => (format!("let {local} = {};", self.lift(ty, c)), local.to_string()), + } + } + + /// The statements that hand a call's `result` to C: return it, or for a fallible + /// function, write it through `out` or `err` and return whether it succeeded. + fn finish(&self, function: &Function, ret: (&str, &str, &str)) -> String { + let (ok_value, ready, error) = ret; + let out_ty = self.rs(&self.abi.ty(&function.ok)); + let write_ok = match function.ok { + Type::Unit => String::new(), + _ => format!( + "unsafe {{ rt::write::<{out_ty}>(out.cast(), || {}) }};", + self.lower(&function.ok, "v") + ), + }; + match &function.err { + None if ok_value.is_empty() => match function.ok { + Type::Unit => "result".to_string(), + _ => self.lower(&function.ok, "result"), + }, + None => format!("let v = result;\n\t{write_ok}\n\t{ready}"), + Some(err) => format!( + "match result {{\n\t\tOk(v) => {{\n\t\t\tlet _ = &v;\n\t\t\t{write_ok}\n\t\t\t{ready}\n\t\t}}\n\t\tErr(e) => {{\n\t\t\tunsafe {{ rt::write::<{}>(err.cast(), || {}) }};\n\t\t\t{error}\n\t\t}}\n\t}}", + self.rs(&self.abi.ty(err)), + self.lower(err, "e") + ), + } + } + + /// An exported function, a method of `owner` if it has one: its C type, and the + /// object it belongs to, if any. + fn function(&mut self, function: &Function, owner: Option<(&Ty, Option)>) { + let export = self.abi.export(function, owner.map(|(ty, _)| ty)); + let name = export.call.name.clone(); + let future = function.future; + let mut stmts = Vec::new(); + let mut args = Vec::new(); + let mut params = Vec::new(); + let mut c_params = export.call.params.iter(); + let receiver_ty = owner.zip(function.receiver); + if let Some(((owner_ty, object), receiver)) = receiver_ty { + let (_, c_ty) = c_params.next().expect("a method takes self"); + params.push(format!("this: {}", self.rs(c_ty))); + match object { + Some(i) => { + let ty = match receiver { + Receiver::Ref => Type::Ref(Mutability::Not, Box::new(Type::Object(i))), + Receiver::Mut => Type::Ref(Mutability::Mut, Box::new(Type::Object(i))), + Receiver::Owned => Type::Object(i), + }; + let (stmt, arg) = self.arg(&ty, "this", "a_self", future); + stmts.push(stmt); + args.push(arg); + } + None => { + let value = self.value_type(owner_ty); + stmts.push(format!("let a_self = {};", self.lift(&value, "unsafe { *this }"))); + args.push(match receiver { + Receiver::Owned => "a_self".to_string(), + _ => "&a_self".to_string(), + }); + } + } + } + for (n, (param, (_, c_ty))) in function.params.iter().zip(c_params).enumerate() { + params.push(format!("p{n}: {}", self.rs(c_ty))); + let (stmt, arg) = self.arg(¶m.ty, &format!("p{n}"), &format!("a{n}"), future); + stmts.push(stmt); + args.push(arg); + } + let callee = match owner { + Some(_) => { + let (owner_path, method) = function.path.split_at(function.path.len() - 1); + format!("<{}>::{}", self.path(owner_path), method[0]) + } + None => self.path(&function.path), + }; + let call = format!("{callee}({})", args.join(", ")); + let body = stmts.join("\n\t"); + if let Some((_, poll, free)) = &export.future { + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> *mut rt::Future {{\n\tlet w = \"{name}\";\n\tlet _ = w;\n\t{body}\n\trt::Future::new(async move {{\n\t\tlet result = {call}.await;\n\t\t::std::boxed::Box::new(move |out: *mut c_void, err: *mut c_void| -> i32 {{\n\t\t\tlet _ = (out, err);\n\t\t\t{}\n\t\t}}) as rt::Done\n\t}})\n}}\n", + params.join(", "), + self.finish(function, ("v", "rt::READY", "rt::ERROR")) + )); + let poll_params: Vec = poll.params[2..] + .iter() + .map(|(n, ty)| format!("{n}: {}", self.rs(ty))) + .collect(); + let out = match function.ok { + Type::Unit => "::std::ptr::null_mut()", + _ => "out.cast()", + }; + let err = match function.err { + Some(_) => "err.cast()", + None => "::std::ptr::null_mut()", + }; + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {}(future: *mut rt::Future, waker: rt::Waker{}) -> i32 {{\n\tunsafe {{ rt::Future::poll(future, waker, {out}, {err}, \"{}\") }}\n}}\n", + poll.name, + poll_params.iter().map(|p| format!(", {p}")).collect::(), + poll.name + )); + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {}(future: *mut rt::Future) {{\n\tunsafe {{ rt::Future::free(future) }}\n}}\n", + free.name + )); + return; + } + let outs: Vec = export.call.params[params.len()..] + .iter() + .map(|(n, ty)| format!("{n}: {}", self.rs(ty))) + .collect(); + params.extend(outs); + let ret = self.rs(&export.call.ret); + let finish = match function.err { + Some(_) => self.finish(function, ("v", "true", "false")), + None => self.finish(function, ("", "", "")), + }; + self.line(format!( + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> {ret} {{\n\tlet w = \"{name}\";\n\tlet _ = w;\n\t{body}\n\tlet result = {call};\n\t{finish}\n}}\n", + params.join(", "), + )); + } + + /// The IR type of a value's C type, for its receiver. + fn value_type(&self, ty: &Ty) -> Type { + let api = self.abi.api; + let name = match ty { + Ty::Struct(name) | Ty::Enum(name) => name, + other => unreachable!("a value's receiver is {other:?}"), + }; + if let Some(i) = (0..api.records.len()).find(|&i| &self.abi.record(i) == name) { + return Type::Record(i); + } + let i = (0..api.enums.len()) + .find(|&i| &self.abi.enumeration(i) == name) + .expect("a value is a record or enum"); + Type::Enum(i) + } +} diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs new file mode 100644 index 000000000..c1aeda617 --- /dev/null +++ b/ffi/src/ir.rs @@ -0,0 +1,234 @@ +//! The exported API, as each generator reads it: what the crate's `pub` items became, +//! with no language's names or calling convention decided yet. +//! +//! Every item keeps its path from the crate root, so a generator names it by its own +//! rule, and its span, so a generator refuses it with one. + +use rustc_span::Span; + +/// A crate's exported API. +pub struct Api { + /// The crate's name, as Rust code names it: `moq_net`. + pub krate: String, + pub records: Vec, + pub enums: Vec, + pub objects: Vec, + pub callbacks: Vec, + pub functions: Vec, + pub constants: Vec, +} + +/// A path from the crate root: `["track", "Producer", "append_group"]`. +pub type Path = Vec; + +/// A struct whose fields are all `pub`: a value, copied across. +pub struct Record { + pub path: Path, + pub span: Span, + pub fields: Vec, + /// Whether its fields are positional, named `0`, `1`, ... + pub tuple: bool, + pub methods: Vec, + pub traits: Traits, +} + +pub struct Field { + /// Its Rust name: a number for a positional field. + pub name: String, + pub ty: Type, +} + +/// An enum: a value, copied across. Without fields in any variant, it is a plain +/// enumeration. +pub struct Enum { + pub path: Path, + pub span: Span, + pub variants: Vec, + /// Whether another crate can match it without a wildcard arm. + pub exhaustive: bool, + pub methods: Vec, + pub traits: Traits, +} + +pub struct Variant { + pub name: String, + /// Its discriminant, for an enum without fields. + pub discriminant: i128, + pub fields: Vec, + pub tuple: bool, +} + +impl Enum { + /// Whether no variant has fields. + pub fn plain(&self) -> bool { + self.variants.iter().all(|v| v.fields.is_empty()) + } +} + +/// Any other type: a handle to a value the foreign side never sees inside, shared behind +/// an `Arc`, whose receivers borrow it as Rust's do, checked at run time. +pub struct Object { + pub path: Path, + pub span: Span, + /// Whether it is `Sync`: if not, even its `&self` methods borrow it exclusively. + pub sync: bool, + pub methods: Vec, + pub traits: Traits, +} + +/// A `pub` trait: implemented by the foreign side, through a table of functions. +pub struct Callback { + pub path: Path, + pub span: Span, + /// Its required methods, each taking `&self` or `&mut self`. + pub methods: Vec, +} + +/// The std traits a type's impls export. +#[derive(Default, Clone, Copy)] +pub struct Traits { + pub clone: bool, + pub eq: bool, + pub display: bool, + pub debug: bool, + pub default: bool, +} + +/// A function or method. +pub struct Function { + /// Its path, ending in its own name: a method's goes through its type's. + pub path: Path, + pub span: Span, + pub receiver: Option, + pub params: Vec, + /// What it returns, or for a future, what the future does. + pub ok: Type, + /// The error of a `Result` it returns. + pub err: Option, + /// Whether it returns a future: an `async fn`, or a value that implements `Future`. + pub future: bool, +} + +impl Function { + pub fn name(&self) -> &str { + self.path.last().expect("a function has a name") + } +} + +/// How a method takes `self`. +#[derive(Clone, Copy, PartialEq, Eq)] +pub enum Receiver { + /// `&self` + Ref, + /// `&mut self` + Mut, + /// `self` + Owned, +} + +pub struct Param { + pub name: String, + pub ty: Type, +} + +/// A `pub const`. +pub struct Constant { + pub path: Path, + pub span: Span, + pub value: Literal, +} + +pub enum Literal { + Bool(bool), + Int(Int, i128), +} + +/// A type as the API uses it, in the exact form the Rust side takes or returns. +#[derive(Clone, PartialEq, Eq, Debug)] +pub enum Type { + Unit, + Bool, + Int(Int), + F32, + F64, + Char, + /// `str`, only behind a reference. + Str, + String, + /// `[u8]`, only behind a reference. + Slice, + /// `Vec` + Vec, + /// `bytes::Bytes` + Bytes, + /// `std::time::Duration` + Duration, + Option(Box), + /// `Box`, of a non-trait type. + Box(Box), + Ref(Mutability, Box), + Record(usize), + Enum(usize), + Object(usize), + /// A foreign implementation of a callback trait, in the form the parameter takes. + Callback(usize, Dyn), +} + +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Mutability { + Not, + Mut, +} + +/// How a parameter takes a foreign implementation of a trait. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Dyn { + /// A type parameter or `impl Trait`, given the foreign type. + Impl, + /// `Box` + Box, + /// `Arc` + Arc, +} + +#[derive(Clone, Copy, PartialEq, Eq, Debug, Hash)] +pub enum Int { + U8, + U16, + U32, + U64, + Usize, + I8, + I16, + I32, + I64, + Isize, +} + +impl Int { + /// Its Rust name. + pub fn rust(self) -> &'static str { + match self { + Int::U8 => "u8", + Int::U16 => "u16", + Int::U32 => "u32", + Int::U64 => "u64", + Int::Usize => "usize", + Int::I8 => "i8", + Int::I16 => "i16", + Int::I32 => "i32", + Int::I64 => "i64", + Int::Isize => "isize", + } + } +} + +impl Type { + /// The type behind any reference or `Box`. + pub fn base(&self) -> &Type { + match self { + Type::Ref(_, inner) | Type::Box(inner) => inner.base(), + ty => ty, + } + } +} diff --git a/ffi/src/main.rs b/ffi/src/main.rs new file mode 100644 index 000000000..dd68e48a6 --- /dev/null +++ b/ffi/src/main.rs @@ -0,0 +1,38 @@ +//! rust2-ffi: export a crate's `pub` API as a C ABI and header, with no attributes. +//! +//! The binary is two programs, as rust2-ts is. Run directly, it is the CLI: it runs +//! cargo on the configured package with itself as `RUSTC_WRAPPER`. Run by cargo as that +//! wrapper, it is rustc, which collects the configured library's API after type checking +//! and writes the export. + +#![feature(rustc_private)] + +extern crate rustc_data_structures; +extern crate rustc_driver; +extern crate rustc_errors; +extern crate rustc_hir; +extern crate rustc_infer; +extern crate rustc_interface; +extern crate rustc_middle; +extern crate rustc_span; +extern crate rustc_trait_selection; + +mod abi; +mod c; +mod census; +mod cli; +mod collect; +mod config; +mod driver; +mod glue; +mod ir; + +use std::process::ExitCode; + +fn main() -> ExitCode { + let args: Vec = std::env::args().collect(); + if rust2_driver::rustc::wrapped(&args) { + return driver::run(args); + } + cli::run(&args[1..]) +} diff --git a/justfile b/justfile index 6b416d310..c524200c5 100644 --- a/justfile +++ b/justfile @@ -3,6 +3,9 @@ set shell := ["bash", "-euo", "pipefail", "-c"] # The TypeScript driver, its own workspace on its own nightly: `just ts `. mod ts +# The C exporter, its own workspace on the TypeScript driver's nightly: `just ffi `. +mod ffi + # The UniFFI fork, in the root workspace: `just uniffi `. mod uniffi diff --git a/ts/src/cli.rs b/ts/src/cli.rs index 5b58b2df4..27e3b24c0 100644 --- a/ts/src/cli.rs +++ b/ts/src/cli.rs @@ -1,8 +1,9 @@ //! The command line: run cargo on the configured package with this binary as rustc. -use std::path::Path; use std::process::ExitCode; +use rust2_driver::cargo::{Args, Check, Output}; + use crate::config::{self, Config}; /// Translation type-checks for this target: its 32-bit `usize` is what a JS number @@ -29,63 +30,21 @@ pub fn run(args: &[String]) -> ExitCode { } fn try_run(args: &[String]) -> Result { - let mut config = None; - let mut out = None; - let mut census = None; - let mut manifest = None; - let mut cargo_args: &[String] = &[]; - let mut rest = args; - while let [arg, tail @ ..] = rest { - rest = tail; - match arg.as_str() { - "--config" | "--out" | "--census" | "--manifest-path" => { - let [value, tail @ ..] = rest else { - return Err(format!("{arg} needs a value\n\n{USAGE}")); - }; - rest = tail; - let slot = match arg.as_str() { - "--config" => &mut config, - "--out" => &mut out, - "--census" => &mut census, - _ => &mut manifest, - }; - *slot = Some(rust2_driver::cargo::absolute(Path::new(value))?); - } - "--" => { - cargo_args = rest; - break; - } - "-h" | "--help" => { - println!("{USAGE}"); - return Ok(ExitCode::SUCCESS); - } - _ => return Err(format!("unexpected argument {arg}\n\n{USAGE}")), - } - } - let config_path = config.ok_or_else(|| format!("--config is required\n\n{USAGE}"))?; - let (output_env, output) = match (out, census) { - (Some(out), None) => (config::env::OUT, out), - (None, Some(census)) => (config::env::CENSUS, census), - _ => return Err(format!("one of --out and --census is required\n\n{USAGE}")), + let Some(args) = Args::parse(args, USAGE)? else { + return Ok(ExitCode::SUCCESS); }; - let config = Config::load(&config_path)?; - let manifest = match manifest { - Some(manifest) => manifest, - None => config_path - .parent() - .expect("an absolute file path has a parent") - .join("Cargo.toml"), + let config = Config::load(&args.config)?; + let output = match &args.output { + Output::Dir(out) => (config::env::OUT, out.as_os_str()), + Output::Census(census) => (config::env::CENSUS, census.as_os_str()), }; - rust2_driver::cargo::Check { + Check { tool: "rust2-ts", - manifest: &manifest, + manifest: &args.manifest, package: &config.package, target: Some(TARGET), - args: cargo_args, - env: &[ - (config::env::CONFIG, config_path.as_os_str()), - (output_env, output.as_os_str()), - ], + args: &args.cargo, + env: &[(config::env::CONFIG, args.config.as_os_str()), output], } .run() } From 50474f5f6e14bbeea7f29f981c67d4e2029dec63 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:06:58 -0700 Subject: [PATCH 04/16] wip(ffi): api fixture driven from C against its native transcript, and reject fixture Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/Cargo.lock | 4 + ffi/fixtures/api/examples/transcript.rs | 86 ++++++++++++ ffi/fixtures/api/ffi.toml | 2 + ffi/fixtures/api/src/lib.rs | 178 ++++++++++++++++++++++++ ffi/fixtures/reject/Cargo.toml | 10 ++ ffi/fixtures/reject/expected.txt | 8 ++ ffi/fixtures/reject/ffi.toml | 4 + ffi/fixtures/reject/src/lib.rs | 48 +++++++ ffi/src/abi.rs | 7 +- ffi/src/census.rs | 9 +- ffi/src/driver.rs | 6 +- ffi/src/glue.rs | 8 +- ffi/tests/api.c | 154 ++++++++++++++++++++ ffi/tests/fixtures.rs | 130 +++++++++++++++++ 14 files changed, 643 insertions(+), 11 deletions(-) create mode 100644 ffi/fixtures/api/examples/transcript.rs create mode 100644 ffi/fixtures/api/ffi.toml create mode 100644 ffi/fixtures/reject/Cargo.toml create mode 100644 ffi/fixtures/reject/expected.txt create mode 100644 ffi/fixtures/reject/ffi.toml create mode 100644 ffi/fixtures/reject/src/lib.rs create mode 100644 ffi/tests/api.c create mode 100644 ffi/tests/fixtures.rs diff --git a/ffi/Cargo.lock b/ffi/Cargo.lock index 0f377369e..77ea36adc 100644 --- a/ffi/Cargo.lock +++ b/ffi/Cargo.lock @@ -55,6 +55,10 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "reject-fixture" +version = "0.0.0" + [[package]] name = "rust2-driver" version = "0.0.0" diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs new file mode 100644 index 000000000..a5880dcbf --- /dev/null +++ b/ffi/fixtures/api/examples/transcript.rs @@ -0,0 +1,86 @@ +//! The script `tests/api.c` runs through the C ABI, run natively: the two transcripts +//! must match line for line. + +use std::future::Future; +use std::pin::pin; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::task::{Context, Poll, Wake, Waker}; + +use api_fixture::{Channel, Counter, Event, LIMIT, Point, Shape}; +use bytes::Bytes; + +struct Count(AtomicUsize); + +impl Wake for Count { + fn wake(self: Arc) { + self.0.fetch_add(1, Ordering::Relaxed); + } +} + +fn main() { + println!("limit {LIMIT}"); + + let p = Point { x: 1, y: 2 }.offset(2, 3); + println!("offset {} {}", p.x, p.y); + println!("debug {p:?}"); + println!("eq {}", p == Point { x: 3, y: 5 }); + let d = Point::default(); + println!("default {} {}", d.x, d.y); + + let mut c = Counter::new("c", 5); + println!("get {}", c.get()); + println!("name {}", c.name()); + match c.add(10) { + Ok(v) => println!("add ok {v}"), + Err(e) => println!("add err {e}"), + } + match c.add(2000) { + Ok(v) => println!("add ok {v}"), + Err(e) => println!("add err {e} {e:?}"), + } + match c.sub(20) { + Ok(v) => println!("sub ok {v}"), + Err(e) => println!("sub err {e} {e:?}"), + } + c.rename("d"); + println!("name {}", c.name()); + let mut copy = c.clone(); + let _ = copy.add(1); + println!("clone {} original {}", copy.get(), c.get()); + println!("debug {c:?}"); + let label = c.into_label(Some(p)); + println!("label {label:?}"); + + println!("{}", api_fixture::greet("x", Shape::Square)); + println!("len {}", api_fixture::len(b"abc")); + for event in [ + Event::Moved(p), + Event::Named { name: "n".to_string() }, + Event::Done, + ] { + println!("{}", api_fixture::describe(&event)); + } + + let channel = Channel::new(); + let count = Arc::new(Count(AtomicUsize::new(0))); + let waker = Waker::from(count.clone()); + let mut cx = Context::from_waker(&waker); + { + let mut recv = pin!(channel.recv()); + let first = recv.as_mut().poll(&mut cx); + println!("recv pending {}", first.is_pending()); + channel.send(Bytes::from_static(b"hi")); + println!("woken {}", count.0.load(Ordering::Relaxed)); + if let Poll::Ready(payload) = recv.as_mut().poll(&mut cx) { + println!("recv {}", String::from_utf8_lossy(&payload)); + } + } + channel.send(Bytes::new()); + let mut recv = pin!(channel.recv_nonempty()); + match recv.as_mut().poll(&mut cx) { + Poll::Ready(Ok(payload)) => println!("nonempty {}", payload.len()), + Poll::Ready(Err(e)) => println!("nonempty err {e}"), + Poll::Pending => println!("nonempty pending"), + } +} diff --git a/ffi/fixtures/api/ffi.toml b/ffi/fixtures/api/ffi.toml new file mode 100644 index 000000000..1c73c98f6 --- /dev/null +++ b/ffi/fixtures/api/ffi.toml @@ -0,0 +1,2 @@ +package = "api-fixture" +prefix = "api" diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index 33acea8ea..b44ae1959 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -1,8 +1,186 @@ //! Each construct rust2-ffi exports, for `tests/api.c` to drive through the C ABI. +use std::fmt; +use std::sync::{Arc, Mutex}; +use std::task::{Poll, Waker}; +use std::time::Duration; + +use bytes::Bytes; + +/// The largest value a [`Counter`] reaches. +pub const LIMIT: u64 = 1000; + /// A point: a record, since every field is `pub`. #[derive(Clone, Copy, Debug, PartialEq, Default)] pub struct Point { pub x: i32, pub y: i32, } + +impl Point { + /// The point moved by `dx` and `dy`. + pub fn offset(&self, dx: i32, dy: i32) -> Point { + Point { + x: self.x + dx, + y: self.y + dy, + } + } +} + +/// A record that owns memory: its `free` releases the name. +#[derive(Clone, Debug, PartialEq)] +pub struct Label { + pub name: String, + pub at: Option, + pub ttl: Option, +} + +/// A plain enumeration. +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum Shape { + Circle = 1, + Square = 4, +} + +/// An enum with data. +#[derive(Clone, Debug, PartialEq)] +pub enum Event { + Moved(Point), + Named { name: String }, + Done, +} + +/// The error a [`Counter`] returns. +#[derive(Clone, Debug, PartialEq)] +pub enum Error { + Underflow { by: u64 }, + Overflow, +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Error::Underflow { by } => write!(f, "underflow by {by}"), + Error::Overflow => write!(f, "overflow"), + } + } +} + +/// A counter: an object, since its field is private. Clones share nothing. +#[derive(Clone, Debug, Default)] +pub struct Counter { + value: u64, + name: String, +} + +impl Counter { + pub fn new(name: &str, start: u64) -> Self { + Self { + value: start, + name: name.to_string(), + } + } + + pub fn get(&self) -> u64 { + self.value + } + + pub fn name(&self) -> &str { + &self.name + } + + pub fn add(&mut self, n: u64) -> Result { + match self.value.checked_add(n) { + Some(v) if v <= LIMIT => { + self.value = v; + Ok(v) + } + _ => Err(Error::Overflow), + } + } + + pub fn sub(&mut self, n: u64) -> Result { + match self.value.checked_sub(n) { + Some(v) => { + self.value = v; + Ok(v) + } + None => Err(Error::Underflow { by: n - self.value }), + } + } + + /// Consumes the counter. + pub fn into_label(self, at: Option) -> Label { + Label { + name: self.name, + at, + ttl: None, + } + } + + pub fn rename(&mut self, name: impl Into) { + self.name = name.into(); + } +} + +/// A one-slot channel: its receive is a future that waits for a send. +#[derive(Clone, Default)] +pub struct Channel { + state: Arc, Option)>>, +} + +impl Channel { + pub fn new() -> Self { + Self::default() + } + + /// Drop any payload not yet received. Exclusive, so it cannot run while a receive + /// borrows the channel. + pub fn clear(&mut self) { + self.state.lock().unwrap().0 = None; + } + + pub fn send(&self, payload: Bytes) { + let mut state = self.state.lock().unwrap(); + state.0 = Some(payload); + if let Some(waker) = state.1.take() { + waker.wake(); + } + } + + /// The next payload sent, waiting for it. + pub async fn recv(&self) -> Bytes { + std::future::poll_fn(|cx| { + let mut state = self.state.lock().unwrap(); + match state.0.take() { + Some(payload) => Poll::Ready(payload), + None => { + state.1 = Some(cx.waker().clone()); + Poll::Pending + } + } + }) + .await + } + + /// Fails once the payload is empty. + pub async fn recv_nonempty(&self) -> Result { + match self.recv().await { + payload if payload.is_empty() => Err(Error::Underflow { by: 1 }), + payload => Ok(payload), + } + } +} + +/// The length of a payload, borrowed for the call. +pub fn len(payload: &[u8]) -> usize { + payload.len() +} + +pub fn greet(name: impl Into, shape: Shape) -> String { + format!("hello {}, a {shape:?}", name.into()) +} + +pub fn describe(event: &Event) -> String { + format!("{event:?}") +} diff --git a/ffi/fixtures/reject/Cargo.toml b/ffi/fixtures/reject/Cargo.toml new file mode 100644 index 000000000..fc53c130e --- /dev/null +++ b/ffi/fixtures/reject/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "reject-fixture" +description = "Items rust2-ffi cannot export, each refused with its span" +version = "0.0.0" +edition = "2024" +license = "MIT OR Apache-2.0" +publish = false + +[lints] +workspace = true diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt new file mode 100644 index 000000000..52f9b732e --- /dev/null +++ b/ffi/fixtures/reject/expected.txt @@ -0,0 +1,8 @@ +fixtures/reject/src/lib.rs:14:1: rust2-ffi: cannot export fn `map`: foreign type `std::collections::HashMap`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:24:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:28:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:36:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:47:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C +fixtures/reject/src/lib.rs:6:1: rust2-ffi: cannot export struct `Wrap`: generic type; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclude it in the config to leave it out diff --git a/ffi/fixtures/reject/ffi.toml b/ffi/fixtures/reject/ffi.toml new file mode 100644 index 000000000..7b8c2daf5 --- /dev/null +++ b/ffi/fixtures/reject/ffi.toml @@ -0,0 +1,4 @@ +package = "reject-fixture" +prefix = "reject" +# An exclusion leaves an item out, so nothing refuses it. +exclude = ["Excluded"] diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs new file mode 100644 index 000000000..2f4273745 --- /dev/null +++ b/ffi/fixtures/reject/src/lib.rs @@ -0,0 +1,48 @@ +//! Items rust2-ffi cannot export: each is a compile error at its span. + +use std::collections::HashMap; + +/// A generic type. +pub struct Wrap(pub T); + +/// A tuple return. +pub fn pair() -> (u8, u8) { + (1, 2) +} + +/// Another crate's type, which has no mapping. +pub fn map() -> HashMap { + HashMap::new() +} + +/// A type parameter no rule picks a type for. +pub fn generic(value: T) -> T { + value +} + +/// A static. +pub static COUNT: u8 = 0; + +/// A macro. +#[macro_export] +macro_rules! noop { + () => {}; +} + +/// Left out by the config, so it refuses nothing itself, but a signature naming it is +/// refused. +pub struct Excluded; + +pub fn excluded() -> Excluded { + Excluded +} + +pub mod audio_encoder { + /// `reject_audio_encoder_finish` in C ... + pub fn finish() {} +} + +pub mod audio { + /// ... and so is this: the clash is refused at both. + pub fn encoder_finish() {} +} diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index ebcbab05e..4d4c83184 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -13,6 +13,9 @@ use rustc_span::Span; use crate::ir::{Api, Dyn, Function, Int, Receiver, Type}; +/// A C name claimed twice: the name, then what claimed it first and second. +pub type Clash = (String, (String, Span), (String, Span)); + /// A C type, as a parameter, field, or return value takes it. #[derive(Clone, PartialEq, Eq, Debug)] pub enum Ty { @@ -67,8 +70,8 @@ pub struct Abi<'a> { pub options: BTreeMap, /// Every C name claimed, with what claimed it. names: HashMap, - /// Each name claimed twice: the name, then both claimants. - pub clashes: Vec<(String, (String, Span), (String, Span))>, + /// Each name claimed twice. + pub clashes: Vec, } impl<'a> Abi<'a> { diff --git a/ffi/src/census.rs b/ffi/src/census.rs index 0b82ae61a..25f6e6ab4 100644 --- a/ffi/src/census.rs +++ b/ffi/src/census.rs @@ -6,10 +6,11 @@ use std::fmt::Write; use rustc_span::Span; +use crate::abi::Clash; use crate::collect::{Collected, Refusal}; /// The census of `krate` as Markdown; `at` locates a span. -pub fn render(krate: &str, collected: &Collected, at: &dyn Fn(Span) -> String) -> String { +pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn(Span) -> String) -> String { let api = &collected.api; let refused = |kinds: &[&str]| collected.refusals.iter().filter(|r| kinds.contains(&r.kind)).count(); let methods: usize = api.objects.iter().map(|o| o.methods.len()).sum::() @@ -115,6 +116,12 @@ pub fn render(krate: &str, collected: &Collected, at: &dyn Fn(Span) -> String) - ); } + if !clashes.is_empty() { + let _ = writeln!(out, "\n## C names claimed twice\n"); + for (name, (first, _), (second, span)) in clashes { + let _ = writeln!(out, "- `{name}`: {first}, and {second} at {}", at(*span)); + } + } if !collected.opaque.is_empty() { let _ = writeln!(out, "\n## Values exported as objects, since a field does not map\n"); for (path, why) in &collected.opaque { diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index cd9f841a8..885341f86 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -83,7 +83,8 @@ impl Callbacks for Export { let collected = collect::collect(tcx, &self.config); let written = match &self.output { Output::Census(path) => { - let text = census::render(&self.config.package, &collected, &|span| at(tcx, span)); + let abi = Abi::new(&collected.api, &self.config.prefix()); + let text = census::render(&self.config.package, &collected, &abi.clashes, &|span| at(tcx, span)); write(path, &text) } Output::Dir(out) => { @@ -111,9 +112,6 @@ impl Callbacks for Export { tcx.dcx().err(format!("rust2-ffi: exclude `{path}` names nothing exported")); } } - if tcx.dcx().has_errors().is_some() { - return Compilation::Stop; - } let abi = Abi::new(&collected.api, &self.config.prefix()); for (name, (first, first_span), (second, second_span)) in &abi.clashes { tcx.dcx() diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 66a951a21..7cfe8d1d0 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -594,11 +594,11 @@ impl Gen<'_> { (format!("let {local} = unsafe {{ {c}.bytes(w) }};"), local.to_string()) } (inner, m, _) => { - let pass = match m { - Mutability::Mut => format!("&mut {local}"), - Mutability::Not => format!("&{local}"), + let (binding, pass) = match m { + Mutability::Mut => ("let mut", format!("&mut {local}")), + Mutability::Not => ("let", format!("&{local}")), }; - (format!("let mut {local} = {};", self.lift(inner, c)), pass) + (format!("{binding} {local} = {};", self.lift(inner, c)), pass) } }, _ => (format!("let {local} = {};", self.lift(ty, c)), local.to_string()), diff --git a/ffi/tests/api.c b/ffi/tests/api.c new file mode 100644 index 000000000..45a509742 --- /dev/null +++ b/ffi/tests/api.c @@ -0,0 +1,154 @@ +/* The api fixture's C test: the script fixtures/api/examples/transcript.rs runs + * natively, through the exported C ABI. tests/fixtures.rs compares the transcripts. + * + * With an argument, it instead breaks one contract of the ABI, which must abort. */ + +#include +#include + +#include "api.h" + +static api_buf str(const char *s) { + return (api_buf){.ptr = (const uint8_t *)s, .len = strlen(s)}; +} + +/* Print a returned buffer, then free it. */ +static void print(const char *before, api_buf buf, const char *after) { + printf("%s%.*s%s", before, (int)buf.len, (const char *)buf.ptr, after); + api_buf_free(buf); +} + +static int wakes = 0; +static int drops = 0; + +static void wake(void *data) { + (void)data; + wakes++; +} + +static void drop(void *data) { + (void)data; + drops++; +} + +static int script(void) { + printf("limit %llu\n", (unsigned long long)API_LIMIT); + + api_point start = {.x = 1, .y = 2}; + api_point p = api_point_offset(&start, 2, 3); + printf("offset %d %d\n", p.x, p.y); + print("debug ", api_point_debug(&p), "\n"); + api_point expected = {.x = 3, .y = 5}; + printf("eq %s\n", api_point_eq(&p, &expected) ? "true" : "false"); + api_point d = api_point_default(); + printf("default %d %d\n", d.x, d.y); + + api_counter *c = api_counter_new(str("c"), 5); + printf("get %llu\n", (unsigned long long)api_counter_get(c)); + print("name ", api_counter_name(c), "\n"); + uint64_t v; + api_error err; + if (api_counter_add(c, 10, &v, &err)) { + printf("add ok %llu\n", (unsigned long long)v); + } + if (!api_counter_add(c, 2000, &v, &err)) { + print("add err ", api_error_to_string(&err), " "); + print("", api_error_debug(&err), "\n"); + api_error_free(&err); + } + if (!api_counter_sub(c, 20, &v, &err)) { + printf("sub err underflow by %llu ", (unsigned long long)err.underflow.by); + print("", api_error_debug(&err), "\n"); + api_error_free(&err); + } + api_counter_rename(c, str("d")); + print("name ", api_counter_name(c), "\n"); + api_counter *copy = api_counter_clone(c); + api_counter_add(copy, 1, NULL, NULL); + printf("clone %llu original %llu\n", (unsigned long long)api_counter_get(copy), + (unsigned long long)api_counter_get(c)); + api_counter_free(copy); + print("debug ", api_counter_debug(c), "\n"); + api_label label = api_counter_into_label(c, (api_option_point){.some = true, .value = p}); + api_counter_free(c); + print("label ", api_label_debug(&label), "\n"); + api_label_free(&label); + + print("", api_greet(str("x"), API_SHAPE_SQUARE), "\n"); + printf("len %zu\n", api_len(str("abc"))); + api_event events[3] = { + {.tag = API_EVENT_MOVED, .moved = {._0 = p}}, + {.tag = API_EVENT_NAMED, .named = {.name = str("n")}}, + {.tag = API_EVENT_DONE}, + }; + for (int i = 0; i < 3; i++) { + print("", api_describe(events[i]), "\n"); + } + + api_channel *channel = api_channel_new(); + api_waker waker = {.wake = wake, .drop = drop, .data = NULL}; + api_channel_recv_future *recv = api_channel_recv(channel); + api_buf payload; + printf("recv pending %s\n", api_channel_recv_poll(recv, waker, &payload) == API_POLL_PENDING ? "true" : "false"); + api_channel_send(channel, str("hi")); + printf("woken %d\n", wakes); + if (api_channel_recv_poll(recv, waker, &payload) == API_POLL_READY) { + print("recv ", payload, "\n"); + } + api_channel_recv_future_free(recv); + api_channel_send(channel, str("")); + api_channel_recv_nonempty_future *nonempty = api_channel_recv_nonempty(channel); + switch (api_channel_recv_nonempty_poll(nonempty, waker, &payload, &err)) { + case API_POLL_READY: + printf("nonempty %zu\n", payload.len); + api_buf_free(payload); + break; + case API_POLL_ERROR: + print("nonempty err ", api_error_to_string(&err), "\n"); + api_error_free(&err); + break; + default: + printf("nonempty pending\n"); + } + api_channel_recv_nonempty_future_free(nonempty); + api_channel_free(channel); + /* Each future dropped its waker once it finished. */ + return drops == 2 ? 0 : 1; +} + +/* Each breaks a contract, which must abort with a message naming the function. */ +static int broken(const char *which) { + if (strcmp(which, "moved") == 0) { + api_counter *c = api_counter_new(str("c"), 0); + api_label label = api_counter_into_label(c, (api_option_point){0}); + api_label_free(&label); + api_counter_get(c); + } else if (strcmp(which, "borrowed") == 0) { + api_channel *channel = api_channel_new(); + api_channel_recv_future *recv = api_channel_recv(channel); + (void)recv; + api_channel_clear(channel); + } else if (strcmp(which, "utf8") == 0) { + api_buf bad = {.ptr = (const uint8_t *)"\xff", .len = 1}; + api_greet(bad, API_SHAPE_CIRCLE); + } else if (strcmp(which, "finished") == 0) { + api_channel *channel = api_channel_new(); + api_channel_send(channel, str("x")); + api_channel_recv_future *recv = api_channel_recv(channel); + api_waker waker = {0}; + api_buf payload; + api_channel_recv_poll(recv, waker, &payload); + api_buf_free(payload); + api_channel_recv_poll(recv, waker, &payload); + } else if (strcmp(which, "enum") == 0) { + api_greet(str("x"), (api_shape)2); + } + return 0; +} + +int main(int argc, char **argv) { + if (argc > 1) { + return broken(argv[1]); + } + return script(); +} diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs new file mode 100644 index 000000000..8eb948e64 --- /dev/null +++ b/ffi/tests/fixtures.rs @@ -0,0 +1,130 @@ +//! 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. +//! The reject fixture's export must fail at each item it cannot export. + +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; + +fn manifest_dir() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) +} + +fn scratch() -> PathBuf { + PathBuf::from(env!("CARGO_TARGET_TMPDIR")) +} + +fn cargo() -> Command { + Command::new(std::env::var_os("CARGO").unwrap_or_else(|| "cargo".into())) +} + +fn run(cmd: &mut Command) -> Output { + let output = cmd.output().unwrap_or_else(|err| panic!("running {cmd:?}: {err}")); + assert!( + output.status.success(), + "{cmd:?} failed:\n{}{}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + output +} + +/// Export the fixture `name` into `out`, returning what the exporter printed. +fn export(name: &str, out: &Path) -> Output { + let fixture = manifest_dir().join("fixtures").join(name); + Command::new(env!("CARGO_BIN_EXE_rust2-ffi")) + .arg("--config") + .arg(fixture.join("ffi.toml")) + .arg("--out") + .arg(out) + .env("CARGO_TARGET_DIR", scratch().join(name).join("build")) + .output() + .expect("running rust2-ffi") +} + +#[test] +fn api() { + let out = scratch().join("api").join("out"); + let output = export("api", &out); + assert!( + output.status.success(), + "exporting failed:\n{}", + String::from_utf8_lossy(&output.stderr) + ); + // The workspace's lockfile pins what the export depends on. + std::fs::copy(manifest_dir().join("Cargo.lock"), out.join("Cargo.lock")).unwrap(); + let target = scratch().join("api").join("glue"); + run(cargo() + .arg("build") + .arg("--quiet") + .arg("--manifest-path") + .arg(out.join("Cargo.toml")) + .arg("--target-dir") + .arg(&target)); + + let exe = scratch().join("api").join("api-test"); + let cc = std::env::var_os("CC").unwrap_or_else(|| "cc".into()); + run(Command::new(cc) + .args(["-std=c11", "-pedantic", "-Wall", "-Wextra", "-Werror", "-I"]) + .arg(out.join("include")) + .arg(manifest_dir().join("tests").join("api.c")) + .arg(target.join("debug").join("libapi.a")) + .args(["-lpthread", "-ldl", "-lm", "-o"]) + .arg(&exe)); + + let c = run(&mut Command::new(&exe)); + let native = run(cargo() + .args(["run", "--quiet", "--locked", "--package", "api-fixture", "--example", "transcript"]) + .current_dir(manifest_dir())); + assert_eq!( + String::from_utf8_lossy(&c.stdout), + String::from_utf8_lossy(&native.stdout), + "the C transcript differs from the native one" + ); + + // 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"), + ("borrowed", "api_channel_clear: a handle is already borrowed"), + ("utf8", "api_greet: a string is not UTF-8"), + ("finished", "api_channel_recv_poll: a future is polled after it finished"), + ("enum", "api_greet: an enum value is invalid"), + ] { + let output = Command::new(&exe).arg(case).output().unwrap(); + assert!(!output.status.success(), "{case} did not abort"); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(stderr.contains(message), "{case} printed {stderr}"); + } +} + +#[test] +fn reject() { + let out = scratch().join("reject").join("out"); + let output = export("reject", &out); + assert!(!output.status.success(), "exporting reject succeeded"); + let stderr = String::from_utf8_lossy(&output.stderr); + // Each error, at its span. + let lines: Vec<&str> = stderr.lines().collect(); + let mut errors: Vec = lines + .iter() + .enumerate() + .filter(|(_, line)| line.starts_with("error: rust2-ffi:")) + .map(|(i, line)| { + let at = lines[i + 1..] + .iter() + .find_map(|l| l.trim_start().strip_prefix("--> ")) + .unwrap_or("no span"); + format!("{at}: {}", &line["error: ".len()..]) + }) + .collect(); + errors.sort(); + let expected = std::fs::read_to_string(manifest_dir().join("fixtures/reject/expected.txt")).unwrap(); + if std::env::var_os("UPDATE_EXPECT").is_some() { + std::fs::write( + manifest_dir().join("fixtures/reject/expected.txt"), + errors.join("\n") + "\n", + ) + .unwrap(); + return; + } + assert_eq!(errors.join("\n") + "\n", expected); +} From dab35ed4725b582cf20bfa39b9809f24ba75aefe Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:15:05 -0700 Subject: [PATCH 05/16] wip(ffi): export moq-net and drive it from C Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/moq/ffi.toml | 185 +++++++++++++++++++++++++++++++++++++++++++++ ffi/moq/moq.c | 127 +++++++++++++++++++++++++++++++ ffi/src/abi.rs | 29 ++++++- ffi/src/census.rs | 11 +++ ffi/src/collect.rs | 76 +++++++++++++++++-- ffi/src/config.rs | 5 ++ ffi/src/driver.rs | 13 +++- ffi/src/glue.rs | 20 ++++- ffi/src/ir.rs | 6 ++ 9 files changed, 453 insertions(+), 19 deletions(-) create mode 100644 ffi/moq/moq.c diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index 0bf5faebe..a64f5eece 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -1,2 +1,187 @@ package = "moq-net" prefix = "moq" +# What the export refuses at the pinned revision, as `just ffi census` lists it: the API +# a hand-written wrapper still has to cover. +exclude = [ + "ALPNS", + "AsPath", + "Client::connect", + "Client::with_publisher", + "Consume", + "Driver::poll", + "Epoch::time", + "Error::from_transport", + "Hops::as_slice", + "Hops::iter", + "IntoBytes", + "InvalidPattern", + "Path", + "Pattern", + "Patterns", + "Server::accept", + "Server::accept_request", + "Server::with_publisher", + "Timed", + "Timestamp::as_micros", + "Timestamp::as_millis", + "Timestamp::as_nanos", + "Timestamp::as_scale", + "Version::names", + "Versions::alpns", + "Versions::iter", + "announce::Announce::captures", + "announce::Announce::prefix", + "announce::Announce::route", + "announce::Consumer::absolute", + "announce::Consumer::poll_next", + "announce::Consumer::poll_synced", + "announce::Consumer::root", + "announce::Follow::poll_next", + "announce::Follow::poll_synced", + "auth::Grant::expires", + "auth::Grant::publish", + "auth::Grant::subscribe", + "auth::Requests::poll_next", + "auth::Watch::poll_changed", + "bandwidth::Consumer::poll_changed", + "bandwidth::Producer::poll_unused", + "bandwidth::Producer::poll_used", + "broadcast::Consumer::info", + "broadcast::Consumer::poll_closed", + "broadcast::Demand::poll_unused", + "broadcast::Demand::poll_used", + "broadcast::Dynamic::info", + "broadcast::Dynamic::poll_closed", + "broadcast::Dynamic::poll_requested_track", + "broadcast::Finish::poll_closed", + "broadcast::Info::path", + "broadcast::Info::pool", + "broadcast::Lister::poll_unused", + "broadcast::Lister::poll_used", + "broadcast::Producer::info", + "broadcast::Tracks::broadcast", + "broadcast::Tracks::poll_next", + "bytes", + "cache::DEFAULT_EXPIRY", + "cache::Pool::gc", + "frame::Buffer", + "frame::Consumer::poll_read_all", + "frame::Consumer::poll_read_chunk", + "frame::Frame::arrived", + "frame::Producer::group", + "goaway::Consumer::poll", + "group::Consumer::poll_finished", + "group::Consumer::poll_next_frame", + "group::Consumer::poll_read_frame", + "group::Consumer::poll_read_frames", + "group::Consumer::read_frames", + "group::Consumer::set_frames", + "group::Demand::poll_unused", + "group::Demand::poll_used", + "group::Producer::poll_closed", + "group::Producer::write_frames", + "kio", + "origin::AnnouncedBroadcast::poll_available", + "origin::Config::pool", + "origin::Consumer::absolute", + "origin::Consumer::allowed", + "origin::Consumer::root", + "origin::Consumer::scope", + "origin::DEFAULT_UPDATE_HOLD", + "origin::Driver::poll", + "origin::Dynamic::poll_requested_broadcast", + "origin::Prepared::broadcast", + "origin::Producer::absolute", + "origin::Producer::allowed", + "origin::Producer::new", + "origin::Producer::root", + "origin::Producer::scope", + "origin::Request::path", + "origin::Requesting::poll_ok", + "origin::Route::hops", + "path::Relative", + "path::Segment", + "path::Specificity", + "server::Handshake::ok", + "server::Handshake::with_publisher", + "stats::Config::exclude", + "stats::Config::with_exclude", + "stats::Handle::parent", + "stats::Handle::tier", + "stats::Registry::exclude", + "stats::Report::sessions", + "stats::Report::traffic", + "stats::SessionEntry::label", + "stats::SessionEntry::tier", + "stats::Snapshot::control", + "stats::Snapshot::sessions", + "stats::Snapshot::traffic", + "stats::Tier::label", + "stats::TrafficEntry::path", + "stats::TrafficEntry::tier", + "time::Driver", + "time::Instant", + "time::now", + "time::run", + "track::Consumer::broadcast", + "track::Consumer::poll_largest", + "track::Demand::poll_wanted_changed", + "track::Dynamic::poll_requested_group", + "track::Ordered::broadcast", + "track::Ordered::info", + "track::Ordered::poll_finished", + "track::Ordered::poll_largest", + "track::Ordered::poll_next_group", + "track::Ordered::poll_recv_datagram", + "track::Ordered::set_groups", + "track::Position::group_end", + "track::Producer::broadcast", + "track::Producer::drop_groups", + "track::Producer::info", + "track::Producer::poll_closed", + "track::Producer::poll_subscription_changed", + "track::Querying::poll_ok", + "track::Range::groups", + "track::Request::poll_subscription_changed", + "track::Subscriber::broadcast", + "track::Subscriber::info", + "track::Subscriber::poll_finished", + "track::Subscriber::poll_largest", + "track::Subscriber::poll_recv_datagram", + "track::Subscriber::poll_recv_group", + "track::Subscriber::set_groups", + "track::Subscribing::poll_ok", + "track::Subscription::ranges", + "track::Subscription::with_groups", + "track::Subscription::with_ranges", + "transport::Error", + "transport::memory::pair", + "transport::poll::AcceptBi", + "transport::poll::AcceptUni", + "transport::poll::Boxable", + "transport::poll::Buffered", + "transport::poll::BufferedLease", + "transport::poll::Chunks", + "transport::poll::Lease", + "transport::poll::OpenBi", + "transport::poll::OpenUni", + "transport::poll::ReadChunk", + "transport::poll::RecvDatagram", + "transport::poll::RecvStream", + "transport::poll::SendClosed", + "transport::poll::SendGroup", + "transport::poll::SendOptions", + "transport::poll::SendStream", + "transport::poll::Session", + "transport::poll::SessionClosed", + "transport::poll::Ungrouped", + "transport::poll::Write", + "transport::poll::WriteBuf", + "transport::poll::WriteChunk", + "varint::decode_quic", + "varint::encode_quic", +] + +[rename] +# The rule makes both this type and `Session::stats` `moq_session_stats`. +"session::Stats" = "session_stats_snapshot" diff --git a/ffi/moq/moq.c b/ffi/moq/moq.c new file mode 100644 index 000000000..f5015600f --- /dev/null +++ b/ffi/moq/moq.c @@ -0,0 +1,127 @@ +/* moq-net's exported C API against the real library: a broadcast's track, published + * and subscribed to in one process, with every read polled as a future. + * + * 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.h" + +static int failures = 0; + +#define CHECK(cond) \ + do { \ + if (!(cond)) { \ + fprintf(stderr, "%s:%d: %s\n", __FILE__, __LINE__, #cond); \ + failures++; \ + } \ + } while (0) + +static moq_buf str(const char *s) { + return (moq_buf){.ptr = (const uint8_t *)s, .len = strlen(s)}; +} + +/* Whether a returned buffer holds `s`, freeing it. */ +static int is(moq_buf buf, const char *s) { + int same = buf.len == strlen(s) && memcmp(buf.ptr, s, buf.len) == 0; + if (!same) { + fprintf(stderr, "got \"%.*s\", want \"%s\"\n", (int)buf.len, (const char *)buf.ptr, s); + } + moq_buf_free(buf); + return same; +} + +static int wakes = 0; + +static void wake(void *data) { + (void)data; + wakes++; +} + +int main(void) { + moq_waker waker = {.wake = wake}; + moq_error *err = NULL; + + moq_broadcast_info *info = moq_broadcast_info_new(); + moq_broadcast_producer *broadcast = moq_broadcast_info_produce(info); + moq_broadcast_info_free(info); + + moq_track_producer *track = NULL; + CHECK(moq_broadcast_producer_create_track(broadcast, str("video"), NULL, &track, &err)); + CHECK(is(moq_track_producer_name(track), "video")); + + /* A second track of the same name is an error, printed as Rust prints it. */ + moq_track_producer *duplicate = NULL; + CHECK(!moq_broadcast_producer_create_track(broadcast, str("video"), NULL, &duplicate, &err)); + CHECK(err != NULL && is(moq_error_to_string(err), "duplicate")); + moq_error_free(err); + + 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; + CHECK(moq_track_consumer_subscribe_poll(subscribing, waker, &subscriber, &err) == MOQ_POLL_READY); + moq_track_consumer_subscribe_future_free(subscribing); + + /* A group's arrival wakes the subscriber's pending receive. */ + moq_track_subscriber_recv_group_future *receiving = moq_track_subscriber_recv_group(subscriber); + moq_group_consumer *group = NULL; + CHECK(moq_track_subscriber_recv_group_poll(receiving, waker, &group, &err) == MOQ_POLL_PENDING); + moq_group_producer *writer = NULL; + CHECK(moq_track_producer_append_group(track, &writer, &err)); + CHECK(wakes == 1); + CHECK(moq_track_subscriber_recv_group_poll(receiving, waker, &group, &err) == MOQ_POLL_READY); + moq_track_subscriber_recv_group_future_free(receiving); + CHECK(group != NULL && moq_group_consumer_index(group) == 0); + + /* So does a frame's. */ + moq_group_consumer_read_frame_future *reading = moq_group_consumer_read_frame(group); + moq_frame_frame *frame = NULL; + CHECK(moq_group_consumer_read_frame_poll(reading, waker, &frame, &err) == MOQ_POLL_PENDING); + CHECK(moq_group_producer_write_frame(writer, NULL, str("hello"), &err)); + CHECK(wakes == 2); + CHECK(moq_group_consumer_read_frame_poll(reading, waker, &frame, &err) == MOQ_POLL_READY); + moq_group_consumer_read_frame_future_free(reading); + CHECK(frame != NULL && is(moq_frame_frame_payload(frame), "hello")); + CHECK(moq_frame_frame_timestamp(frame) == NULL); + moq_frame_frame_free(frame); + + /* A timestamp is a `Copy` value behind a handle: passing it copies it out. The track + * is untimed, so a timestamped frame is refused. */ + moq_timestamp *at = NULL; + moq_time_overflow *overflow = NULL; + CHECK(moq_timestamp_from_millis(1500, &at, &overflow)); + CHECK(moq_timestamp_as_secs(at) == 1); + CHECK(!moq_group_producer_write_frame(writer, at, str("late"), &err)); + CHECK(err != NULL && is(moq_error_to_string(err), "frame timestamp doesn't fit its track")); + moq_error_free(err); + CHECK(moq_timestamp_as_secs(at) == 1); + + /* The last frame, then the group's end, which reads as None. */ + CHECK(moq_group_producer_write_frame(writer, NULL, str("world"), &err)); + CHECK(moq_group_producer_finish(writer, &err)); + reading = moq_group_consumer_read_frame(group); + CHECK(moq_group_consumer_read_frame_poll(reading, waker, &frame, &err) == MOQ_POLL_READY); + moq_group_consumer_read_frame_future_free(reading); + CHECK(frame != NULL && is(moq_frame_frame_payload(frame), "world")); + moq_frame_frame_free(frame); + reading = moq_group_consumer_read_frame(group); + frame = (moq_frame_frame *)1; + CHECK(moq_group_consumer_read_frame_poll(reading, waker, &frame, &err) == MOQ_POLL_READY); + CHECK(frame == NULL); + moq_group_consumer_read_frame_future_free(reading); + + moq_timestamp_free(at); + moq_group_consumer_free(group); + moq_group_producer_free(writer); + moq_track_subscriber_free(subscriber); + moq_track_consumer_free(consumer); + moq_track_producer_free(track); + moq_broadcast_producer_free(broadcast); + + if (failures == 0) { + printf("ok\n"); + } + return failures != 0; +} diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 4d4c83184..14f07cc3d 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -66,6 +66,8 @@ pub struct Export { pub struct Abi<'a> { pub api: &'a Api, pub prefix: String, + /// C names for paths, in place of the rule's: an item's, and its methods' through it. + rename: &'a BTreeMap, /// Each `Option` struct by C name, with `T`. pub options: BTreeMap, /// Every C name claimed, with what claimed it. @@ -75,10 +77,11 @@ pub struct Abi<'a> { } impl<'a> Abi<'a> { - pub fn new(api: &'a Api, prefix: &str) -> Self { + pub fn new(api: &'a Api, prefix: &str, rename: &'a BTreeMap) -> Self { let mut abi = Self { api, prefix: prefix.to_string(), + rename, options: BTreeMap::new(), names: HashMap::new(), clashes: Vec::new(), @@ -90,7 +93,16 @@ impl<'a> Abi<'a> { /// The C name for a path from the crate root. pub fn name(&self, path: &[String]) -> String { let mut name = self.prefix.clone(); - for segment in path { + let mut rest = path; + for len in (1..=path.len()).rev() { + if let Some(renamed) = self.rename.get(&path[..len].join("::")) { + name.push('_'); + name.push_str(renamed); + rest = &path[len..]; + break; + } + } + for segment in rest { name.push('_'); name.push_str(&snake(segment)); } @@ -198,7 +210,8 @@ impl<'a> Abi<'a> { let ty = match owner { Ty::Handle { name, .. } => Ty::Handle { name: name.clone(), - constant: receiver == Receiver::Ref, + constant: receiver == Receiver::Ref + || (receiver == Receiver::Owned && self.api.objects.iter().any(|o| o.copy && &self.name(&o.path) == name)), }, // A value's receiver is read through a pointer, and never changed. value => Ty::In(Box::new(value.clone())), @@ -206,7 +219,15 @@ impl<'a> Abi<'a> { params.push(("self".to_string(), ty)); } for param in &function.params { - params.push((escape(¶m.name), self.ty(¶m.ty))); + let ty = match ¶m.ty { + // Taken by value, a `Copy` value is copied out, leaving its handle as it was. + Type::Object(i) if self.api.objects[*i].copy => Ty::Handle { + name: self.object(*i), + constant: true, + }, + ty => self.ty(ty), + }; + params.push((escape(¶m.name), ty)); } let mut outs = Vec::new(); if function.ok != Type::Unit { diff --git a/ffi/src/census.rs b/ffi/src/census.rs index 25f6e6ab4..7d989028d 100644 --- a/ffi/src/census.rs +++ b/ffi/src/census.rs @@ -116,6 +116,17 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn ); } + if !collected.refusals.is_empty() { + let _ = writeln!(out, "\n## The config that exports what maps\n"); + let _ = writeln!(out, "```toml\nexclude = ["); + let mut paths: Vec<&str> = collected.refusals.iter().map(|r| r.path.as_str()).collect(); + paths.sort(); + paths.dedup(); + for path in paths { + let _ = writeln!(out, " \"{path}\","); + } + let _ = writeln!(out, "]\n```"); + } if !clashes.is_empty() { let _ = writeln!(out, "\n## C names claimed twice\n"); for (name, (first, _), (second, span)) in clashes { diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 161ef566e..57d1969d9 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -87,8 +87,8 @@ struct Collector<'a, 'tcx> { api: Api, } -/// Collect the crate's exported API. -pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config) -> Collected { +/// Collect the crate's exported API, leaving out what `exclude` names. +pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> Collected { let bytes = tcx .crates(()) .iter() @@ -106,7 +106,7 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config) -> Collected { decls: Default::default(), refusals: Vec::new(), hidden: Vec::new(), - excluded: config.exclude.iter().map(|path| (path.clone(), 0)).collect(), + excluded: exclude.iter().map(|path| (path.clone(), 0)).collect(), aliases: Vec::new(), left_out: Default::default(), opaque: Vec::new(), @@ -245,6 +245,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { false => self.object(def_id), } } + DefKind::Enum if tcx.adt_def(def_id).variants().is_empty() => Decl::Refused(why("enum without variants", "")), DefKind::Enum => Decl::Enum(0), DefKind::Trait => Decl::Callback(0), _ => continue, @@ -285,10 +286,12 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { Decl::Object(i) => { *i = api.objects.len(); let sync = implements(tcx, def_id, sym::Sync); + let copy = implements(tcx, def_id, sym::Copy); api.objects.push(Object { path, span, sync, + copy, methods: Vec::new(), traits: Traits::default(), }); @@ -414,7 +417,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { e.traits = traits; } Some(Decl::Object(index)) => { - let (methods, traits) = self.methods(def_id, &path); + let (mut methods, traits) = self.methods(def_id, &path); + if kind == DefKind::Struct { + methods.splice(0..0, self.getters(def_id, &path)); + } let object = &mut self.api.objects[index]; object.methods = methods; object.traits = traits; @@ -442,6 +448,40 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { } } + /// A getter for each `pub` field of a struct exported as an object, returning a copy. + fn getters(&mut self, def_id: DefId, path: &[String]) -> Vec { + let tcx = self.tcx; + let identity = ty::GenericArgs::identity_for_item(tcx, def_id); + let mut getters = Vec::new(); + for field in &tcx.adt_def(def_id).non_enum_variant().fields { + if !field.vis.is_public() { + continue; + } + let mut getter = path.to_vec(); + getter.push(field.name.to_string()); + if self.exclude(&getter) { + continue; + } + let span = tcx.def_span(field.did); + let ty = field.ty(tcx, identity).skip_norm_wip(); + // Read through `&self`, so returned as a copy, as a borrowed return is. + match self.ty(Ty::new_imm_ref(tcx, tcx.lifetimes.re_erased, ty), Pos::Return) { + Ok(ty) => getters.push(Function { + path: getter, + span, + receiver: Some(Receiver::Ref), + params: Vec::new(), + ok: ty, + err: None, + future: false, + field: true, + }), + Err(why) => self.refuse(&getter, "field", span, vec![why]), + } + } + getters + } + /// A type's inherent `pub` methods, and the std traits it implements. fn methods(&mut self, def_id: DefId, path: &[String]) -> (Vec, Traits) { let tcx = self.tcx; @@ -619,6 +659,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { ok, err, future, + field: false, }), _ => Err(errs), } @@ -711,7 +752,8 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let obligation = Obligation::new(tcx, ObligationCause::dummy(), param_env, clause); infcx.predicate_must_hold_modulo_regions(&obligation) }); - if holds { + // `impl Into>` takes a `String` too, which maps where `Arc` does not. + if holds && self.ty(candidate, Pos::Param).is_ok() { return Ok(candidate); } } @@ -808,7 +850,11 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { }; match (&inner_ty, pos, mutability) { // Returned as a copy: plain data reads the same either way. - (Type::Object(_), Pos::Return, _) => return Err(why("borrowed object return", inner.to_string())), + // Returned as a copy: plain data reads the same either way, and so does a + // `Copy` handle's value. + (Type::Object(_), Pos::Return, _) if !tcx.type_is_copy_modulo_regions(TypingEnv::fully_monomorphized(), *inner) => { + return Err(why("borrowed object return", inner.to_string())); + } (_, Pos::Field, _) => return Err(why("reference field", inner.to_string())), (Type::Object(_), Pos::Param, _) => {} (_, Pos::Param, Mutability::Mut) => return Err(why("&mut of a value", inner.to_string())), @@ -830,7 +876,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { } else if tcx.is_diagnostic_item(rustc_span::Symbol::intern("Duration"), did) { Type::Duration } else if tcx.is_diagnostic_item(sym::Option, did) { - let inner = self.ty(args.type_at(0), Pos::Behind)?; + let inner = self.ty(args.type_at(0), pos.inner())?; if matches!(inner, Type::Option(_)) { return Err(why("nested Option", ty.to_string())); } @@ -843,7 +889,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { ty::Dynamic(preds, ..) => { return self.dynamic(preds.principal_def_id(), Dyn::Box, inner); } - _ => Type::Box(Box::new(self.ty(inner, Pos::Behind)?)), + _ => Type::Box(Box::new(self.ty(inner, pos.inner())?)), } } else if tcx.is_diagnostic_item(sym::Arc, did) { let inner = args.type_at(0); @@ -859,6 +905,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { match self.decls.get(&did) { Some(Decl::Record(i)) => Type::Record(*i), Some(Decl::Enum(i)) => Type::Enum(*i), + // A value holds only values, and handles it can copy. + Some(Decl::Object(_)) if pos == Pos::Field && !implements(tcx, did, sym::Copy) => { + return Err(why("object in a value", tcx.def_path_str(did))); + } Some(Decl::Object(i)) => Type::Object(*i), Some(Decl::Refused(_)) => return Err(why("refused type", tcx.def_path_str(did))), Some(Decl::Callback(_)) | None => { @@ -903,6 +953,16 @@ enum Pos { Behind, } +impl Pos { + /// The position of a type inside an `Option` or `Box` here: a field's stays a field's. + fn inner(self) -> Pos { + match self { + Pos::Field => Pos::Field, + _ => Pos::Behind, + } + } +} + fn int(ty: Ty<'_>) -> Option { Some(match ty.kind() { ty::Uint(ty::UintTy::U8) => Int::U8, diff --git a/ffi/src/config.rs b/ffi/src/config.rs index 890857311..031f17f9d 100644 --- a/ffi/src/config.rs +++ b/ffi/src/config.rs @@ -16,6 +16,11 @@ pub struct Config { /// method (`track::Producer::poll_closed`). Each must name something exported. #[serde(default)] pub exclude: Vec, + /// C names, without the prefix, for paths from the crate root whose names the rule + /// makes clash: `"session::Stats" = "session_stats_snapshot"`. A type's methods are + /// named through its new name. + #[serde(default)] + pub rename: std::collections::BTreeMap, } impl Config { diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index 885341f86..8e65decd6 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -80,10 +80,15 @@ impl Callbacks for Export { if tcx.dcx().has_errors().is_some() { return Compilation::Stop; } - let collected = collect::collect(tcx, &self.config); + // A census counts the whole API, whatever the config leaves out. + let exclude = match self.output { + Output::Census(_) => &[][..], + Output::Dir(_) => &self.config.exclude[..], + }; + let collected = collect::collect(tcx, &self.config, exclude); let written = match &self.output { Output::Census(path) => { - let abi = Abi::new(&collected.api, &self.config.prefix()); + let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); let text = census::render(&self.config.package, &collected, &abi.clashes, &|span| at(tcx, span)); write(path, &text) } @@ -112,7 +117,7 @@ impl Callbacks for Export { tcx.dcx().err(format!("rust2-ffi: exclude `{path}` names nothing exported")); } } - let abi = Abi::new(&collected.api, &self.config.prefix()); + let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); for (name, (first, first_span), (second, second_span)) in &abi.clashes { tcx.dcx() .struct_span_err( @@ -120,7 +125,7 @@ impl Callbacks for Export { format!("rust2-ffi: {second} and {first} are both `{name}` in C"), ) .with_span_note(*first_span, format!("{first} is here")) - .with_help("exclude one in the config") + .with_help("rename or exclude one in the config") .emit(); } if tcx.dcx().has_errors().is_some() { diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 7cfe8d1d0..84aa399ba 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -138,7 +138,10 @@ impl Gen<'_> { true => format!("lift_{}({e}, w)", self.abi.enumeration(*i)), false => format!("lift_{}(&{e}, w)", self.abi.enumeration(*i)), }, - Type::Object(i) => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), + Type::Object(i) => match self.abi.api.objects[*i].copy { + true => format!("*unsafe {{ rt::Object::<{}>::borrow({e}, w) }}", self.object_path(*i)), + false => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), + }, Type::Callback(i, form) => abi::dyn_wrap(*form, &format!("Foreign_{}({e})", self.abi.callback(*i))), } } @@ -172,6 +175,7 @@ impl Gen<'_> { Type::Box(inner) => self.lower(inner, &format!("*{e}")), Type::Ref(_, inner) => match &**inner { Type::Str | Type::Slice => self.lower(inner, e), + Type::Object(_) => format!("rt::Object::new(*{e})"), inner => self.lower(inner, &format!("::std::clone::Clone::clone({e})")), }, Type::Record(i) => format!("lower_{}({e})", self.abi.record(*i)), @@ -187,11 +191,14 @@ impl Gen<'_> { _ if Abi::is_buf(ty) => Some(format!("unsafe {{ {e}.free() }};")), Type::Option(inner) => match inner.base() { base if Abi::is_buf(base) => Some(format!("unsafe {{ {e}.free() }};")), + // A null handle frees nothing. + Type::Object(_) => self.free(inner, e), _ => self .free(inner, &format!("{e}.value")) .map(|free| format!("if {e}.some {{ {free} }}")), }, Type::Box(inner) => self.free(inner, e), + Type::Object(i) => Some(format!("unsafe {{ rt::Object::<{}>::free({e}) }};", self.object_path(*i))), Type::Record(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.record(*i))), Type::Enum(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.enumeration(*i))), _ => None, @@ -202,6 +209,7 @@ impl Gen<'_> { fn owns(&self, ty: &Type) -> bool { match ty { _ if Abi::is_buf(ty) => true, + Type::Object(_) => true, Type::Option(inner) | Type::Box(inner) => self.owns(inner), Type::Record(i) => self.abi.api.records[*i].fields.iter().any(|f| self.owns(&f.ty)), Type::Enum(i) => self.abi.api.enums[*i] @@ -622,7 +630,10 @@ impl Gen<'_> { Type::Unit => "result".to_string(), _ => self.lower(&function.ok, "result"), }, - None => format!("let v = result;\n\t{write_ok}\n\t{ready}"), + None => match function.ok { + Type::Unit => format!("let _ = result;\n\t{ready}"), + _ => format!("let v = result;\n\t{write_ok}\n\t{ready}"), + }, Some(err) => format!( "match result {{\n\t\tOk(v) => {{\n\t\t\tlet _ = &v;\n\t\t\t{write_ok}\n\t\t\t{ready}\n\t\t}}\n\t\tErr(e) => {{\n\t\t\tunsafe {{ rt::write::<{}>(err.cast(), || {}) }};\n\t\t\t{error}\n\t\t}}\n\t}}", self.rs(&self.abi.ty(err)), @@ -679,7 +690,10 @@ impl Gen<'_> { } None => self.path(&function.path), }; - let call = format!("{callee}({})", args.join(", ")); + let call = match function.field { + true => format!("&({}).{}", args[0], function.name()), + false => format!("{callee}({})", args.join(", ")), + }; let body = stmts.join("\n\t"); if let Some((_, poll, free)) = &export.future { self.line(format!( diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index c1aeda617..7ff4c109b 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -72,6 +72,9 @@ pub struct Object { pub span: Span, /// Whether it is `Sync`: if not, even its `&self` methods borrow it exclusively. pub sync: bool, + /// Whether it is `Copy`: taken by value, it is copied out of its handle, as Rust + /// copies it, rather than moved out. + pub copy: bool, pub methods: Vec, pub traits: Traits, } @@ -107,6 +110,9 @@ pub struct Function { pub err: Option, /// Whether it returns a future: an `async fn`, or a value that implements `Future`. pub future: bool, + /// Whether it reads a `pub` field of its receiver, named as the function is, rather + /// than calling a method. + pub field: bool, } impl Function { From bacb0beddf6b3277248e51484dbaa34d60211643 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:18:44 -0700 Subject: [PATCH 06/16] wip(ffi): callback interfaces, Copy handles, and field getters Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/fixtures/api/examples/transcript.rs | 33 ++++++++- ffi/fixtures/api/src/lib.rs | 72 +++++++++++++++++++ ffi/src/abi.rs | 16 +++-- ffi/src/c.rs | 17 +++++ ffi/src/collect.rs | 93 ++++++++++++++++++++---- ffi/src/glue.rs | 96 ++++++++++++++++++++++++- ffi/tests/api.c | 37 ++++++++++ 7 files changed, 344 insertions(+), 20 deletions(-) diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index a5880dcbf..f1551051a 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -7,9 +7,25 @@ use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use std::task::{Context, Poll, Wake, Waker}; -use api_fixture::{Channel, Counter, Event, LIMIT, Point, Shape}; +use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Point, Shape, Stamp}; use bytes::Bytes; +/// Keeps even levels, as `tests/api.c`'s implementation does. +struct Print; + +impl Log for Print { + fn log(&self, level: u8, line: &str) -> bool { + println!("log {level} {line}"); + level % 2 == 0 + } +} + +impl Drop for Print { + fn drop(&mut self) { + println!("freed"); + } +} + struct Count(AtomicUsize); impl Wake for Count { @@ -62,6 +78,21 @@ fn main() { println!("{}", api_fixture::describe(&event)); } + let stamp = Stamp::from_millis(2500); + println!("secs {}", stamp.secs()); + println!("later {}", Stamp::from_millis(3000).later(stamp)); + println!("secs {}", stamp.secs()); + let message = Message::new(Some(stamp), Bytes::from_static(b"body")); + println!("payload {}", String::from_utf8_lossy(&message.payload)); + println!("stamp {:?}", message.stamp.unwrap()); + println!("sent {}", message.sent()); + + println!("kept {}", api_fixture::emit(Print, vec![1, 2, 3, 4])); + let logger = Logger::new(Box::new(Print)); + println!("write {}", logger.write("hi")); + drop(logger); + println!("dropped"); + let channel = Channel::new(); let count = Arc::new(Count(AtomicUsize::new(0))); let waker = Waker::from(count.clone()); diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index b44ae1959..23b3558c8 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -172,6 +172,78 @@ impl Channel { } } +/// 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)] +pub struct Stamp { + millis: u64, +} + +impl Stamp { + pub fn from_millis(millis: u64) -> Self { + Self { millis } + } + + pub fn secs(self) -> u64 { + self.millis / 1000 + } + + pub fn later(self, other: Stamp) -> bool { + self.millis > other.millis + } +} + +/// A message: an object, since one field is private, whose `pub` fields read as getters. +#[derive(Clone, Debug)] +pub struct Message { + pub stamp: Option, + pub payload: Bytes, + sent: bool, +} + +impl Message { + pub fn new(stamp: Option, payload: Bytes) -> Self { + Self { + stamp, + payload, + sent: false, + } + } + + pub fn sent(&self) -> bool { + self.sent + } +} + +/// A sink: a callback interface, implemented in C. +pub trait Log: Send + Sync { + /// Whether the line was kept. + fn log(&self, level: u8, line: &str) -> bool; +} + +/// Each line to `log` as a type parameter takes it, returning how many it kept. +pub fn emit(log: impl Log, lines: Vec) -> u32 { + lines + .iter() + .filter(|&&n| log.log(n, &format!("line {n}"))) + .count() as u32 +} + +/// Holds a foreign implementation as a trait object, dropping it with itself. +pub struct Logger { + sink: Box, +} + +impl Logger { + pub fn new(sink: Box) -> Self { + Self { sink } + } + + pub fn write(&self, line: &str) -> bool { + self.sink.log(0, line) + } +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index 14f07cc3d..b01aefbf9 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -219,13 +219,21 @@ impl<'a> Abi<'a> { params.push(("self".to_string(), ty)); } for param in &function.params { - let ty = match ¶m.ty { + let copied = match ¶m.ty { + Type::Object(i) => Some(*i), + Type::Option(inner) => match **inner { + Type::Object(i) => Some(i), + _ => None, + }, + _ => None, + }; + let ty = match copied { // Taken by value, a `Copy` value is copied out, leaving its handle as it was. - Type::Object(i) if self.api.objects[*i].copy => Ty::Handle { - name: self.object(*i), + Some(i) if self.api.objects[i].copy => Ty::Handle { + name: self.object(i), constant: true, }, - ty => self.ty(ty), + _ => self.ty(¶m.ty), }; params.push((escape(¶m.name), ty)); } diff --git a/ffi/src/c.rs b/ffi/src/c.rs index 8c5ef9c67..d354f6fbb 100644 --- a/ffi/src/c.rs +++ b/ffi/src/c.rs @@ -121,6 +121,23 @@ impl Header<'_> { self.value(&Ty::Struct(abi.enumeration(i))); } + for (i, callback) in api.callbacks.iter().enumerate() { + let name = abi.callback(i); + let mut table = vec!["\tvoid (*free)(void *data);".to_string()]; + for method in &callback.methods { + let params: Vec = std::iter::once("void *data".to_string()) + .chain(method.params.iter().map(|p| self.decl(&abi.ty(&p.ty), &abi::escape(&p.name)))) + .collect(); + let decl = self.decl(&abi.ty(&method.ok), &format!("(*{})({})", method.name(), params.join(", "))); + table.push(format!("\t{decl};")); + } + self.line(format!( + "/* {}: implemented in C. Rust calls free once it drops the implementation, and\n * may call the others from any thread. */\ntypedef struct {name}_vtable {{\n{}\n}} {name}_vtable;\n\ntypedef struct {name} {{\n\tconst {name}_vtable *vtable;\n\tvoid *data;\n}} {name};\n", + callback.path.join("::"), + table.join("\n") + )); + } + for constant in &api.constants { let value = match constant.value { Literal::Bool(b) => b.to_string(), diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 57d1969d9..a5b47a1c8 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -82,6 +82,9 @@ struct Collector<'a, 'tcx> { aliases: Vec, /// Local items the walk left out, and why: `excluded` or `doc(hidden)`. left_out: rustc_data_structures::fx::FxHashMap, + /// The type parameters of the function being mapped that take a foreign + /// implementation, with the callback each takes. + impls: std::cell::RefCell, usize)>>, opaque: Vec<(String, Why)>, bytes: Option, api: Api, @@ -109,6 +112,7 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> excluded: exclude.iter().map(|path| (path.clone(), 0)).collect(), aliases: Vec::new(), left_out: Default::default(), + impls: Default::default(), opaque: Vec::new(), bytes, api: Api { @@ -253,6 +257,15 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { self.decls.insert(def_id, decl); } self.settle(); + // A trait whose methods do not map is refused before any signature takes it. + for (def_id, path) in self.items.clone() { + if matches!(self.decls.get(&def_id), Some(Decl::Callback(_))) + && let Err(why) = self.callback(def_id, &path) + { + let first = why.into_iter().next().expect("a refusal has a reason"); + self.decls.insert(def_id, Decl::Refused(first)); + } + } // Number each kind in item order, with placeholders filled in by `define`. for (def_id, path) in self.items.clone() { let span = tcx.def_span(def_id); @@ -425,14 +438,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { object.methods = methods; object.traits = traits; } - Some(Decl::Callback(index)) => match self.callback(def_id, &path) { - Ok(methods) => self.api.callbacks[index].methods = methods, - Err(why) => { - // A trait refused after signatures could name it: those that do - // still compile, and the census counts this one. - self.refuse(&path, "trait", span, why); - } - }, + Some(Decl::Callback(index)) => { + self.api.callbacks[index].methods = self.callback(def_id, &path).expect("settled"); + } None => match kind { DefKind::Fn => match self.function(def_id, path.clone(), None) { Ok(function) => self.api.functions.push(function), @@ -558,6 +566,13 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { method.push(name.to_string()); match self.function(item.def_id, method, Some(self_ty)) { Ok(function) if function.future => errs.push(why("async trait method", name.to_string())), + Ok(function) + if !function.params.iter().all(|p| foreign_arg(&p.ty)) + || !foreign_return(&function.ok) + || function.err.is_some() => + { + errs.push(why("callback signature", name.to_string())) + } Ok(function) if function.receiver == Some(Receiver::Owned) || function.receiver.is_none() => { errs.push(why("trait method without &self", name.to_string())) } @@ -581,6 +596,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { fn function(&self, def_id: DefId, path: Path, self_ty: Option>) -> Result> { let tcx = self.tcx; let mut errs = Vec::new(); + self.impls.borrow_mut().clear(); let args = match self.instantiate(def_id, self_ty) { Ok(args) => args, Err(why) => return Err(why), @@ -686,6 +702,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { GenericArgKind::Const(_) => errs.push(why("const generic", "")), GenericArgKind::Type(param) => match self.choose(def_id, param) { Ok(ty) => args[i] = ty.into(), + // The parameter stays, and `ty` maps it to the foreign implementation. + Err(Why { construct: "callback bound", .. }) if let Some(callback) = self.foreign(def_id, param) => { + self.impls.borrow_mut().push((param, callback)); + } Err(why) => errs.push(why), }, } @@ -775,6 +795,30 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { } } + /// The callback a type parameter takes a foreign implementation of: one bounded by a + /// single exported trait, and otherwise only by what that implementation meets. + fn foreign(&self, def_id: DefId, param: Ty<'tcx>) -> Option { + let tcx = self.tcx; + let mut callback = None; + for clause in tcx.clauses_of(def_id).instantiate_identity(tcx).clauses { + let Some(bound) = clause.skip_norm_wip().as_trait_clause() else { + continue; + }; + if bound.self_ty().skip_binder() != param { + continue; + } + let tr = bound.def_id(); + let met = [sym::Send, sym::Sync].iter().any(|&item| tcx.is_diagnostic_item(item, tr)) + || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); + match self.decls.get(&tr) { + Some(Decl::Callback(i)) if callback.is_none() => callback = Some(*i), + _ if met => {} + _ => return None, + } + } + callback + } + /// What `ty` resolves to when awaited, if it is a future. fn future_output(&self, ty: Ty<'tcx>, env: TypingEnv<'tcx>) -> Option> { let tcx = self.tcx; @@ -887,7 +931,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let inner = args.type_at(0); match inner.kind() { ty::Dynamic(preds, ..) => { - return self.dynamic(preds.principal_def_id(), Dyn::Box, inner); + return self.dynamic(preds.principal_def_id(), Dyn::Box, inner, pos); } _ => Type::Box(Box::new(self.ty(inner, pos.inner())?)), } @@ -895,7 +939,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let inner = args.type_at(0); match inner.kind() { ty::Dynamic(preds, ..) => { - return self.dynamic(preds.principal_def_id(), Dyn::Arc, inner); + return self.dynamic(preds.principal_def_id(), Dyn::Arc, inner, pos); } _ => return Err(why("Arc", strip_args(tcx, did))), } @@ -922,8 +966,8 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { ty::Array(..) => return Err(why("array", ty.to_string())), ty::Slice(_) | ty::Str => return Err(why("unsized type", ty.to_string())), ty::Dynamic(..) => return Err(why("trait object", ty.to_string())), - ty::Param(_) => match pos { - // A callback method's `Self`. + ty::Param(_) => match self.impls.borrow().iter().find(|(param, _)| *param == ty) { + Some((_, callback)) if pos == Pos::Param => Type::Callback(*callback, Dyn::Impl), _ => return Err(why("type parameter", ty.to_string())), }, ty::Closure(..) | ty::FnDef(..) | ty::FnPtr(..) => return Err(why("function value", "")), @@ -935,9 +979,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { } /// A trait object of one of the crate's traits, as a foreign implementation. - fn dynamic(&self, principal: Option, form: Dyn, ty: Ty<'tcx>) -> Result { + /// A foreign implementation crosses only into Rust, as a parameter. + fn dynamic(&self, principal: Option, form: Dyn, ty: Ty<'tcx>, pos: Pos) -> Result { match principal.and_then(|tr| self.decls.get(&tr)) { - Some(Decl::Callback(i)) => Ok(Type::Callback(*i, form)), + Some(Decl::Callback(i)) if pos == Pos::Param => Ok(Type::Callback(*i, form)), _ => Err(why("trait object", ty.to_string())), } } @@ -953,6 +998,26 @@ enum Pos { Behind, } +/// Whether a callback can take `ty`: lent to the foreign side for the call, and +/// copied by it if kept. +fn foreign_arg(ty: &Type) -> bool { + match ty { + Type::Bool | Type::Int(_) | Type::F32 | Type::F64 | Type::Char | Type::Duration => true, + Type::String | Type::Vec | Type::Bytes => true, + Type::Ref(Mutability::Not, inner) => matches!(**inner, Type::Str | Type::Slice), + Type::Option(inner) => foreign_arg(inner), + _ => false, + } +} + +/// Whether a callback can return `ty`: a value with no memory to own. +fn foreign_return(ty: &Type) -> bool { + matches!( + ty, + Type::Unit | Type::Bool | Type::Int(_) | Type::F32 | Type::F64 | Type::Char + ) +} + impl Pos { /// The position of a type inside an `Option` or `Box` here: a field's stays a field's. fn inner(self) -> Pos { diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 84aa399ba..2508446ae 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -14,6 +14,27 @@ use crate::ir::{Function, Mutability, Receiver, Traits, Type}; const RUNTIME: &str = include_str!("../runtime/rt.rs"); +/// The Rust spelling of a type a callback's method takes or returns. +fn rust(ty: &Type) -> String { + match ty { + Type::Unit => "()".to_string(), + Type::Bool => "bool".to_string(), + Type::Int(int) => int.rust().to_string(), + Type::F32 => "f32".to_string(), + Type::F64 => "f64".to_string(), + Type::Char => "char".to_string(), + Type::Str => "str".to_string(), + Type::String => "::std::string::String".to_string(), + Type::Slice => "[u8]".to_string(), + Type::Vec => "::std::vec::Vec".to_string(), + Type::Bytes => "::bytes::Bytes".to_string(), + Type::Duration => "::std::time::Duration".to_string(), + Type::Option(inner) => format!("Option<{}>", rust(inner)), + Type::Ref(Mutability::Not, inner) => format!("&{}", rust(inner)), + other => unreachable!("a callback never takes {other:?}"), + } +} + /// The crate that builds the C ABI. pub struct Crate<'a> { pub abi: &'a Abi<'a>, @@ -563,7 +584,80 @@ impl Gen<'_> { } } - fn callback(&mut self, _i: usize) {} + /// A callback: its table of foreign functions, and the Rust type that implements the + /// trait by calling them. + fn callback(&mut self, i: usize) { + let callback = &self.abi.api.callbacks[i]; + let name = self.abi.callback(i); + let path = self.path(&callback.path); + let mut table = String::from("\tpub free: Option,\n"); + let mut methods = String::new(); + for method in &callback.methods { + let method_name = method.name(); + let c_params: Vec = std::iter::once("*mut c_void".to_string()) + .chain(method.params.iter().map(|p| self.rs(&self.abi.ty(&p.ty)))) + .collect(); + let ret = self.rs(&self.abi.ty(&method.ok)); + let _ = writeln!( + table, + "\tpub {method_name}: Option {ret}>,", + c_params.join(", ") + ); + let receiver = match method.receiver { + Some(Receiver::Mut) => "&mut self", + _ => "&self", + }; + let params: Vec = method + .params + .iter() + .enumerate() + .map(|(n, p)| format!("p{n}: {}", rust(&p.ty))) + .collect(); + let args: Vec = std::iter::once("self.0.data".to_string()) + .chain(method.params.iter().enumerate().map(|(n, p)| self.view(&p.ty, &format!("p{n}")))) + .collect(); + let _ = write!( + methods, + "\tfn {method_name}({receiver}{}) -> {} {{\n\t\tlet w = \"{name}_vtable.{method_name}\";\n\t\tlet f = unsafe {{ (*self.0.vtable).{method_name} }}.unwrap_or_else(|| rt::fail(w, \"the function is null\"));\n\t\tlet result = unsafe {{ f({}) }};\n\t\t{}\n\t}}\n", + params.iter().map(|p| format!(", {p}")).collect::(), + rust(&method.ok), + args.join(", "), + self.lift(&method.ok, "result"), + ); + } + self.line(format!("#[repr(C)]\npub struct {name}_vtable {{\n{table}}}\n")); + self.line(format!( + "#[repr(C)]\n#[derive(Clone, Copy)]\npub struct {name} {{\n\tpub vtable: *const {name}_vtable,\n\tpub data: *mut c_void,\n}}\n" + )); + self.line(format!( + "/// The foreign implementation, which frees its data when dropped.\npub struct Foreign_{name}({name});\n\n// SAFETY: the callback's contract: its functions may be called from any thread.\nunsafe impl Send for Foreign_{name} {{}}\n// SAFETY: as above.\nunsafe impl Sync for Foreign_{name} {{}}\n\nimpl Drop for Foreign_{name} {{\n\tfn drop(&mut self) {{\n\t\tif let Some(free) = unsafe {{ (*self.0.vtable).free }} {{\n\t\t\tunsafe {{ free(self.0.data) }};\n\t\t}}\n\t}}\n}}\n" + )); + self.line(format!("impl {path} for Foreign_{name} {{\n{methods}}}\n")); + } + + /// The C value lending the Rust value `e` of type `ty` to a callback for its call. + fn view(&self, ty: &Type, e: &str) -> String { + match ty { + Type::Ref(_, inner) => match &**inner { + Type::Str => format!("rt::Buf::view({e}.as_bytes())"), + _ => format!("rt::Buf::view({e})"), + }, + Type::String => format!("rt::Buf::view({e}.as_bytes())"), + Type::Vec | Type::Bytes => format!("rt::Buf::view(&{e}[..])"), + Type::Option(inner) => match &**inner { + inner if Abi::is_buf(inner) => format!( + "match &{e} {{ Some(v) => {}, None => rt::Buf::NONE }}", + self.view(inner, "v") + ), + inner => format!( + "match {e} {{ Some(v) => {name} {{ some: true, value: {} }}, None => {name} {{ some: false, value: unsafe {{ ::std::mem::zeroed() }} }} }}", + self.view(inner, "v"), + name = self.abi.option(inner) + ), + }, + _ => self.lower(ty, e), + } + } /// An argument: the statement binding it from its C parameter `c` to `local`, and /// the expression passing it. A future owns its arguments, so it borrows nothing diff --git a/ffi/tests/api.c b/ffi/tests/api.c index 45a509742..6265b72e7 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -31,6 +31,18 @@ static void drop(void *data) { drops++; } +/* The Log callback: keeps even levels. */ +static bool log_line(void *data, uint8_t level, api_buf line) { + (void)data; + printf("log %u %.*s\n", level, (int)line.len, (const char *)line.ptr); + return level % 2 == 0; +} + +static void log_free(void *data) { + (void)data; + printf("freed\n"); +} + static int script(void) { printf("limit %llu\n", (unsigned long long)API_LIMIT); @@ -85,6 +97,31 @@ static int script(void) { print("", api_describe(events[i]), "\n"); } + /* A `Copy` handle passed by value is copied, so it stays usable. */ + api_stamp *stamp = api_stamp_from_millis(2500); + printf("secs %llu\n", (unsigned long long)api_stamp_secs(stamp)); + api_stamp *later = api_stamp_from_millis(3000); + printf("later %s\n", api_stamp_later(later, stamp) ? "true" : "false"); + api_stamp_free(later); + printf("secs %llu\n", (unsigned long long)api_stamp_secs(stamp)); + api_message *message = api_message_new(stamp, str("body")); + api_stamp_free(stamp); + print("payload ", api_message_payload(message), "\n"); + api_stamp *read = api_message_stamp(message); + print("stamp ", api_stamp_debug(read), "\n"); + api_stamp_free(read); + printf("sent %s\n", api_message_sent(message) ? "true" : "false"); + api_message_free(message); + + static const api_log_vtable print_log = {.free = log_free, .log = log_line}; + uint8_t levels[] = {1, 2, 3, 4}; + api_buf lines = {.ptr = levels, .len = sizeof levels}; + printf("kept %u\n", api_emit((api_log){.vtable = &print_log}, lines)); + api_logger *logger = api_logger_new((api_log){.vtable = &print_log}); + printf("write %s\n", api_logger_write(logger, str("hi")) ? "true" : "false"); + api_logger_free(logger); + printf("dropped\n"); + api_channel *channel = api_channel_new(); api_waker waker = {.wake = wake, .drop = drop, .data = NULL}; api_channel_recv_future *recv = api_channel_recv(channel); From dc354bed905e1d00f063b882752c9d455782dd1c Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:21:22 -0700 Subject: [PATCH 07/16] wip(ffi): just ffi moq exports, builds, and runs the C test Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/justfile | 17 +++++++++++++++++ ffi/moq/ffi.toml | 2 ++ ffi/src/collect.rs | 4 ++++ 3 files changed, 23 insertions(+) diff --git a/ffi/justfile b/ffi/justfile index 126c4d76f..148de7ef8 100644 --- a/ffi/justfile +++ b/ffi/justfile @@ -46,3 +46,20 @@ census checkout="": src=../ts/target/moq fi cargo run --locked --quiet -- --config moq/ffi.toml --manifest-path "$src/rs/moq-net/Cargo.toml" --census target/census/moq-net.md + +# Export moq-net's C ABI, build it, and run moq/moq.c against it, from the moq revision `just ts moq` pins or a checkout. +moq checkout="": + #!/usr/bin/env bash + set -euo pipefail + src="{{ checkout }}" + if [ -z "$src" ]; then + (cd ../ts && just moq-pin) + src=../ts/target/moq + fi + out=target/export/moq + cargo run --locked --quiet -- --config moq/ffi.toml --manifest-path "$src/rs/moq-net/Cargo.toml" --out "$out" + # moq's lockfile pins what the export depends on, as it pins moq-net's own build. + cp "$src/Cargo.lock" "$out/Cargo.lock" + 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 diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index a64f5eece..50d588688 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -155,6 +155,8 @@ exclude = [ "track::Subscription::with_groups", "track::Subscription::with_ranges", "transport::Error", + "transport::MaybeSend", + "transport::MaybeSync", "transport::memory::pair", "transport::poll::AcceptBi", "transport::poll::AcceptUni", diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index a5b47a1c8..0c9d82e5a 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -542,6 +542,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { fn callback(&mut self, def_id: DefId, path: &[String]) -> Result, Vec> { let tcx = self.tcx; let mut errs = Vec::new(); + // It may already cover the foreign implementation, which could not then implement it. + if !tcx.trait_impls_of(def_id).blanket_impls().is_empty() { + errs.push(why("trait with a blanket impl", "")); + } for clause in tcx.explicit_super_clauses_of(def_id).iter_identity_copied() { let (clause, _) = clause.skip_norm_wip(); if let Some(trait_pred) = clause.as_trait_clause() { From 4ab20eaac67c96f16397d5ca6c1a7553cc48d6ab Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:25:37 -0700 Subject: [PATCH 08/16] wip(ffi): constants, nightly job, and the shared driver in the flake build Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- .github/workflows/nightly.yml | 30 ++++++ driver/Cargo.lock | 7 ++ driver/src/cargo.rs | 8 +- ffi/fixtures/api/examples/transcript.rs | 6 +- ffi/fixtures/api/src/lib.rs | 5 +- ffi/moq/ffi.toml | 4 +- ffi/src/abi.rs | 16 ++- ffi/src/c.rs | 26 ++++- ffi/src/census.rs | 7 +- ffi/src/collect.rs | 138 ++++++++++++++++++------ ffi/src/driver.rs | 5 +- ffi/src/glue.rs | 35 +++--- ffi/src/ir.rs | 16 ++- ffi/tests/fixtures.rs | 15 ++- flake.nix | 11 +- justfile | 3 + 16 files changed, 250 insertions(+), 82 deletions(-) create mode 100644 driver/Cargo.lock diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index c3d5b459d..ad299a7cb 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -97,6 +97,36 @@ jobs: - name: Summary run: cat ts/target/bench/report.md >> "$GITHUB_STEP_SUMMARY" + ffi: + name: Export moq-net to C + runs-on: ubuntu-24.04-arm + timeout-minutes: 60 + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/nix + + # moq-net's pub API at the pinned moq revision, exported, built, and driven from C. + - name: Export + run: nix develop --command just ffi moq + + # What exports, and every refusal, ranked. + - name: Census + run: nix develop --command just ffi census + + - name: Summarize + run: awk '/^## Refused items/ { exit } { print }' ffi/target/census/moq-net.md >> "$GITHUB_STEP_SUMMARY" + + - name: Upload + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: ffi-census + path: ffi/target/census + census: name: Census moq-net and kio runs-on: ubuntu-24.04-arm diff --git a/driver/Cargo.lock b/driver/Cargo.lock new file mode 100644 index 000000000..09c13bb77 --- /dev/null +++ b/driver/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "rust2-driver" +version = "0.0.0" diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs index 82ed64613..481d75e82 100644 --- a/driver/src/cargo.rs +++ b/driver/src/cargo.rs @@ -161,7 +161,13 @@ fn run_cargo(cmd: &mut Command) -> Result<(), String> { /// The directory of the workspace `manifest` belongs to. fn workspace_root(manifest: &Path) -> Result { let output = cargo() - .args(["locate-project", "--workspace", "--message-format", "plain", "--manifest-path"]) + .args([ + "locate-project", + "--workspace", + "--message-format", + "plain", + "--manifest-path", + ]) .arg(manifest) .output() .map_err(|err| format!("running cargo: {err}"))?; diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index f1551051a..d605bba60 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -70,11 +70,7 @@ fn main() { println!("{}", api_fixture::greet("x", Shape::Square)); println!("len {}", api_fixture::len(b"abc")); - for event in [ - Event::Moved(p), - Event::Named { name: "n".to_string() }, - Event::Done, - ] { + for event in [Event::Moved(p), Event::Named { name: "n".to_string() }, Event::Done] { println!("{}", api_fixture::describe(&event)); } diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index 23b3558c8..b58ecbfa1 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -223,10 +223,7 @@ pub trait Log: Send + Sync { /// Each line to `log` as a type parameter takes it, returning how many it kept. pub fn emit(log: impl Log, lines: Vec) -> u32 { - lines - .iter() - .filter(|&&n| log.log(n, &format!("line {n}"))) - .count() as u32 + lines.iter().filter(|&&n| log.log(n, &format!("line {n}"))).count() as u32 } /// Holds a foreign implementation as a trait object, dropping it with itself. diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index 50d588688..998a5ee24 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -62,7 +62,6 @@ exclude = [ "broadcast::Tracks::broadcast", "broadcast::Tracks::poll_next", "bytes", - "cache::DEFAULT_EXPIRY", "cache::Pool::gc", "frame::Buffer", "frame::Consumer::poll_read_all", @@ -87,7 +86,6 @@ exclude = [ "origin::Consumer::allowed", "origin::Consumer::root", "origin::Consumer::scope", - "origin::DEFAULT_UPDATE_HOLD", "origin::Driver::poll", "origin::Dynamic::poll_requested_broadcast", "origin::Prepared::broadcast", @@ -106,8 +104,10 @@ exclude = [ "server::Handshake::with_publisher", "stats::Config::exclude", "stats::Config::with_exclude", + "stats::Failure::ALL", "stats::Handle::parent", "stats::Handle::tier", + "stats::Refusal::ALL", "stats::Registry::exclude", "stats::Report::sessions", "stats::Report::traffic", diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index b01aefbf9..f7469a880 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -35,7 +35,10 @@ pub enum Ty { /// A plain enum, passed as its C enum, which is an `int`. Enum(String), /// A handle: `const` when only borrowed. - Handle { name: String, constant: bool }, + Handle { + name: String, + constant: bool, + }, /// A future's handle. Future(String), /// `_waker` @@ -211,7 +214,8 @@ impl<'a> Abi<'a> { Ty::Handle { name, .. } => Ty::Handle { name: name.clone(), constant: receiver == Receiver::Ref - || (receiver == Receiver::Owned && self.api.objects.iter().any(|o| o.copy && &self.name(&o.path) == name)), + || (receiver == Receiver::Owned + && self.api.objects.iter().any(|o| o.copy && &self.name(&o.path) == name)), }, // A value's receiver is read through a pointer, and never changed. value => Ty::In(Box::new(value.clone())), @@ -323,7 +327,11 @@ impl<'a> Abi<'a> { let what = format!("enum `{}`", e.path.join("::")); let upper = name.to_uppercase(); for variant in &e.variants { - self.claim(format!("{upper}_{}", snake(&variant.name).to_uppercase()), what.clone(), e.span); + self.claim( + format!("{upper}_{}", snake(&variant.name).to_uppercase()), + what.clone(), + e.span, + ); types.extend(variant.fields.iter().map(|f| &f.ty)); } let plain = e.plain(); @@ -396,7 +404,7 @@ impl<'a> Abi<'a> { _ => {} } } - for (name, _) in &options { + for name in options.keys() { self.claim(name.clone(), "an option".to_string(), crate_span); } self.options = options; diff --git a/ffi/src/c.rs b/ffi/src/c.rs index d354f6fbb..7909c53a7 100644 --- a/ffi/src/c.rs +++ b/ffi/src/c.rs @@ -126,9 +126,17 @@ impl Header<'_> { let mut table = vec!["\tvoid (*free)(void *data);".to_string()]; for method in &callback.methods { let params: Vec = std::iter::once("void *data".to_string()) - .chain(method.params.iter().map(|p| self.decl(&abi.ty(&p.ty), &abi::escape(&p.name)))) + .chain( + method + .params + .iter() + .map(|p| self.decl(&abi.ty(&p.ty), &abi::escape(&p.name))), + ) .collect(); - let decl = self.decl(&abi.ty(&method.ok), &format!("(*{})({})", method.name(), params.join(", "))); + let decl = self.decl( + &abi.ty(&method.ok), + &format!("(*{})({})", method.name(), params.join(", ")), + ); table.push(format!("\t{decl};")); } self.line(format!( @@ -221,7 +229,9 @@ impl Header<'_> { let inner = abi.ty(inner); self.value(&inner); let value = self.decl(&inner, "value"); - self.line(format!("typedef struct {name} {{\n\tbool some;\n\t{value};\n}} {name};\n")); + self.line(format!( + "typedef struct {name} {{\n\tbool some;\n\t{value};\n}} {name};\n" + )); return; } if let Some(i) = (0..abi.api.records.len()).find(|&i| &abi.record(i) == name) { @@ -250,7 +260,10 @@ impl Header<'_> { .enumerate() .map(|(n, v)| format!("\t{upper}_{} = {n},", abi::snake(&v.name).to_uppercase())) .collect(); - self.line(format!("typedef enum {name}_tag {{\n{}\n}} {name}_tag;\n", tags.join("\n"))); + self.line(format!( + "typedef enum {name}_tag {{\n{}\n}} {name}_tag;\n", + tags.join("\n") + )); let mut members = Vec::new(); for variant in e.variants.iter().filter(|v| !v.fields.is_empty()) { let payload = format!("{name}_{}", abi::snake(&variant.name)); @@ -264,7 +277,10 @@ impl Header<'_> { .zip(&fields) .map(|(f, ty)| format!("\t{};", self.decl(ty, &abi::escape(&f.name)))) .collect(); - self.line(format!("typedef struct {payload} {{\n{}\n}} {payload};\n", decls.join("\n"))); + self.line(format!( + "typedef struct {payload} {{\n{}\n}} {payload};\n", + decls.join("\n") + )); members.push(format!("\t\t{payload} {};", abi::escape(&abi::snake(&variant.name)))); } self.line(format!( diff --git a/ffi/src/census.rs b/ffi/src/census.rs index 7d989028d..cf254dc17 100644 --- a/ffi/src/census.rs +++ b/ffi/src/census.rs @@ -20,7 +20,10 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn let mut out = String::new(); let _ = writeln!(out, "# Export census of `{krate}`\n"); - let _ = writeln!(out, "| Item | Exported | Refused | Share exported |\n| --- | ---: | ---: | ---: |"); + let _ = writeln!( + out, + "| Item | Exported | Refused | Share exported |\n| --- | ---: | ---: | ---: |" + ); let mut row = |name: &str, exported: usize, refused: usize| { let total = exported + refused; let share = match total { @@ -161,7 +164,7 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn } /// Groups by count, most first, then by key. -fn ranked<'a, K: Ord, V>(groups: &'a BTreeMap>) -> Vec<(&'a K, &'a Vec)> { +fn ranked(groups: &BTreeMap>) -> Vec<(&K, &Vec)> { let mut ranked: Vec<_> = groups.iter().collect(); ranked.sort_by(|a, b| b.1.len().cmp(&a.1.len()).then_with(|| a.0.cmp(b.0))); ranked diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 0c9d82e5a..ab8203722 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -18,8 +18,8 @@ use rustc_trait_selection::traits::query::evaluate_obligation::InferCtxtExt as _ use crate::config::Config; use crate::ir::{ - Api, Callback, Constant, Dyn, Enum, Field, Function, Int, Literal, Mutability, Object, Param, Path, Receiver, - Record, Traits, Type, Variant, + Access, Api, Callback, Constant, Dyn, Enum, Field, Function, Int, Literal, Mutability, Object, Param, Path, + Receiver, Record, Traits, Type, Variant, }; /// Why something is refused: a construct, ranked by the census, and what it names. @@ -70,9 +70,8 @@ enum Decl { Refused(Why), } -struct Collector<'a, 'tcx> { +struct Collector<'tcx> { tcx: TyCtxt<'tcx>, - config: &'a Config, /// Each `pub` item and its shortest path, in the order the walk met them. items: Vec<(DefId, Path)>, decls: rustc_data_structures::fx::FxHashMap, @@ -104,7 +103,6 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> }); let mut c = Collector { tcx, - config, items: Vec::new(), decls: Default::default(), refusals: Vec::new(), @@ -138,7 +136,7 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> } } -impl<'a, 'tcx> Collector<'a, 'tcx> { +impl<'tcx> Collector<'tcx> { /// Whether the config excludes `path`, counting the exclusion. fn exclude(&mut self, path: &[String]) -> bool { let joined = path.join("::"); @@ -217,7 +215,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { | DefKind::Union | DefKind::Trait | DefKind::Fn - | DefKind::Const { .. } => self.items.push((def_id, path)), + | DefKind::Const => self.items.push((def_id, path)), _ => self.refuse(&path, "item", span, vec![why("item kind", format!("{kind:?}"))]), } } @@ -249,7 +247,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { false => self.object(def_id), } } - DefKind::Enum if tcx.adt_def(def_id).variants().is_empty() => Decl::Refused(why("enum without variants", "")), + DefKind::Enum if tcx.adt_def(def_id).variants().is_empty() => { + Decl::Refused(why("enum without variants", "")) + } DefKind::Enum => Decl::Enum(0), DefKind::Trait => Decl::Callback(0), _ => continue, @@ -446,10 +446,11 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { Ok(function) => self.api.functions.push(function), Err(why) => self.refuse(&path, "fn", span, why), }, - DefKind::Const { .. } => match self.constant(def_id) { - Ok(value) => self.api.constants.push(Constant { path, span, value }), - Err(why) => self.refuse(&path, "const", span, vec![why]), - }, + DefKind::Const => { + if let Some(getter) = self.constant_item(def_id, path) { + self.api.functions.push(getter); + } + } _ => {} }, } @@ -482,7 +483,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { ok: ty, err: None, future: false, - field: true, + access: Access::Field, }), Err(why) => self.refuse(&getter, "field", span, vec![why]), } @@ -497,7 +498,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let self_ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); for &imp in tcx.inherent_impls(def_id) { for item in tcx.associated_items(imp).in_definition_order() { - let ty::AssocKind::Fn { name, .. } = item.kind else { + let (ty::AssocKind::Fn { name, .. } | ty::AssocKind::Const { name, .. }) = item.kind else { continue; }; if !tcx.visibility(item.def_id).is_public() { @@ -512,9 +513,14 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { self.hidden.push(method.join("::")); continue; } + let span = tcx.def_span(item.def_id); + if let ty::AssocKind::Const { .. } = item.kind { + methods.extend(self.constant_item(item.def_id, method)); + continue; + } match self.function(item.def_id, method.clone(), Some(self_ty)) { Ok(function) => methods.push(function), - Err(why) => self.refuse(&method, "method", tcx.def_span(item.def_id), why), + Err(why) => self.refuse(&method, "method", span, why), } } } @@ -522,14 +528,18 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let implements = |item| { tcx.get_diagnostic_item(item).is_some_and(|tr| { let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(env); - infcx.type_implements_trait(tr, [self_ty], env).must_apply_modulo_regions() + infcx + .type_implements_trait(tr, [self_ty], env) + .must_apply_modulo_regions() }) }; let traits = Traits { clone: implements(sym::Clone), eq: tcx.lang_items().eq_trait().is_some_and(|tr| { let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(env); - infcx.type_implements_trait(tr, [self_ty, self_ty], env).must_apply_modulo_regions() + infcx + .type_implements_trait(tr, [self_ty, self_ty], env) + .must_apply_modulo_regions() }), display: implements(sym::Display), debug: implements(sym::Debug), @@ -550,7 +560,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let (clause, _) = clause.skip_norm_wip(); if let Some(trait_pred) = clause.as_trait_clause() { let tr = trait_pred.def_id(); - let auto = [sym::Send, sym::Sync].iter().any(|&item| tcx.is_diagnostic_item(item, tr)) + let auto = [sym::Send, sym::Sync] + .iter() + .any(|&item| tcx.is_diagnostic_item(item, tr)) || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); if !auto { errs.push(why("supertrait", tcx.def_path_str(tr))); @@ -585,7 +597,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { } } // An `impl Trait` return's own type: the method refuses it. - ty::AssocKind::Type { data: ty::AssocTypeData::Rpitit(_) } => {} + ty::AssocKind::Type { + data: ty::AssocTypeData::Rpitit(_), + } => {} ty::AssocKind::Type { .. } => errs.push(why("associated type", item.name().to_string())), ty::AssocKind::Const { .. } => errs.push(why("associated const", item.name().to_string())), } @@ -601,10 +615,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let tcx = self.tcx; let mut errs = Vec::new(); self.impls.borrow_mut().clear(); - let args = match self.instantiate(def_id, self_ty) { - Ok(args) => args, - Err(why) => return Err(why), - }; + let args = self.instantiate(def_id, self_ty)?; let env = TypingEnv::post_analysis(tcx, def_id); let sig = tcx.fn_sig(def_id).instantiate(tcx, args).skip_norm_wip(); let sig = tcx.instantiate_bound_regions_with_erased(sig); @@ -614,7 +625,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { }; let names = tcx.fn_arg_idents(def_id); let has_self = matches!(tcx.def_kind(def_id), DefKind::AssocFn) - && matches!(tcx.associated_item(def_id).kind, ty::AssocKind::Fn { has_self: true, .. }); + && matches!( + tcx.associated_item(def_id).kind, + ty::AssocKind::Fn { has_self: true, .. } + ); let mut inputs = sig.inputs().iter().copied().map(normalize).enumerate(); let receiver = match has_self { false => None, @@ -656,9 +670,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { future = true; } let (ok, err) = match output.kind() { - ty::Adt(adt, args) if tcx.is_diagnostic_item(sym::Result, adt.did()) => { - (self.ty(args.type_at(0), Pos::Return), Some(self.ty(args.type_at(1), Pos::Return))) - } + ty::Adt(adt, args) if tcx.is_diagnostic_item(sym::Result, adt.did()) => ( + self.ty(args.type_at(0), Pos::Return), + Some(self.ty(args.type_at(1), Pos::Return)), + ), _ => (self.ty(output, Pos::Return), None), }; let ok = ok.map_err(|why| errs.push(why)).ok(); @@ -679,7 +694,7 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { ok, err, future, - field: false, + access: Access::Call, }), _ => Err(errs), } @@ -707,7 +722,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { GenericArgKind::Type(param) => match self.choose(def_id, param) { Ok(ty) => args[i] = ty.into(), // The parameter stays, and `ty` maps it to the foreign implementation. - Err(Why { construct: "callback bound", .. }) if let Some(callback) = self.foreign(def_id, param) => { + Err(Why { + construct: "callback bound", + .. + }) if let Some(callback) = self.foreign(def_id, param) => { self.impls.borrow_mut().push((param, callback)); } Err(why) => errs.push(why), @@ -812,7 +830,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { continue; } let tr = bound.def_id(); - let met = [sym::Send, sym::Sync].iter().any(|&item| tcx.is_diagnostic_item(item, tr)) + let met = [sym::Send, sym::Sync] + .iter() + .any(|&item| tcx.is_diagnostic_item(item, tr)) || [tcx.lang_items().sized_trait(), tcx.lang_items().meta_sized_trait()].contains(&Some(tr)); match self.decls.get(&tr) { Some(Decl::Callback(i)) if callback.is_none() => callback = Some(*i), @@ -829,7 +849,10 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { let future = tcx.lang_items().future_trait()?; let output = tcx.lang_items().future_output()?; let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); - if !infcx.type_implements_trait(future, [ty], param_env).must_apply_modulo_regions() { + if !infcx + .type_implements_trait(future, [ty], param_env) + .must_apply_modulo_regions() + { return None; } let projection = Ty::new_projection(tcx, ty::IsRigid::No, output, [ty]); @@ -843,7 +866,44 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { return true; }; let (infcx, param_env) = tcx.infer_ctxt().build_with_typing_env(env); - infcx.type_implements_trait(send, [ty], param_env).must_apply_modulo_regions() + infcx + .type_implements_trait(send, [ty], param_env) + .must_apply_modulo_regions() + } + + /// A constant: a C constant if a `bool` or integer, or else a function returning it, + /// which the caller adds. + fn constant_item(&mut self, def_id: DefId, path: Path) -> Option { + let tcx = self.tcx; + let span = tcx.def_span(def_id); + let why = match self.constant(def_id) { + Ok(value) => { + self.api.constants.push(Constant { path, span, value }); + return None; + } + Err(why) => why, + }; + let ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); + if why.construct != "constant type" { + self.refuse(&path, "const", span, vec![why]); + return None; + } + match self.ty(ty, Pos::Return) { + Ok(ok) => Some(Function { + path, + span, + receiver: None, + params: Vec::new(), + ok, + err: None, + future: false, + access: Access::Const, + }), + Err(why) => { + self.refuse(&path, "const", span, vec![why]); + None + } + } } /// A constant's value, if it is a `bool` or integer. @@ -900,7 +960,9 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { // Returned as a copy: plain data reads the same either way. // Returned as a copy: plain data reads the same either way, and so does a // `Copy` handle's value. - (Type::Object(_), Pos::Return, _) if !tcx.type_is_copy_modulo_regions(TypingEnv::fully_monomorphized(), *inner) => { + (Type::Object(_), Pos::Return, _) + if !tcx.type_is_copy_modulo_regions(TypingEnv::fully_monomorphized(), *inner) => + { return Err(why("borrowed object return", inner.to_string())); } (_, Pos::Field, _) => return Err(why("reference field", inner.to_string())), @@ -960,7 +1022,11 @@ impl<'a, 'tcx> Collector<'a, 'tcx> { Some(Decl::Object(i)) => Type::Object(*i), Some(Decl::Refused(_)) => return Err(why("refused type", tcx.def_path_str(did))), Some(Decl::Callback(_)) | None => { - let construct = self.left_out.get(&did).copied().unwrap_or("type not reachable from the crate root"); + let construct = self + .left_out + .get(&did) + .copied() + .unwrap_or("type not reachable from the crate root"); return Err(why(construct, tcx.def_path_str(did))); } } @@ -1072,7 +1138,9 @@ fn implements(tcx: TyCtxt<'_>, def_id: DefId, item: rustc_span::Symbol) -> bool let Some(tr) = tcx.get_diagnostic_item(item) else { return false; }; - let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(TypingEnv::post_analysis(tcx, def_id)); + let (infcx, env) = tcx + .infer_ctxt() + .build_with_typing_env(TypingEnv::post_analysis(tcx, def_id)); infcx.type_implements_trait(tr, [ty], env).must_apply_modulo_regions() } diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index 8e65decd6..7ef2c0b12 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -9,8 +9,8 @@ use rustc_interface::interface::Compiler; use rustc_middle::ty::TyCtxt; use rustc_span::Span; -use crate::config::{self, Config}; use crate::abi::Abi; +use crate::config::{self, Config}; use crate::{c, census, collect, glue}; /// Run as rustc, with `args` as cargo passed them: the wrapped rustc's path first. @@ -114,7 +114,8 @@ impl Callbacks for Export { } for (path, count) in &collected.excluded { if *count == 0 { - tcx.dcx().err(format!("rust2-ffi: exclude `{path}` names nothing exported")); + tcx.dcx() + .err(format!("rust2-ffi: exclude `{path}` names nothing exported")); } } let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 2508446ae..04b9a778d 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -10,7 +10,7 @@ use std::fmt::Write; use std::path::Path; use crate::abi::{self, Abi, Ty}; -use crate::ir::{Function, Mutability, Receiver, Traits, Type}; +use crate::ir::{Access, Function, Mutability, Receiver, Traits, Type}; const RUNTIME: &str = include_str!("../runtime/rt.rs"); @@ -80,10 +80,7 @@ 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)), - self.header, - ) + crate::driver::write(&out.join("include").join(format!("{}.h", self.abi.prefix)), self.header) } } @@ -140,10 +137,7 @@ impl Gen<'_> { Type::Bytes => format!("::bytes::Bytes::copy_from_slice(unsafe {{ {e}.bytes(w) }})"), Type::Duration => format!("{e}.lift(w)"), Type::Option(inner) => match inner.base() { - Type::Object(_) => format!( - "if {e}.is_null() {{ None }} else {{ Some({}) }}", - self.lift(inner, e) - ), + Type::Object(_) => format!("if {e}.is_null() {{ None }} else {{ Some({}) }}", self.lift(inner, e)), base if Abi::is_buf(base) => { format!("if {e}.is_none() {{ None }} else {{ Some({}) }}", self.lift(inner, e)) } @@ -219,7 +213,10 @@ impl Gen<'_> { .map(|free| format!("if {e}.some {{ {free} }}")), }, Type::Box(inner) => self.free(inner, e), - Type::Object(i) => Some(format!("unsafe {{ rt::Object::<{}>::free({e}) }};", self.object_path(*i))), + Type::Object(i) => Some(format!( + "unsafe {{ rt::Object::<{}>::free({e}) }};", + self.object_path(*i) + )), Type::Record(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.record(*i))), Type::Enum(i) if self.owns(ty) => Some(format!("free_{}({e});", self.abi.enumeration(*i))), _ => None, @@ -274,8 +271,7 @@ impl Gen<'_> { for i in 0..api.callbacks.len() { self.callback(i); } - for i in 0..api.objects.len() { - let object = &api.objects[i]; + for (i, object) in api.objects.iter().enumerate() { let name = self.abi.object(i); let path = self.object_path(i); self.line(format!( @@ -614,7 +610,13 @@ impl Gen<'_> { .map(|(n, p)| format!("p{n}: {}", rust(&p.ty))) .collect(); let args: Vec = std::iter::once("self.0.data".to_string()) - .chain(method.params.iter().enumerate().map(|(n, p)| self.view(&p.ty, &format!("p{n}")))) + .chain( + method + .params + .iter() + .enumerate() + .map(|(n, p)| self.view(&p.ty, &format!("p{n}"))), + ) .collect(); let _ = write!( methods, @@ -784,9 +786,10 @@ impl Gen<'_> { } None => self.path(&function.path), }; - let call = match function.field { - true => format!("&({}).{}", args[0], function.name()), - false => format!("{callee}({})", args.join(", ")), + let call = match function.access { + Access::Call => format!("{callee}({})", args.join(", ")), + Access::Field => format!("&({}).{}", args[0], function.name()), + Access::Const => callee, }; let body = stmts.join("\n\t"); if let Some((_, poll, free)) = &export.future { diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index 7ff4c109b..701d4366c 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -110,9 +110,19 @@ pub struct Function { pub err: Option, /// Whether it returns a future: an `async fn`, or a value that implements `Future`. pub future: bool, - /// Whether it reads a `pub` field of its receiver, named as the function is, rather - /// than calling a method. - pub field: bool, + /// What it reads: Rust's function, or a field or constant named as it is. + pub access: Access, +} + +/// What an exported function reads. +#[derive(Clone, Copy, PartialEq, Eq)] +pub enum Access { + /// It calls the function. + Call, + /// It reads a `pub` field of its receiver. + Field, + /// It reads a constant that is not a `bool` or integer. + Const, } impl Function { diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 8eb948e64..7cbaaa135 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -73,7 +73,15 @@ fn api() { let c = run(&mut Command::new(&exe)); let native = run(cargo() - .args(["run", "--quiet", "--locked", "--package", "api-fixture", "--example", "transcript"]) + .args([ + "run", + "--quiet", + "--locked", + "--package", + "api-fixture", + "--example", + "transcript", + ]) .current_dir(manifest_dir())); assert_eq!( String::from_utf8_lossy(&c.stdout), @@ -86,7 +94,10 @@ fn api() { ("moved", "api_counter_get: a handle's value was moved out"), ("borrowed", "api_channel_clear: a handle is already borrowed"), ("utf8", "api_greet: a string is not UTF-8"), - ("finished", "api_channel_recv_poll: a future is polled after it finished"), + ( + "finished", + "api_channel_recv_poll: a future is polled after it finished", + ), ("enum", "api_greet: an enum value is invalid"), ] { let output = Command::new(&exe).arg(case).output().unwrap(); diff --git a/flake.nix b/flake.nix index 8b7d74592..60d8441d1 100644 --- a/flake.nix +++ b/flake.nix @@ -60,7 +60,16 @@ { pname = "rust2-ts"; version = "0.0.0"; - src = ./ts; + # With the driver front end it shares, which it depends on by path. + src = pkgs.lib.fileset.toSource { + root = ./.; + fileset = pkgs.lib.fileset.unions [ + ./ts + ./driver + ]; + }; + buildAndTestSubdir = "ts"; + cargoRoot = "ts"; cargoLock.lockFile = ./ts/Cargo.lock; cargoBuildFlags = [ "--package" diff --git a/justfile b/justfile index c524200c5..9e0f73c82 100644 --- a/justfile +++ b/justfile @@ -24,12 +24,14 @@ check: cargo fmt --all --check cargo clippy --locked --workspace --all-targets -- -D warnings just ts check + just ffi check just uniffi check # Run the tests. test: bash .claude/hooks/direnv.test.sh just ts test + just ffi test just uniffi test # Measure Rust build time on the pinned corpus; see bench/build/README.md. @@ -43,3 +45,4 @@ fix: nixfmt flake.nix cargo fmt --all just ts fix + just ffi fix From 90fd36b56df6b16f09a4a1b9dc46673cdbd9f72b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:31:31 -0700 Subject: [PATCH 09/16] wip(ffi): doc comments in the header, renames checked, bench sources Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/fixtures/api/src/lib.rs | 3 +- ffi/moq/bench/export.c | 97 +++++++++++++++++++++++++++++++++++++ ffi/moq/bench/moq-c.c | 49 +++++++++++++++++++ ffi/src/abi.rs | 17 ++++++- ffi/src/c.rs | 86 ++++++++++++++++++++++++++++---- ffi/src/census.rs | 6 ++- ffi/src/collect.rs | 33 ++++++++++++- ffi/src/driver.rs | 8 +++ ffi/src/ir.rs | 8 +++ 9 files changed, 294 insertions(+), 13 deletions(-) create mode 100644 ffi/moq/bench/export.c create mode 100644 ffi/moq/bench/moq-c.c diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index b58ecbfa1..b9f9c59e6 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -10,7 +10,8 @@ use bytes::Bytes; /// The largest value a [`Counter`] reaches. pub const LIMIT: u64 = 1000; -/// A point: a record, since every field is `pub`. +/// A point: a record, since every field is `pub`. Its docs reach the header, where a +/// comment such as `/* this */` must not close the header's own. #[derive(Clone, Copy, Debug, PartialEq, Default)] pub struct Point { pub x: i32, diff --git a/ffi/moq/bench/export.c b/ffi/moq/bench/export.c new file mode 100644 index 000000000..9e95a7328 --- /dev/null +++ b/ffi/moq/bench/export.c @@ -0,0 +1,97 @@ +/* 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. */ + +#define _POSIX_C_SOURCE 199309L + +#include +#include +#include + +#include "moq.h" + +#define GROUPS 10000 +#define FRAMES 100 + +static double now(void) { + struct timespec ts; + clock_gettime(CLOCK_MONOTONIC, &ts); + return (double)ts.tv_sec * 1e9 + (double)ts.tv_nsec; +} + +static moq_buf str(const char *s) { + return (moq_buf){.ptr = (const uint8_t *)s, .len = strlen(s)}; +} + +int main(void) { + moq_broadcast_info *binfo = moq_broadcast_info_new(); + moq_broadcast_producer *broadcast = moq_broadcast_info_produce(binfo); + moq_broadcast_info_free(binfo); + moq_timescale *micro = moq_timescale_micro(); + /* Builders take the handle's value, leaving the handle to free. */ + moq_track_info *defaults = moq_track_info_default(); + moq_track_info *info = moq_track_info_with_timescale(defaults, micro); + moq_track_info_free(defaults); + moq_track_producer *track = NULL; + moq_error *err = NULL; + if (!moq_broadcast_producer_create_track(broadcast, str("bench"), info, &track, &err)) { + return 1; + } + moq_track_info_free(info); + + uint8_t payload[100] = {0}; + moq_buf frame = {.ptr = payload, .len = sizeof payload}; + uint64_t micros = 0; + + /* Each frame stamped through a fresh timestamp handle, as a caller holding a u64 must. */ + double start = now(); + for (int g = 0; g < GROUPS; g++) { + moq_group_producer *group = NULL; + moq_track_producer_append_group(track, &group, &err); + for (int f = 0; f < FRAMES; f++) { + moq_timestamp *at = NULL; + moq_time_overflow *overflow = NULL; + moq_timestamp_from_micros(micros++, &at, &overflow); + if (!moq_group_producer_write_frame(group, at, frame, &err)) { + return 2; + } + moq_timestamp_free(at); + } + moq_group_producer_finish(group, &err); + moq_group_producer_free(group); + } + double stamped = (now() - start) / (GROUPS * FRAMES); + + /* The same, reusing one timestamp handle: what the handle costs. */ + moq_timestamp *at = NULL; + moq_time_overflow *overflow = NULL; + moq_timestamp_from_micros(micros, &at, &overflow); + start = now(); + for (int g = 0; g < GROUPS; g++) { + moq_group_producer *group = NULL; + moq_track_producer_append_group(track, &group, &err); + for (int f = 0; f < FRAMES; f++) { + if (!moq_group_producer_write_frame(group, at, frame, &err)) { + return 3; + } + } + moq_group_producer_finish(group, &err); + 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(); + int closed = 0; + for (int i = 0; i < GROUPS * FRAMES; i++) { + closed += moq_track_producer_is_closed(track); + } + 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 ? "!" : ""); + moq_track_producer_free(track); + moq_timescale_free(micro); + moq_broadcast_producer_free(broadcast); + return 0; +} diff --git a/ffi/moq/bench/moq-c.c b/ffi/moq/bench/moq-c.c new file mode 100644 index 000000000..994dab3f8 --- /dev/null +++ b/ffi/moq/bench/moq-c.c @@ -0,0 +1,49 @@ +/* bench/export.c's frame write path, through moq's hand-written rs/moq-c: a timed track, + * groups of 100 frames of 100 bytes, each frame stamped. */ + +#define _POSIX_C_SOURCE 199309L + +#include +#include +#include + +#include "moq.h" + +#define GROUPS 10000 +#define FRAMES 100 + +static double now(void) { + struct timespec ts; + clock_gettime(CLOCK_MONOTONIC, &ts); + return (double)ts.tv_sec * 1e9 + (double)ts.tv_nsec; +} + +int main(void) { + int32_t origin = moq_origin_create(); + int32_t broadcast = moq_origin_create_broadcast((uint32_t)origin, "b", 1); + /* No info: a raw track on a microsecond timescale. */ + int32_t track = moq_publish_track((uint32_t)broadcast, "bench", 5, NULL); + if (origin <= 0 || broadcast <= 0 || track <= 0) { + return 1; + } + + uint8_t payload[100] = {0}; + uint64_t micros = 0; + + double start = now(); + for (int g = 0; g < GROUPS; g++) { + int32_t group = moq_publish_track_group((uint32_t)track); + for (int f = 0; f < FRAMES; f++) { + if (moq_publish_group_frame((uint32_t)group, payload, sizeof payload, micros++) < 0) { + return 2; + } + } + moq_publish_group_finish((uint32_t)group); + } + double stamped = (now() - start) / (GROUPS * FRAMES); + + printf("moq-c: %.0f ns per stamped 100 B frame\n", stamped); + moq_publish_close((uint32_t)broadcast); + moq_origin_close((uint32_t)origin); + return 0; +} diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index f7469a880..e1019b6c1 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -71,6 +71,8 @@ pub struct Abi<'a> { pub prefix: String, /// C names for paths, in place of the rule's: an item's, and its methods' through it. rename: &'a BTreeMap, + /// The renamed paths some name went through. + renamed: std::cell::RefCell>, /// Each `Option` struct by C name, with `T`. pub options: BTreeMap, /// Every C name claimed, with what claimed it. @@ -85,6 +87,7 @@ impl<'a> Abi<'a> { api, prefix: prefix.to_string(), rename, + renamed: Default::default(), options: BTreeMap::new(), names: HashMap::new(), clashes: Vec::new(), @@ -98,7 +101,9 @@ impl<'a> Abi<'a> { let mut name = self.prefix.clone(); let mut rest = path; for len in (1..=path.len()).rev() { - if let Some(renamed) = self.rename.get(&path[..len].join("::")) { + let key = path[..len].join("::"); + if let Some(renamed) = self.rename.get(&key) { + self.renamed.borrow_mut().insert(key); name.push('_'); name.push_str(renamed); rest = &path[len..]; @@ -112,6 +117,16 @@ impl<'a> Abi<'a> { name } + /// The config's renames that name nothing exported. + pub fn unused_renames(&self) -> Vec<&str> { + let renamed = self.renamed.borrow(); + self.rename + .keys() + .filter(|key| !renamed.contains(*key)) + .map(String::as_str) + .collect() + } + /// A constant's name for a path: the name in upper case. pub fn constant(&self, path: &[String]) -> String { self.name(path).to_uppercase() diff --git a/ffi/src/c.rs b/ffi/src/c.rs index 7909c53a7..31b138393 100644 --- a/ffi/src/c.rs +++ b/ffi/src/c.rs @@ -3,7 +3,7 @@ use std::collections::BTreeSet; use crate::abi::{self, Abi, Sig, Ty}; -use crate::ir::{Function, Int, Literal, Traits, Type}; +use crate::ir::{Function, Int, Literal, Receiver, Traits, Type}; /// The header for `abi`, as `.h`. pub fn header(abi: &Abi<'_>, package: &str) -> String { @@ -107,7 +107,11 @@ impl Header<'_> { .iter() .map(|v| format!("\t{upper}_{} = {},", abi::snake(&v.name).to_uppercase(), v.discriminant)) .collect(); - self.line(format!("typedef enum {name} {{\n{}\n}} {name};\n", variants.join("\n"))); + self.line(format!( + "{}typedef enum {name} {{\n{}\n}} {name};\n", + comment(&e.docs, ""), + variants.join("\n") + )); } // Value structs, each after the values it holds. @@ -139,9 +143,14 @@ impl Header<'_> { ); table.push(format!("\t{decl};")); } - self.line(format!( - "/* {}: implemented in C. Rust calls free once it drops the implementation, and\n * may call the others from any thread. */\ntypedef struct {name}_vtable {{\n{}\n}} {name}_vtable;\n\ntypedef struct {name} {{\n\tconst {name}_vtable *vtable;\n\tvoid *data;\n}} {name};\n", + let docs = format!( + "{}: implemented in C. Rust calls free once it drops the implementation, and\nmay call the others from any thread.\n\n{}", callback.path.join("::"), + callback.docs + ); + self.line(format!( + "{}typedef struct {name}_vtable {{\n{}\n}} {name}_vtable;\n\ntypedef struct {name} {{\n\tconst {name}_vtable *vtable;\n\tvoid *data;\n}} {name};\n", + comment(docs.trim(), ""), table.join("\n") )); } @@ -151,7 +160,11 @@ impl Header<'_> { Literal::Bool(b) => b.to_string(), Literal::Int(int, v) => c_literal(int, v), }; - self.line(format!("#define {} {value}", abi.constant(&constant.path))); + self.line(format!( + "{}#define {} {value}", + comment(&constant.docs, ""), + abi.constant(&constant.path) + )); } if !api.constants.is_empty() { self.line(""); @@ -159,7 +172,7 @@ impl Header<'_> { for (i, record) in api.records.iter().enumerate() { let name = abi.record(i); - self.line(format!("/* {} */", record.path.join("::"))); + self.line(format!("/* {} */", record.path.join("::")).trim_end()); self.value_functions(&name, Ty::Struct(name.clone()), record.traits, true); let owner = Ty::Struct(name.clone()); for method in &record.methods { @@ -182,7 +195,8 @@ impl Header<'_> { } for (i, object) in api.objects.iter().enumerate() { let name = abi.object(i); - self.line(format!("/* {} */", object.path.join("::"))); + let docs = format!("{}\n\n{}", object.path.join("::"), object.docs); + self.line(comment(docs.trim(), "").trim_end()); self.line(format!("void {name}_free({name} *self);")); let t = object.traits; if t.clone { @@ -244,9 +258,13 @@ impl Header<'_> { .fields .iter() .zip(&fields) - .map(|(f, ty)| format!("\t{};", self.decl(ty, &abi::escape(&f.name)))) + .map(|(f, ty)| format!("{}\t{};", comment(&f.docs, "\t"), self.decl(ty, &abi::escape(&f.name)))) .collect(); - self.line(format!("typedef struct {name} {{\n{}\n}} {name};\n", decls.join("\n"))); + self.line(format!( + "{}typedef struct {name} {{\n{}\n}} {name};\n", + comment(&record.docs, ""), + decls.join("\n") + )); return; } let Some(i) = (0..abi.api.enums.len()).find(|&i| &abi.enumeration(i) == name) else { @@ -314,6 +332,28 @@ impl Header<'_> { fn function(&mut self, function: &Function, owner: Option<&Ty>) { let export = self.abi.export(function, owner); + let mut docs = function.docs.clone(); + // What the call moves out of the caller's handles, which are then only freed. + // A handle taken by value: one taken `&mut` is not `const` either, but stays. + let receiver = function.receiver.map(|r| r == Receiver::Owned); + let by_value = receiver + .into_iter() + .chain(function.params.iter().map(|p| !matches!(p.ty, Type::Ref(..)))); + let moved: Vec = export + .call + .params + .iter() + .zip(by_value) + .filter(|((_, ty), by_value)| *by_value && matches!(ty, Ty::Handle { constant: false, .. })) + .map(|((name, _), _)| format!("`{name}`")) + .collect(); + if !moved.is_empty() { + docs.push_str(&format!( + "\n\nMoves the value out of {}: free the handle after.", + moved.join(" and ") + )); + } + self.out.push_str(&comment(docs.trim(), "")); if let Some((handle, poll, free)) = &export.future { self.line(format!("typedef struct {handle} {handle};")); let call = self.prototype(&export.call); @@ -329,6 +369,34 @@ impl Header<'_> { } } +/// 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() { + return String::new(); + } + // Neither may appear inside a C comment. + let docs = docs.replace("*/", "* /").replace("/*", "/ *"); + let lines: Vec<&str> = docs.lines().collect(); + let mut out = String::new(); + for (i, line) in lines.iter().enumerate() { + let lead = match i { + 0 => "/* ", + _ => " * ", + }; + out.push_str(indent); + out.push_str(lead.trim_end_matches(' ')); + if !line.is_empty() { + out.push(' '); + out.push_str(line); + } + if i + 1 == lines.len() { + out.push_str(" */"); + } + out.push('\n'); + } + out +} + fn has(traits: Traits) -> bool { traits.eq || traits.display || traits.debug || traits.default } diff --git a/ffi/src/census.rs b/ffi/src/census.rs index cf254dc17..67239d969 100644 --- a/ffi/src/census.rs +++ b/ffi/src/census.rs @@ -34,7 +34,11 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn }; row("Types", types, refused(&["struct", "enum", "union"])); row("Functions", api.functions.len(), refused(&["fn"])); - row("Methods of exported types", methods, refused(&["method"])); + row( + "Methods and fields of exported types", + methods, + refused(&["method", "field"]), + ); row("Traits", api.callbacks.len(), refused(&["trait"])); row("Constants", api.constants.len(), refused(&["const"])); row("Other items", 0, refused(&["use", "macro", "static", "item"])); diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index ab8203722..648721955 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -269,6 +269,7 @@ impl<'tcx> Collector<'tcx> { // Number each kind in item order, with placeholders filled in by `define`. for (def_id, path) in self.items.clone() { let span = tcx.def_span(def_id); + let docs = docs(tcx, def_id); let Some(decl) = self.decls.get_mut(&def_id) else { continue; }; @@ -279,6 +280,7 @@ impl<'tcx> Collector<'tcx> { api.records.push(Record { path, span, + docs, fields: Vec::new(), tuple: false, methods: Vec::new(), @@ -290,6 +292,7 @@ impl<'tcx> Collector<'tcx> { api.enums.push(Enum { path, span, + docs, variants: Vec::new(), exhaustive: true, methods: Vec::new(), @@ -303,6 +306,7 @@ impl<'tcx> Collector<'tcx> { api.objects.push(Object { path, span, + docs, sync, copy, methods: Vec::new(), @@ -314,6 +318,7 @@ impl<'tcx> Collector<'tcx> { api.callbacks.push(Callback { path, span, + docs, methods: Vec::new(), }); } @@ -374,6 +379,7 @@ impl<'tcx> Collector<'tcx> { match self.ty(ty, Pos::Field) { Ok(ty) => fields.push(Field { name: field.name.to_string(), + docs: docs(tcx, field.did), ty, }), Err(why) => errs.push(why), @@ -478,6 +484,7 @@ impl<'tcx> Collector<'tcx> { Ok(ty) => getters.push(Function { path: getter, span, + docs: docs(tcx, field.did), receiver: Some(Receiver::Ref), params: Vec::new(), ok: ty, @@ -689,6 +696,7 @@ impl<'tcx> Collector<'tcx> { (true, Some(ok)) => Ok(Function { path, span: tcx.def_span(def_id), + docs: docs(tcx, def_id), receiver, params, ok, @@ -878,7 +886,12 @@ impl<'tcx> Collector<'tcx> { let span = tcx.def_span(def_id); let why = match self.constant(def_id) { Ok(value) => { - self.api.constants.push(Constant { path, span, value }); + self.api.constants.push(Constant { + path, + span, + docs: docs(tcx, def_id), + value, + }); return None; } Err(why) => why, @@ -892,6 +905,7 @@ impl<'tcx> Collector<'tcx> { Ok(ok) => Some(Function { path, span, + docs: docs(tcx, def_id), receiver: None, params: Vec::new(), ok, @@ -1132,6 +1146,23 @@ fn signed<'tcx>(tcx: TyCtxt<'tcx>, ty: Ty<'tcx>, bits: u128) -> i128 { } } +/// An item's doc comment, each line as written after `///`. +fn docs(tcx: TyCtxt<'_>, def_id: DefId) -> String { + #[expect(deprecated, reason = "doc comments are no parsed attribute to find")] + let attrs = tcx.get_all_attrs(def_id); + let lines: Vec = attrs + .iter() + .filter_map(|attr| attr.doc_str()) + .flat_map(|doc| { + doc.as_str() + .lines() + .map(|line| line.strip_prefix(' ').unwrap_or(line).to_string()) + .collect::>() + }) + .collect(); + lines.join("\n").trim().to_string() +} + /// Whether the local type `def_id` implements the std trait `item`. fn implements(tcx: TyCtxt<'_>, def_id: DefId, item: rustc_span::Symbol) -> bool { let ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index 7ef2c0b12..ac92b313d 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -89,6 +89,10 @@ impl Callbacks for Export { let written = match &self.output { Output::Census(path) => { let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); + for path in abi.unused_renames() { + tcx.dcx() + .err(format!("rust2-ffi: rename `{path}` names nothing exported")); + } let text = census::render(&self.config.package, &collected, &abi.clashes, &|span| at(tcx, span)); write(path, &text) } @@ -119,6 +123,10 @@ impl Callbacks for Export { } } let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); + for path in abi.unused_renames() { + tcx.dcx() + .err(format!("rust2-ffi: rename `{path}` names nothing exported")); + } for (name, (first, first_span), (second, second_span)) in &abi.clashes { tcx.dcx() .struct_span_err( diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index 701d4366c..9ef29c26f 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -25,6 +25,7 @@ pub type Path = Vec; pub struct Record { pub path: Path, pub span: Span, + pub docs: String, pub fields: Vec, /// Whether its fields are positional, named `0`, `1`, ... pub tuple: bool, @@ -35,6 +36,7 @@ pub struct Record { pub struct Field { /// Its Rust name: a number for a positional field. pub name: String, + pub docs: String, pub ty: Type, } @@ -43,6 +45,7 @@ pub struct Field { pub struct Enum { pub path: Path, pub span: Span, + pub docs: String, pub variants: Vec, /// Whether another crate can match it without a wildcard arm. pub exhaustive: bool, @@ -70,6 +73,7 @@ impl Enum { pub struct Object { pub path: Path, pub span: Span, + pub docs: String, /// Whether it is `Sync`: if not, even its `&self` methods borrow it exclusively. pub sync: bool, /// Whether it is `Copy`: taken by value, it is copied out of its handle, as Rust @@ -83,6 +87,7 @@ pub struct Object { pub struct Callback { pub path: Path, pub span: Span, + pub docs: String, /// Its required methods, each taking `&self` or `&mut self`. pub methods: Vec, } @@ -102,6 +107,8 @@ pub struct Function { /// Its path, ending in its own name: a method's goes through its type's. pub path: Path, pub span: Span, + /// Its doc comment, as Markdown. + pub docs: String, pub receiver: Option, pub params: Vec, /// What it returns, or for a future, what the future does. @@ -151,6 +158,7 @@ pub struct Param { pub struct Constant { pub path: Path, pub span: Span, + pub docs: String, pub value: Literal, } From 6171efce01aaf6ea8dfbdfabd04a688b91270f1b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:42:38 -0700 Subject: [PATCH 10/16] feat(ffi): the exporter spike's report, bench, and quests Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- .github/workflows/nightly.yml | 20 ++++++ README.md | 1 + ffi/README.md | 115 +++++++++++++++++++++++++++++++ ffi/justfile | 18 +++++ ffi/src/abi.rs | 2 +- ffi/src/glue.rs | 11 ++- flake.nix | 2 + quest/m1/README.md | 17 ++--- quest/m1/ffi-bytes.md | 2 +- quest/m1/ffi-export-decision.md | 46 +++++++++++++ quest/m1/ffi-export-spike.md | 54 --------------- quest/m1/ffi-export.md | 33 +++++++++ quest/m1/ffi-poll-protocol.md | 2 +- quest/m1/kt-ffi-calls.md | 2 +- quest/m2/README.md | 4 +- quest/m2/ffi-async.md | 2 +- quest/m2/ffi-bytes-return.md | 2 +- quest/m2/ffi-checksums.md | 2 +- quest/m2/ffi-code-size.md | 2 +- quest/m2/uniffi-c-first-spike.md | 2 +- quest/m2/uniffi-contract.md | 2 +- 21 files changed, 264 insertions(+), 77 deletions(-) create mode 100644 ffi/README.md create mode 100644 quest/m1/ffi-export-decision.md delete mode 100644 quest/m1/ffi-export-spike.md create mode 100644 quest/m1/ffi-export.md diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index ad299a7cb..370aba46a 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -127,6 +127,26 @@ jobs: name: ffi-census path: ffi/target/census + ffi-bench: + name: Bench the C export against moq-c + runs-on: ubuntu-24.04-arm + timeout-minutes: 90 + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/nix + + # Frame writes through each C API. The numbers go in the run's summary: no threshold + # fails the job. + - name: Bench + # Named, so a failing bench fails the pipe. + shell: bash + run: nix develop .#bench --command just ffi bench | tee -a "$GITHUB_STEP_SUMMARY" + census: name: Census moq-net and kio runs-on: ubuntu-24.04-arm diff --git a/README.md b/README.md index d58878283..963219832 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ Rust to other places. - **TypeScript**: an own rustc driver that translates a [documented Rust subset](ts/README.md) to readable TypeScript, without WASM. +- **C, then any language**: an [exporter spike](ffi/README.md) that turns a crate's `pub` API into a C ABI and header with no attributes, sharing the TypeScript driver's front end. - **Any language**: [a hard fork](uniffi/README.md) of [UniFFI](https://github.com/mozilla/uniffi-rs) with every generator [moq](https://github.com/moq-dev/moq) uses. - **Faster builds**: a reproducible [build-speed benchmark](bench/build/README.md), then a pure-Rust subset (no build scripts, no C linking) that builds faster. diff --git a/ffi/README.md b/ffi/README.md new file mode 100644 index 000000000..02cf016f2 --- /dev/null +++ b/ffi/README.md @@ -0,0 +1,115 @@ +# rust2-ffi + +A rustc driver that exports a crate's `pub` API as a C ABI and a C header, with no +attributes in the Rust source. A spike: it answers whether such an exporter can replace +[the UniFFI fork](../uniffi/README.md) for moq, starting from C. + +```bash +rust2-ffi --config ffi.toml (--out dir | --census file.md) [--manifest-path Cargo.toml] [-- cargo args] +``` + +It runs `cargo check` on the package with itself as `RUSTC_WRAPPER`, on the host, through +the front end it shares with [rust2-ts](../ts/README.md) in [`driver/`](../driver). Once +rustc has checked the configured library, it walks every `pub` item reachable from the +crate root and exports it by fixed rules, or refuses it with a compile error at its span. +`--out` writes a crate of `extern "C"` functions over the library, its runtime beside it, +and the header in `include/.h`; `cargo build` on that crate makes a static and a +shared library. + +```toml +# ffi.toml, beside the package's Cargo.toml unless --manifest-path says otherwise. +package = "moq-net" +# The prefix of every C name, the crate name by default. +prefix = "moq" +# Paths from the crate root left out: a module, an item, or one method or field. Each +# must name something exported. Nothing else leaves an item out. +exclude = ["track::Producer::poll_closed"] + +# C names, without the prefix, for paths whose names the naming rule makes clash. +[rename] +"session::Stats" = "session_stats_snapshot" +``` + +## Rules + +Every `pub` item reachable from the crate root, by its shortest path, is exported or +refused. `#[doc(hidden)]` items are no part of the API and are left out; type aliases +export nothing of their own. + +| Rust | C | +| --- | --- | +| a struct whose fields are all `pub`, not `#[non_exhaustive]`, and which map | a record: a struct, copied across | +| an enum whose fields map | a C enum without fields, or a struct of a tag and a union | +| any other type, if `Send` | an object: an opaque handle to an `Arc`, freed with `_free` | +| a `pub` field of an object | a getter returning a copy | +| a `pub` trait | a callback interface: a table of C functions and their data | +| `fn` and inherent `pub` methods | functions named through their type | +| `Result` | `bool f(..., T *out, E *err)` | +| `async fn`, or a return that implements `Future` | a future: `f` makes it, `f_poll` polls it, `f_future_free` drops it | +| `bool`, integers but 128-bit, floats, `char` | `bool`, `` types, `float`, `double`, a `uint32_t` code point | +| `&str`, `String`, `&[u8]`, `Vec`, `bytes::Bytes` | `_buf`: a view passed in, an owned buffer returned | +| `Duration` | `_duration` | +| `Option` | a null handle or buffer, or `_option_` | +| a `pub const` | a `#define` if a `bool` or integer, else a function returning it | +| `impl Into`, `impl AsRef` | `X` | +| another type parameter | the first of `String`, `Bytes`, and `Vec` meeting its bounds, or a foreign implementation of its one exported trait | + +A record or enum holds only values and `Copy` handles: one with a field that does not map +is an object instead, and the census lists it. Everything else is refused, and the census +counts why. + +## The C ABI + +- **Handles** are `Arc`s, and a call borrows the value as Rust's receiver or parameter + does, checked at run time: shared for `&T`, exclusive for `&mut T`, and moved out for + `T`, after which the handle is only freed. A `Copy` value is copied out instead, and a + value that is not `Sync` is borrowed exclusively even through `&T`. A borrow Rust would + refuse at compile time aborts, naming the function, as does a null or moved-out handle: + there is no Rust caller to return an error to. +- **Values** are copied in from the caller's memory, which Rust never frees, and lowered + into memory the caller frees once with the type's `_free`. +- **Futures** run no runtime: C polls with a `_waker` and polls again when woken. + A poll that finishes writes the result through the poll's own out pointers, so a + cancelled read never loses a value. The future reuses the last waker when given the same + one again, and owns what it borrowed: the handle it was called on stays borrowed until + it finishes or is freed. +- **Callbacks** are a struct of a table and its data. Rust calls `free` once it drops the + implementation, and may call the others from any thread. A callback takes scalars and + buffers lent for the call, and returns a scalar. +- **Panics** abort, as an `extern "C"` function's do. +- **Names** are the prefix, then the item's path from the crate root, each segment in + snake case, joined by `_`: `track::Producer::append_group` is + `moq_track_producer_append_group`. Joining loses where segments split, so every C name + is registered, and two items claiming one is a compile error at both spans, fixed by a + `rename`: moq-net's `session::Stats` and `Session::stats` are both `moq_session_stats`. + +## IR + +[`src/ir.rs`](src/ir.rs) is the API as each generator reads it, with no language decided: +records, enums, objects, callbacks, functions, and constants, each by its path from the +crate root, 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). + +## Census + +`--census file.md` exports nothing. It counts what exports and ranks every refusal by +construct and by the type it names, lists each refused item at its span, and ends with +the `exclude` list that exports the rest. It ignores the config's `exclude`. + +## Tests + +```bash +just ffi test # export the fixtures, build them, and drive api from C +just ffi moq # export moq-net at the pinned revision, build it, and run moq/moq.c +just ffi census # census moq-net into target/census +nix develop .#bench --command just ffi bench # frame writes, through the export and moq's rs/moq-c +``` + +The `api` fixture covers each rule once. `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` +fixture's expected errors are `fixtures/reject/expected.txt`. moq-net's `moq/moq.c` +publishes and subscribes to a track in one process, polling each read. diff --git a/ffi/justfile b/ffi/justfile index 148de7ef8..24f3501d1 100644 --- a/ffi/justfile +++ b/ffi/justfile @@ -47,6 +47,24 @@ census checkout="": fi cargo run --locked --quiet -- --config moq/ffi.toml --manifest-path "$src/rs/moq-net/Cargo.toml" --census target/census/moq-net.md +# Time frame writes through the export 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 + [ -n "${LIBCLANG_PATH:-}" ] || { echo "LIBCLANG_PATH is unset: run this in the bench shell, nix develop .#bench" >&2; exit 1; } + src="{{ checkout }}" + [ -n "$src" ] || src=../ts/target/moq + out=target/export/moq + # moq-c's header is written to its build script's output directory. + moqc=$(cd "$src" && cargo build --locked --quiet --release --package moq-c --message-format=json \ + | 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 + for _ in 1 2 3; do + target/bench-moq-c + target/bench-export + done + # Export moq-net's C ABI, build it, and run moq/moq.c against it, from the moq revision `just ts moq` pins or a checkout. moq checkout="": #!/usr/bin/env bash diff --git a/ffi/src/abi.rs b/ffi/src/abi.rs index e1019b6c1..918044468 100644 --- a/ffi/src/abi.rs +++ b/ffi/src/abi.rs @@ -480,7 +480,7 @@ pub fn escape(name: &str) -> String { "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", + "volatile", "while", "out", "err", "future", "waker", "data", ]; match KEYWORDS.contains(&name) || name.chars().next().is_some_and(|c| c.is_ascii_digit()) { true => format!("_{name}"), diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 04b9a778d..4a43fc386 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -153,9 +153,14 @@ impl Gen<'_> { true => format!("lift_{}({e}, w)", self.abi.enumeration(*i)), false => format!("lift_{}(&{e}, w)", self.abi.enumeration(*i)), }, - Type::Object(i) => match self.abi.api.objects[*i].copy { - true => format!("*unsafe {{ rt::Object::<{}>::borrow({e}, w) }}", self.object_path(*i)), - false => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), + // A value that is not `Sync` may change through `&self`, so it is read exclusively. + Type::Object(i) => match (self.abi.api.objects[*i].copy, self.abi.api.objects[*i].sync) { + (true, true) => format!("*unsafe {{ rt::Object::<{}>::borrow({e}, w) }}", self.object_path(*i)), + (true, false) => format!( + "*unsafe {{ rt::Object::<{}>::borrow_mut({e}, w) }}", + self.object_path(*i) + ), + (false, _) => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), }, Type::Callback(i, form) => abi::dyn_wrap(*form, &format!("Foreign_{}({e})", self.abi.callback(*i))), } diff --git a/flake.nix b/flake.nix index 60d8441d1..87e9575a6 100644 --- a/flake.nix +++ b/flake.nix @@ -193,6 +193,8 @@ pkgs.chromium pkgs.wasm-bindgen-cli ]; + # `just ffi bench` builds moq's rs/moq-c, whose VAAPI bindings run bindgen. + LIBCLANG_PATH = "${pkgs.llvmPackages.libclang.lib}/lib"; }); # Every foreign toolchain the UniFFI fixture suite runs, apart for their size. devShells.uniffi = self.devShells.${system}.default.overrideAttrs (old: { diff --git a/quest/m1/README.md b/quest/m1/README.md index 49f7795d2..0fdebb01c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -3,22 +3,23 @@ ## Goal The work moq is waiting on: the UniFFI fork its bindings switch to, the exporter -spike that may replace it, and the fork's perf work moq planned. +that may replace it, and the fork's perf work moq planned. ## Plan -Decided with the maintainer on 2026-10-24: an [exporter](/quest/m1/ffi-export-spike.md) -that turns a crate's `pub` API into bindings, with no attributes, may replace the UniFFI -fork. The fork stays in maintenance and keeps building moq's bindings; its feature -quests, here and in m2, pause until the spike reports, which decides whether each is -folded into the exporter. The spike sits in m1 because it blocks them. The binding -benchmark continues as the exporter's baseline. +Decided with the maintainer on 2026-10-24: an [exporter](/ffi/README.md) that turns a +crate's `pub` API into bindings, with no attributes, may replace the UniFFI fork. The fork +stays in maintenance and keeps building moq's bindings; its feature quests, here and in +m2, pause until the [decision](/quest/m1/ffi-export-decision.md) the spike's report asks +for, which decides whether each is folded into the exporter. The binding benchmark +continues as the exporter's baseline. ## Required - [Waiting: publish the UniFFI fork](/quest/m1/uniffi-release.md) - the fork publishes to crates.io under `rust2-*` names, once the maintainer decides it should - [Binding benchmark](/quest/m1/ffi-bench.md) - moq's `bench-ffi` moves here and measures every wrapper against the fork, nightly -- [Exporter spike](/quest/m1/ffi-export-spike.md) - moq-net's `pub` API exported to a C ABI and header by a rustc driver, with refusals counted and compared against moq's `rs/moq-c` +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - the maintainer decides from the spike's report whether the exporter replaces the UniFFI fork +- [Exporter](/quest/m1/ffi-export.md) - moq's bindings exported from its crates' `pub` API, if adopted - [Payload bytes](/quest/m1/ffi-bytes.md) - payloads cross the FFI in bulk copies, proven in every wrapper - [Kotlin calls](/quest/m1/kt-ffi-calls.md) - Kotlin calls cost about what Python's and Go's do, starting from upstream's JNI bindgen - [Waiting: moq's poll-native async](/quest/m1/moq-poll-migrate.md) - condition: moq's `ffi-poll-migrate` quest has landed diff --git a/quest/m1/ffi-bytes.md b/quest/m1/ffi-bytes.md index dde7b0503..2a892348c 100644 --- a/quest/m1/ffi-bytes.md +++ b/quest/m1/ffi-bytes.md @@ -49,5 +49,5 @@ Public API: none unless `&[u8]` lands, which changes Kotlin's parameter type. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m1/ffi-export-decision.md b/quest/m1/ffi-export-decision.md new file mode 100644 index 000000000..dbcf8edb4 --- /dev/null +++ b/quest/m1/ffi-export-decision.md @@ -0,0 +1,46 @@ +# [XS] Waiting: decide whether the exporter replaces the UniFFI fork + +## Goal + +The maintainer decides, from [the exporter spike's report](https://github.com/kixelated/rust2/pull/41), +whether [rust2-ffi](/ffi/README.md) replaces [the UniFFI fork](/uniffi/README.md) for moq, +and so whether the fork's paused feature quests fold into it. Check: ask the maintainer. +Delete this quest once decided, rescoping or deleting each quest that requires it. + +## Plan + +The spike's recommendation: adopt the exporter, and fold every paused quest into it. + +- It exports 87% of moq-net's types and 81% of their methods and fields with no + attributes, and its C test publishes and subscribes to a track against the real + library, with every read a polled future. Four more rules (tuples as out parameters, + `Path<'static>`, a clone for a borrowed `Clone` return, and `Range`) cover most of the + rest; the `poll_*` methods with an async twin are 39 of the 112 refused methods. +- Its frame writes cost what moq's hand-written `rs/moq-c` does (within 5%, the rest a + timestamp's handle), so call overhead is no reason to keep a wrapper. +- What moq-ffi adds over moq-net is mostly other crates (sessions over moq-native, media + over hang and the codecs) and a runtime to drive sessions, not reshaping moq-net. + +Each paused quest, if adopted: + +- [C-first bindings spike](/quest/m2/uniffi-c-first-spike.md): done in kind. The export is + C with nothing underneath, callbacks are C, and the name clash is refused at both spans + with a `rename` to fix it. C++ per standard layers on its C ABI, as a generator. +- [Namespaced contract](/quest/m2/uniffi-contract.md) and [checksums](/quest/m2/ffi-checksums.md): + the export has neither. A header and library from different builds still mix silently, + so the exporter needs one contract symbol per build, checked at load. +- [Payload bytes](/quest/m1/ffi-bytes.md) and [zero-copy returns](/quest/m2/ffi-bytes-return.md): + done at the C ABI. A sync call borrows a payload argument with no copy, and a returned + `Bytes` is handed over without one; each language's generator must keep that. +- [Cheaper async](/quest/m2/ffi-async.md) and [foreign poll](/quest/m1/ffi-poll-protocol.md): + a future ready on its first poll costs three crossings (call, poll, free), not UniFFI's + five, and the poll that finishes writes the result, so a cancel never loses a frame. A + repeated waker is reused, not re-registered. Left: a future handle per read. +- [Code size](/quest/m2/ffi-code-size.md): moq-net's header is 1003 functions, 99 KB + without its docs; measure per language once generators exist. +- [Kotlin calls](/quest/m1/kt-ffi-calls.md): JNI or Panama becomes the Kotlin generator's + choice over the C ABI, rather than a patch to the fork's JNA bindings. + +## Related + +- [Exporter](/quest/m1/ffi-export.md) - the work that follows, if adopted diff --git a/quest/m1/ffi-export-spike.md b/quest/m1/ffi-export-spike.md deleted file mode 100644 index 77691173a..000000000 --- a/quest/m1/ffi-export-spike.md +++ /dev/null @@ -1,54 +0,0 @@ -# [L] Exporter spike: a crate's pub API to C - -## Goal - -A prototype exporter turns a crate's `pub` API into a C ABI and a C header, with no -attributes in the Rust source. It runs on moq-net's public API directly, not moq-ffi, -and its report counts every refusal, which shows how much of the moq-ffi wrapper crate -is really needed. It compares the C output with moq's hand-written `rs/moq-c`, and -decides whether the exporter replaces [the UniFFI fork](/uniffi/README.md) and what -becomes of the fork feature quests paused behind it. - -## Plan - -Decided with the maintainer on 2026-10-24: replace UniFFI's macros with an opinionated -Rust-to-language exporter. A crate's `pub` API alone defines what gets exported, with no -`#[uniffi::export]` attributes. - -- **Source**: a rustc driver, reusing [rust2-ts](/ts/README.md)'s driver infrastructure - on the same pinned nightly, so types, visibility, and trait impls come from the - compiler. Chosen over rustdoc JSON and parsing the source. -- **Output**: its own IR and its own generators, not UniFFI metadata. -- **Opinions**: every `pub` item reachable from the crate root is exported by fixed - rules: - - a struct whose fields are all `pub` becomes a record, and other types become - objects behind `Arc`; - - `Result` becomes errors; - - `async fn` becomes a future; - - `pub` traits become callback interfaces. - - Anything that doesn't map is a compile error with a source span, unless a config file - excludes it. Nothing is skipped silently, and nothing is opted in by attribute. -- **Target**: moq-net's public API, at a pinned moq revision as `just ts moq` pins one. - The refusal count is the measure of what a wrapper crate still has to add. -- **First output**: a C ABI plus a C header, matching the earlier C-first decision: - every other language layers on that one ABI later. Compare it against moq's - hand-written `rs/moq-c`. -- **The UniFFI fork**: spike first, with the fork in maintenance. New fork features - pause behind this spike: the [C-first bindings spike](/quest/m2/uniffi-c-first-spike.md), - the [namespaced contract](/quest/m2/uniffi-contract.md), and the perf quests - ([payload bytes](/quest/m1/ffi-bytes.md), - [zero-copy returns](/quest/m2/ffi-bytes-return.md), - [cheaper async](/quest/m2/ffi-async.md), - [checksums](/quest/m2/ffi-checksums.md), - [code size](/quest/m2/ffi-code-size.md), - [Kotlin calls](/quest/m1/kt-ffi-calls.md), and - [foreign poll](/quest/m1/ffi-poll-protocol.md)). Their findings feed the exporter's - design, and the report says, for each, whether it is folded into the exporter. The - fork keeps building moq's bindings until the exporter replaces it. - -Public API: a new tool. - -## Related - -- [Binding benchmark](/quest/m1/ffi-bench.md) - continues, as the baseline the exporter is measured against diff --git a/quest/m1/ffi-export.md b/quest/m1/ffi-export.md new file mode 100644 index 000000000..a60262633 --- /dev/null +++ b/quest/m1/ffi-export.md @@ -0,0 +1,33 @@ +# [XL] Exporter: moq's bindings from its crates' pub API + +## Goal + +[rust2-ffi](/ffi/README.md) exports what moq's bindings need from moq's own crates, with +no attributes and no hand-written wrapper beyond what the census shows is genuinely new +API, and generates the languages moq ships on its C ABI. moq-ffi shrinks to that remainder. + +## Plan + +From the spike ([kixelated/rust2#41](https://github.com/kixelated/rust2/pull/41)); split +into quests once the decision lands, ranked by what the census refuses: + +- **Rules the census asks for**: tuples as out parameters (`origin::Producer::new`, so an + origin can be made), `Path<'a>` exported as `Path<'static>`, a clone for a borrowed + return of a `Clone` object (the 21 `info()` getters), `Range` and `RangeBounds`, + and a policy for `poll_*` methods: 39 of 46 have an async twin, which may make them + redundant, or the poll protocol may want them in place of the twin. +- **Several crates**: moq-native's sessions and the media crates are where moq-ffi's + remaining API lives. Export each with its own census, naming another export's types + across crates, as moq-pattern's re-exports already need. +- **Driving**: sessions and origins run a `Driver` polled with a time and a `kio::Waiter`. + Decide between exporting that poll, a generated thread that drives it, or moq-native's + runtime helpers. +- **A contract symbol** per build, so a header and a library from different builds refuse + to load together. +- **Generators**: the IR holds what each language needs (paths, docs, receivers, exact + borrow forms). Start with the language whose binding costs moq the most today, measured + on the [binding benchmark](/quest/m1/ffi-bench.md). + +## Required + +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - whether the exporter replaces the UniFFI fork diff --git a/quest/m1/ffi-poll-protocol.md b/quest/m1/ffi-poll-protocol.md index 3f6aaf0c0..16b7f889a 100644 --- a/quest/m1/ffi-poll-protocol.md +++ b/quest/m1/ffi-poll-protocol.md @@ -73,7 +73,7 @@ terminal to per-read. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Binding benchmark](/quest/m1/ffi-bench.md) - the numbers every wrapper is measured on - [moq's poll-native async](/quest/m1/moq-poll-migrate.md) - the kio poll each export wraps, with `ffi::Task` gone diff --git a/quest/m1/kt-ffi-calls.md b/quest/m1/kt-ffi-calls.md index a9930c2ed..b75c2551f 100644 --- a/quest/m1/kt-ffi-calls.md +++ b/quest/m1/kt-ffi-calls.md @@ -41,5 +41,5 @@ Public API: none expected. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m2/README.md b/quest/m2/README.md index e9019d67b..8a2c16113 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -16,8 +16,8 @@ Decided with the maintainer on 2026-10-24: the translator's output ranks correct then speed, then the size of the consumer's final tree-shaken, minified JS; readability is not a goal, and types must be solid at the API boundary ([design](/ts/README.md#design)). -The fork's feature quests here pause until the [exporter spike](/quest/m1/ffi-export-spike.md) -reports; [m1](/quest/m1/README.md#plan) records the decision. +The fork's feature quests here pause until the [exporter decision](/quest/m1/ffi-export-decision.md); +[m1](/quest/m1/README.md#plan) records why. ## Required diff --git a/quest/m2/ffi-async.md b/quest/m2/ffi-async.md index f2d73a350..83ac484a4 100644 --- a/quest/m2/ffi-async.md +++ b/quest/m2/ffi-async.md @@ -25,5 +25,5 @@ Public API: none expected. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Foreign poll for hot reads](/quest/m1/ffi-poll-protocol.md) - the waker design this reuses diff --git a/quest/m2/ffi-bytes-return.md b/quest/m2/ffi-bytes-return.md index 84ddc7939..e33578c1e 100644 --- a/quest/m2/ffi-bytes-return.md +++ b/quest/m2/ffi-bytes-return.md @@ -25,5 +25,5 @@ Public API: returned payload types may change per language. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Payload bytes](/quest/m1/ffi-bytes.md) - the numbers that justify it diff --git a/quest/m2/ffi-checksums.md b/quest/m2/ffi-checksums.md index 974384d89..809511fdd 100644 --- a/quest/m2/ffi-checksums.md +++ b/quest/m2/ffi-checksums.md @@ -20,6 +20,6 @@ Public API: none; generated bindings lose their checksum calls. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Namespaced FFI contract](/quest/m2/uniffi-contract.md) - what refuses a mismatched library once the checksums are gone - [Binding benchmark](/quest/m1/ffi-bench.md) - load time, size, and symbol numbers diff --git a/quest/m2/ffi-code-size.md b/quest/m2/ffi-code-size.md index 9f8fa2796..b5f66d99c 100644 --- a/quest/m2/ffi-code-size.md +++ b/quest/m2/ffi-code-size.md @@ -18,5 +18,5 @@ Public API: generated code changes shape; wrapper APIs do not. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - [Binding benchmark](/quest/m1/ffi-bench.md) - the size report diff --git a/quest/m2/uniffi-c-first-spike.md b/quest/m2/uniffi-c-first-spike.md index 76e7755db..0fc02a610 100644 --- a/quest/m2/uniffi-c-first-spike.md +++ b/quest/m2/uniffi-c-first-spike.md @@ -44,7 +44,7 @@ generator with two error styles that each support only part of UniFFI: ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends ## Related diff --git a/quest/m2/uniffi-contract.md b/quest/m2/uniffi-contract.md index 87092e962..1ddd8682e 100644 --- a/quest/m2/uniffi-contract.md +++ b/quest/m2/uniffi-contract.md @@ -29,4 +29,4 @@ contract symbol. ## Required -- [Exporter spike](/quest/m1/ffi-export-spike.md) - this quest is paused until the spike reports, and may be folded into the exporter +- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends From bc870057876b147eccca5687103364a358e964c9 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 21:20:40 -0700 Subject: [PATCH 11/16] fix(ffi): call eager futures at once, make recursive values objects, leave out poll twins; fold the paused quests Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- README.md | 2 +- ffi/README.md | 14 ++-- ffi/fixtures/api/examples/transcript.rs | 15 +++- ffi/fixtures/api/ffi.toml | 2 + ffi/fixtures/api/src/lib.rs | 43 ++++++++++ ffi/fixtures/reject/expected.txt | 9 +- ffi/fixtures/reject/src/lib.rs | 7 ++ ffi/moq/ffi.toml | 42 +--------- ffi/src/census.rs | 14 +++- ffi/src/collect.rs | 104 ++++++++++++++++++++++-- ffi/src/glue.rs | 11 ++- ffi/src/ir.rs | 3 + ffi/tests/api.c | 16 +++- quest/m1/README.md | 23 ++---- quest/m1/ffi-bench.md | 2 +- quest/m1/ffi-bytes.md | 53 ------------ quest/m1/ffi-export-decision.md | 46 ----------- quest/m1/ffi-export.md | 54 +++++++----- quest/m1/ffi-poll-protocol.md | 82 ------------------- quest/m1/kt-ffi-calls.md | 45 ---------- quest/m1/moq-poll-migrate.md | 16 ---- quest/m2/README.md | 8 +- quest/m2/ffi-async.md | 29 ------- quest/m2/ffi-bytes-return.md | 29 ------- quest/m2/ffi-checksums.md | 25 ------ quest/m2/ffi-code-size.md | 22 ----- quest/m2/uniffi-c-first-spike.md | 51 ------------ quest/m2/uniffi-contract.md | 32 -------- 28 files changed, 265 insertions(+), 534 deletions(-) delete mode 100644 quest/m1/ffi-bytes.md delete mode 100644 quest/m1/ffi-export-decision.md delete mode 100644 quest/m1/ffi-poll-protocol.md delete mode 100644 quest/m1/kt-ffi-calls.md delete mode 100644 quest/m1/moq-poll-migrate.md delete mode 100644 quest/m2/ffi-async.md delete mode 100644 quest/m2/ffi-bytes-return.md delete mode 100644 quest/m2/ffi-checksums.md delete mode 100644 quest/m2/ffi-code-size.md delete mode 100644 quest/m2/uniffi-c-first-spike.md delete mode 100644 quest/m2/uniffi-contract.md diff --git a/README.md b/README.md index 963219832..fd0e7a4b9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Rust to other places. - **TypeScript**: an own rustc driver that translates a [documented Rust subset](ts/README.md) to readable TypeScript, without WASM. -- **C, then any language**: an [exporter spike](ffi/README.md) that turns a crate's `pub` API into a C ABI and header with no attributes, sharing the TypeScript driver's front end. +- **C, then any language**: an [exporter](ffi/README.md) that turns a crate's `pub` API into a C ABI and header with no attributes, sharing the TypeScript driver's front end. - **Any language**: [a hard fork](uniffi/README.md) of [UniFFI](https://github.com/mozilla/uniffi-rs) with every generator [moq](https://github.com/moq-dev/moq) uses. - **Faster builds**: a reproducible [build-speed benchmark](bench/build/README.md), then a pure-Rust subset (no build scripts, no C linking) that builds faster. diff --git a/ffi/README.md b/ffi/README.md index 02cf016f2..17a49dde2 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -1,8 +1,8 @@ # rust2-ffi A rustc driver that exports a crate's `pub` API as a C ABI and a C header, with no -attributes in the Rust source. A spike: it answers whether such an exporter can replace -[the UniFFI fork](../uniffi/README.md) for moq, starting from C. +attributes in the Rust source. It replaces [the UniFFI fork](../uniffi/README.md) for moq, +starting from C, which every other language's generator will build on. ```bash rust2-ffi --config ffi.toml (--out dir | --census file.md) [--manifest-path Cargo.toml] [-- cargo args] @@ -45,7 +45,8 @@ export nothing of their own. | a `pub` trait | a callback interface: a table of C functions and their data | | `fn` and inherent `pub` methods | functions named through their type | | `Result` | `bool f(..., T *out, E *err)` | -| `async fn`, or a return that implements `Future` | a future: `f` makes it, `f_poll` polls it, `f_future_free` drops it | +| `async fn`, or a return that implements `Future` | a future: `f` makes it, `f_poll` polls it, `f_future_free` drops it; a function that is not `async` runs at the call, as in Rust | +| `poll_x`, when `x` exports as a future | left out: the future is its poll | | `bool`, integers but 128-bit, floats, `char` | `bool`, `` types, `float`, `double`, a `uint32_t` code point | | `&str`, `String`, `&[u8]`, `Vec`, `bytes::Bytes` | `_buf`: a view passed in, an owned buffer returned | | `Duration` | `_duration` | @@ -54,9 +55,10 @@ export nothing of their own. | `impl Into`, `impl AsRef` | `X` | | another type parameter | the first of `String`, `Bytes`, and `Vec` meeting its bounds, or a foreign implementation of its one exported trait | -A record or enum holds only values and `Copy` handles: one with a field that does not map -is an object instead, and the census lists it. Everything else is refused, and the census -counts why. +A record or enum holds only values and `Copy` handles: one with a field that does not map, +or that holds itself, is an object instead, and the census lists it. A borrowed return is +returned as a copy, so it must be `Clone` and hold no other handle, whose clone would be a +new one. Everything else is refused, and the census counts why. ## The C ABI diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index d605bba60..86169864c 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -7,7 +7,7 @@ use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use std::task::{Context, Poll, Wake, Waker}; -use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Point, Shape, Stamp}; +use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Node, Point, Shape, Stamp}; use bytes::Bytes; /// Keeps even levels, as `tests/api.c`'s implementation does. @@ -110,4 +110,17 @@ fn main() { Poll::Ready(Err(e)) => println!("nonempty err {e}"), Poll::Pending => println!("nonempty pending"), } + + // The send happens at the call: the future is dropped unpolled. + drop(channel.send_later(Bytes::from_static(b"eager"))); + let mut recv = pin!(channel.recv()); + if let Poll::Ready(payload) = recv.as_mut().poll(&mut cx) { + println!("recv {}", String::from_utf8_lossy(&payload)); + } + + let list = Node { + value: 1, + next: Some(Box::new(Node { value: 2, next: None })), + }; + println!("node {}", list.sum()); } diff --git a/ffi/fixtures/api/ffi.toml b/ffi/fixtures/api/ffi.toml index 1c73c98f6..0fc9046e6 100644 --- a/ffi/fixtures/api/ffi.toml +++ b/ffi/fixtures/api/ffi.toml @@ -1,2 +1,4 @@ package = "api-fixture" prefix = "api" +# A copy of the list's tail would be a new handle, so its getter is refused. +exclude = ["Node::next"] diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index b9f9c59e6..f1575896d 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -164,6 +164,25 @@ impl Channel { .await } + /// Sends at once, as a function that is not `async` runs when called, and returns a + /// future that borrows nothing. + pub fn send_later(&self, payload: Bytes) -> impl Future + use<> { + self.send(payload); + std::future::ready(()) + } + + /// `recv`'s poll, which does not map: left out, since `recv` exports as a future. + pub fn poll_recv(&self, cx: &mut std::task::Context<'_>) -> Poll { + let mut state = self.state.lock().unwrap(); + match state.0.take() { + Some(payload) => Poll::Ready(payload), + None => { + state.1 = Some(cx.waker().clone()); + Poll::Pending + } + } + } + /// Fails once the payload is empty. pub async fn recv_nonempty(&self) -> Result { match self.recv().await { @@ -242,6 +261,30 @@ impl Logger { } } +/// A list: every field is `pub`, but it holds itself, which C cannot hold in place, so it +/// is an object. +#[derive(Debug)] +pub struct Node { + pub value: u64, + pub next: Option>, +} + +impl Node { + pub fn new(value: u64, next: Option>) -> Self { + Self { value, next } + } + + /// Prepend `value`. + pub fn push(&mut self, value: u64) { + let rest = std::mem::replace(self, Node { value, next: None }); + self.next = Some(Box::new(rest)); + } + + pub fn sum(&self) -> u64 { + self.value + self.next.as_ref().map_or(0, |next| next.sum()) + } +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 52f9b732e..b5dc7fe37 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -1,8 +1,9 @@ fixtures/reject/src/lib.rs:14:1: rust2-ffi: cannot export fn `map`: foreign type `std::collections::HashMap`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:24:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:28:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:36:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:47:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C +fixtures/reject/src/lib.rs:26:1: rust2-ffi: cannot export fn `borrowing`: borrowing future from a function that is not async; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:35:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:43:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:54:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C fixtures/reject/src/lib.rs:6:1: rust2-ffi: cannot export struct `Wrap`: generic type; exclude it in the config to leave it out fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclude it in the config to leave it out diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs index 2f4273745..06e2468ad 100644 --- a/ffi/fixtures/reject/src/lib.rs +++ b/ffi/fixtures/reject/src/lib.rs @@ -20,6 +20,13 @@ pub fn generic(value: T) -> T { value } +/// A future that borrows its argument, from a function that runs when called: the export +/// would have to keep the argument alive past the call. +#[allow(clippy::manual_async_fn, reason = "the construct under test")] +pub fn borrowing(name: &str) -> impl Future + '_ { + async move { name.len() } +} + /// A static. pub static COUNT: u8 = 0; diff --git a/ffi/moq/ffi.toml b/ffi/moq/ffi.toml index 998a5ee24..8e1bb5d06 100644 --- a/ffi/moq/ffi.toml +++ b/ffi/moq/ffi.toml @@ -33,61 +33,37 @@ exclude = [ "announce::Announce::prefix", "announce::Announce::route", "announce::Consumer::absolute", - "announce::Consumer::poll_next", - "announce::Consumer::poll_synced", "announce::Consumer::root", - "announce::Follow::poll_next", - "announce::Follow::poll_synced", "auth::Grant::expires", "auth::Grant::publish", "auth::Grant::subscribe", - "auth::Requests::poll_next", - "auth::Watch::poll_changed", - "bandwidth::Consumer::poll_changed", - "bandwidth::Producer::poll_unused", - "bandwidth::Producer::poll_used", "broadcast::Consumer::info", - "broadcast::Consumer::poll_closed", - "broadcast::Demand::poll_unused", - "broadcast::Demand::poll_used", "broadcast::Dynamic::info", - "broadcast::Dynamic::poll_closed", - "broadcast::Dynamic::poll_requested_track", "broadcast::Finish::poll_closed", + "broadcast::Info::epoch", "broadcast::Info::path", "broadcast::Info::pool", "broadcast::Lister::poll_unused", "broadcast::Lister::poll_used", "broadcast::Producer::info", "broadcast::Tracks::broadcast", - "broadcast::Tracks::poll_next", "bytes", "cache::Pool::gc", "frame::Buffer", - "frame::Consumer::poll_read_all", - "frame::Consumer::poll_read_chunk", "frame::Frame::arrived", "frame::Producer::group", "goaway::Consumer::poll", - "group::Consumer::poll_finished", - "group::Consumer::poll_next_frame", - "group::Consumer::poll_read_frame", "group::Consumer::poll_read_frames", "group::Consumer::read_frames", "group::Consumer::set_frames", - "group::Demand::poll_unused", - "group::Demand::poll_used", - "group::Producer::poll_closed", "group::Producer::write_frames", "kio", - "origin::AnnouncedBroadcast::poll_available", "origin::Config::pool", "origin::Consumer::absolute", "origin::Consumer::allowed", "origin::Consumer::root", "origin::Consumer::scope", "origin::Driver::poll", - "origin::Dynamic::poll_requested_broadcast", "origin::Prepared::broadcast", "origin::Producer::absolute", "origin::Producer::allowed", @@ -96,6 +72,8 @@ exclude = [ "origin::Producer::scope", "origin::Request::path", "origin::Requesting::poll_ok", + "origin::Route::auth", + "origin::Route::epoch", "origin::Route::hops", "path::Relative", "path::Segment", @@ -124,31 +102,17 @@ exclude = [ "time::now", "time::run", "track::Consumer::broadcast", - "track::Consumer::poll_largest", - "track::Demand::poll_wanted_changed", - "track::Dynamic::poll_requested_group", "track::Ordered::broadcast", "track::Ordered::info", - "track::Ordered::poll_finished", - "track::Ordered::poll_largest", - "track::Ordered::poll_next_group", - "track::Ordered::poll_recv_datagram", "track::Ordered::set_groups", "track::Position::group_end", "track::Producer::broadcast", "track::Producer::drop_groups", "track::Producer::info", - "track::Producer::poll_closed", - "track::Producer::poll_subscription_changed", "track::Querying::poll_ok", "track::Range::groups", - "track::Request::poll_subscription_changed", "track::Subscriber::broadcast", "track::Subscriber::info", - "track::Subscriber::poll_finished", - "track::Subscriber::poll_largest", - "track::Subscriber::poll_recv_datagram", - "track::Subscriber::poll_recv_group", "track::Subscriber::set_groups", "track::Subscribing::poll_ok", "track::Subscription::ranges", diff --git a/ffi/src/census.rs b/ffi/src/census.rs index 67239d969..4c20bd065 100644 --- a/ffi/src/census.rs +++ b/ffi/src/census.rs @@ -44,10 +44,11 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn row("Other items", 0, refused(&["use", "macro", "static", "item"])); let _ = writeln!( out, - "\nExported types: {} records, {} enums, {} objects. A refused type's methods are not counted.", + "\nExported types: {} records, {} enums, {} objects. A refused type's methods are not counted, nor are the {} `poll_*` methods left out for their async twins.", api.records.len(), api.enums.len(), - api.objects.len() + api.objects.len(), + collected.twins.len() ); // Each item counts once per construct, however many times it hits it. @@ -146,6 +147,15 @@ pub fn render(krate: &str, collected: &Collected, clashes: &[Clash], at: &dyn Fn let _ = writeln!(out, "- `{path}`: {} `{}`", why.construct, why.detail); } } + if !collected.twins.is_empty() { + let _ = writeln!( + out, + "\n## `poll_*` methods left out, since their async twin exports as a future\n" + ); + for path in &collected.twins { + let _ = writeln!(out, "- `{path}`"); + } + } if !collected.excluded.is_empty() { let _ = writeln!(out, "\n## Excluded by the config\n"); for (path, count) in &collected.excluded { diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 648721955..cb1e97fe6 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -52,6 +52,8 @@ pub struct Collected { pub refusals: Vec, /// Records and enums exported as objects, since a field does not map: the first. pub opaque: Vec<(String, Why)>, + /// `poll_x` methods that do not map, left out since `x` exports as a future. + pub twins: Vec, /// `#[doc(hidden)]` items, by path. pub hidden: Vec, /// Excluded paths, and how many items each left out. @@ -85,6 +87,7 @@ struct Collector<'tcx> { /// implementation, with the callback each takes. impls: std::cell::RefCell, usize)>>, opaque: Vec<(String, Why)>, + twins: Vec, bytes: Option, api: Api, } @@ -112,6 +115,7 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> left_out: Default::default(), impls: Default::default(), opaque: Vec::new(), + twins: Vec::new(), bytes, api: Api { krate: config.crate_name(), @@ -130,6 +134,7 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> api: c.api, refusals: c.refusals, opaque: c.opaque, + twins: c.twins, hidden: c.hidden, excluded: c.excluded, aliases: c.aliases, @@ -344,7 +349,11 @@ impl<'tcx> Collector<'tcx> { if !matches!(self.decls.get(&def_id), Some(Decl::Record(_) | Decl::Enum(_))) { continue; } - if let Err(why) = self.fields(def_id) { + let fields = match self.recursive(def_id) { + true => Err(vec![why("recursive value", "")]), + false => self.fields(def_id).map(|_| ()), + }; + if let Err(why) = fields { let first = why.into_iter().next().expect("a refusal has a reason"); self.opaque.push((path.join("::"), first)); let decl = self.object(def_id); @@ -358,6 +367,39 @@ impl<'tcx> Collector<'tcx> { } } + /// Whether a value holds itself, through other values, an `Option`, or a `Box`: C + /// holds each value in place, so it cannot. + fn recursive(&self, start: DefId) -> bool { + let tcx = self.tcx; + let mut seen = rustc_data_structures::fx::FxHashSet::default(); + let mut stack = vec![start]; + while let Some(def_id) = stack.pop() { + let adt = tcx.adt_def(def_id); + let identity = ty::GenericArgs::identity_for_item(tcx, def_id); + for field in adt.all_fields() { + for arg in field.ty(tcx, identity).skip_norm_wip().walk() { + let Some(ty) = arg.as_type() else { + continue; + }; + let ty::Adt(inner, _) = ty.kind() else { + continue; + }; + let did = inner.did(); + if !matches!(self.decls.get(&did), Some(Decl::Record(_) | Decl::Enum(_))) { + continue; + } + if did == start { + return true; + } + if seen.insert(did) { + stack.push(did); + } + } + } + } + false + } + /// A struct's or enum's variants, with their fields mapped. fn fields(&self, def_id: DefId) -> Result, Vec> { let tcx = self.tcx; @@ -490,6 +532,7 @@ impl<'tcx> Collector<'tcx> { ok: ty, err: None, future: false, + eager: false, access: Access::Field, }), Err(why) => self.refuse(&getter, "field", span, vec![why]), @@ -502,6 +545,7 @@ impl<'tcx> Collector<'tcx> { fn methods(&mut self, def_id: DefId, path: &[String]) -> (Vec, Traits) { let tcx = self.tcx; let mut methods = Vec::new(); + let mut refused = Vec::new(); let self_ty = tcx.type_of(def_id).instantiate_identity().skip_norm_wip(); for &imp in tcx.inherent_impls(def_id) { for item in tcx.associated_items(imp).in_definition_order() { @@ -527,10 +571,21 @@ impl<'tcx> Collector<'tcx> { } match self.function(item.def_id, method.clone(), Some(self_ty)) { Ok(function) => methods.push(function), - Err(why) => self.refuse(&method, "method", span, why), + Err(why) => refused.push((method, span, why)), } } } + // `poll_x` is left out when `x` exports as a future: the future is its poll. + for (method, span, why) in refused { + let name = method.last().expect("a method has a name"); + let twin = name + .strip_prefix("poll_") + .is_some_and(|x| methods.iter().any(|m| m.future && m.name() == x)); + match twin { + true => self.twins.push(method.join("::")), + false => self.refuse(&method, "method", span, why), + } + } let env = TypingEnv::post_analysis(tcx, def_id); let implements = |item| { tcx.get_diagnostic_item(item).is_some_and(|tr| { @@ -625,6 +680,11 @@ impl<'tcx> Collector<'tcx> { let args = self.instantiate(def_id, self_ty)?; let env = TypingEnv::post_analysis(tcx, def_id); let sig = tcx.fn_sig(def_id).instantiate(tcx, args).skip_norm_wip(); + // Whether what it returns borrows: any lifetime but `'static` in it. + let borrows = sig.skip_binder().output().walk().any(|arg| match arg.kind() { + GenericArgKind::Lifetime(region) => !region.is_static(), + _ => false, + }); let sig = tcx.instantiate_bound_regions_with_erased(sig); let normalize = |ty: Ty<'tcx>| { tcx.try_normalize_erasing_regions(env, ty::Unnormalized::new_wip(ty)) @@ -669,10 +729,15 @@ impl<'tcx> Collector<'tcx> { } let mut output = normalize(sig.output()); let mut future = false; + let eager = !tcx.asyncness(def_id).is_async(); if let Some(inner) = self.future_output(output, env) { if !self.is_send(output, env) { errs.push(why("future not Send", "")); } + // Called at once, the future must outlive the arguments the call borrowed. + if eager && borrows { + errs.push(why("borrowing future from a function that is not async", "")); + } output = normalize(inner); future = true; } @@ -702,6 +767,7 @@ impl<'tcx> Collector<'tcx> { ok, err, future, + eager: future && eager, access: Access::Call, }), _ => Err(errs), @@ -868,6 +934,28 @@ impl<'tcx> Collector<'tcx> { .ok() } + /// Whether `ty` holds an object that is not `Copy`, which a copy would duplicate. + fn holds_handle(&self, ty: Ty<'tcx>) -> bool { + let tcx = self.tcx; + ty.walk().filter_map(|arg| arg.as_type()).any(|ty| match ty.kind() { + ty::Adt(adt, _) => { + matches!(self.decls.get(&adt.did()), Some(Decl::Object(_))) && !implements(tcx, adt.did(), sym::Copy) + } + _ => false, + }) + } + + fn is_clone(&self, ty: Ty<'tcx>) -> bool { + let tcx = self.tcx; + let Some(clone) = tcx.lang_items().clone_trait() else { + return false; + }; + let (infcx, env) = tcx.infer_ctxt().build_with_typing_env(TypingEnv::fully_monomorphized()); + infcx + .type_implements_trait(clone, [ty], env) + .must_apply_modulo_regions() + } + fn is_send(&self, ty: Ty<'tcx>, env: TypingEnv<'tcx>) -> bool { let tcx = self.tcx; let Some(send) = tcx.get_diagnostic_item(sym::Send) else { @@ -911,6 +999,7 @@ impl<'tcx> Collector<'tcx> { ok, err: None, future: false, + eager: false, access: Access::Const, }), Err(why) => { @@ -971,14 +1060,15 @@ impl<'tcx> Collector<'tcx> { ty::Mutability::Mut => Mutability::Mut, }; match (&inner_ty, pos, mutability) { - // Returned as a copy: plain data reads the same either way. // Returned as a copy: plain data reads the same either way, and so does a - // `Copy` handle's value. - (Type::Object(_), Pos::Return, _) - if !tcx.type_is_copy_modulo_regions(TypingEnv::fully_monomorphized(), *inner) => - { + // `Copy` handle's value, but a clone of another handle is a new one. + (_, Pos::Return, _) if self.holds_handle(*inner) => { return Err(why("borrowed object return", inner.to_string())); } + (Type::Str | Type::Slice, Pos::Return, _) => {} + (_, Pos::Return, _) if !self.is_clone(*inner) => { + return Err(why("borrowed return that is not Clone", inner.to_string())); + } (_, Pos::Field, _) => return Err(why("reference field", inner.to_string())), (Type::Object(_), Pos::Param, _) => {} (_, Pos::Param, Mutability::Mut) => return Err(why("&mut of a value", inner.to_string())), diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 4a43fc386..8e653f609 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -748,7 +748,8 @@ impl Gen<'_> { fn function(&mut self, function: &Function, owner: Option<(&Ty, Option)>) { let export = self.abi.export(function, owner.map(|(ty, _)| ty)); let name = export.call.name.clone(); - let future = function.future; + // An eager call borrows its arguments only for the call, as a synchronous one does. + let future = function.future && !function.eager; let mut stmts = Vec::new(); let mut args = Vec::new(); let mut params = Vec::new(); @@ -798,8 +799,14 @@ impl Gen<'_> { }; let body = stmts.join("\n\t"); if let Some((_, poll, free)) = &export.future { + // A function that is not `async` runs when called, and what it returns + // borrows nothing, so it is called now; an `async fn` runs when polled. + let (now, later) = match function.eager { + true => (format!("\n\tlet future = {call};"), "future".to_string()), + false => (String::new(), call), + }; self.line(format!( - "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> *mut rt::Future {{\n\tlet w = \"{name}\";\n\tlet _ = w;\n\t{body}\n\trt::Future::new(async move {{\n\t\tlet result = {call}.await;\n\t\t::std::boxed::Box::new(move |out: *mut c_void, err: *mut c_void| -> i32 {{\n\t\t\tlet _ = (out, err);\n\t\t\t{}\n\t\t}}) as rt::Done\n\t}})\n}}\n", + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}({}) -> *mut rt::Future {{\n\tlet w = \"{name}\";\n\tlet _ = w;\n\t{body}{now}\n\trt::Future::new(async move {{\n\t\tlet result = {later}.await;\n\t\t::std::boxed::Box::new(move |out: *mut c_void, err: *mut c_void| -> i32 {{\n\t\t\tlet _ = (out, err);\n\t\t\t{}\n\t\t}}) as rt::Done\n\t}})\n}}\n", params.join(", "), self.finish(function, ("v", "rt::READY", "rt::ERROR")) )); diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index 9ef29c26f..f73a4666b 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -117,6 +117,9 @@ pub struct Function { pub err: Option, /// Whether it returns a future: an `async fn`, or a value that implements `Future`. pub future: bool, + /// For a future, whether the call itself runs code, as a function that is not + /// `async` returning one does: the export calls it at once, and polls what it returns. + pub eager: bool, /// What it reads: Rust's function, or a field or constant named as it is. pub access: Access, } diff --git a/ffi/tests/api.c b/ffi/tests/api.c index 6265b72e7..f50940ae0 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -148,9 +148,23 @@ static int script(void) { printf("nonempty pending\n"); } api_channel_recv_nonempty_future_free(nonempty); + + /* The send happens at the call: the future is dropped unpolled. */ + api_channel_send_later_future_free(api_channel_send_later(channel, str("eager"))); + recv = api_channel_recv(channel); + if (api_channel_recv_poll(recv, waker, &payload) == API_POLL_READY) { + print("recv ", payload, "\n"); + } + api_channel_recv_future_free(recv); api_channel_free(channel); + + /* A value that holds itself is an object. */ + api_node *list = api_node_new(1, NULL); + api_node_push(list, 2); + printf("node %llu\n", (unsigned long long)api_node_sum(list)); + api_node_free(list); /* Each future dropped its waker once it finished. */ - return drops == 2 ? 0 : 1; + return drops == 3 ? 0 : 1; } /* Each breaks a contract, which must abort with a message naming the function. */ diff --git a/quest/m1/README.md b/quest/m1/README.md index 0fdebb01c..9ef87679d 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -2,25 +2,20 @@ ## Goal -The work moq is waiting on: the UniFFI fork its bindings switch to, the exporter -that may replace it, and the fork's perf work moq planned. +The work moq is waiting on: the UniFFI fork its bindings switch to, and the exporter +that replaces it. ## Plan -Decided with the maintainer on 2026-10-24: an [exporter](/ffi/README.md) that turns a -crate's `pub` API into bindings, with no attributes, may replace the UniFFI fork. The fork -stays in maintenance and keeps building moq's bindings; its feature quests, here and in -m2, pause until the [decision](/quest/m1/ffi-export-decision.md) the spike's report asks -for, which decides whether each is folded into the exporter. The binding benchmark -continues as the exporter's baseline. +Decided with the maintainer on 2026-10-25, from the +[spike](https://github.com/kixelated/rust2/pull/41): the [exporter](/ffi/README.md), which +turns a crate's `pub` API into bindings with no attributes, replaces the UniFFI fork. The +fork stays in maintenance and keeps building moq's bindings until then; its feature quests +are folded into the [exporter's](/quest/m1/ffi-export.md). The binding benchmark continues +as the exporter's baseline. ## Required - [Waiting: publish the UniFFI fork](/quest/m1/uniffi-release.md) - the fork publishes to crates.io under `rust2-*` names, once the maintainer decides it should - [Binding benchmark](/quest/m1/ffi-bench.md) - moq's `bench-ffi` moves here and measures every wrapper against the fork, nightly -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - the maintainer decides from the spike's report whether the exporter replaces the UniFFI fork -- [Exporter](/quest/m1/ffi-export.md) - moq's bindings exported from its crates' `pub` API, if adopted -- [Payload bytes](/quest/m1/ffi-bytes.md) - payloads cross the FFI in bulk copies, proven in every wrapper -- [Kotlin calls](/quest/m1/kt-ffi-calls.md) - Kotlin calls cost about what Python's and Go's do, starting from upstream's JNI bindgen -- [Waiting: moq's poll-native async](/quest/m1/moq-poll-migrate.md) - condition: moq's `ffi-poll-migrate` quest has landed -- [Foreign poll for hot reads](/quest/m1/ffi-poll-protocol.md) - track and group reads are a sync poll plus a registered waker in every wrapper, and a cancel never loses a frame +- [Exporter](/quest/m1/ffi-export.md) - moq's bindings exported from its crates' `pub` API, replacing the fork diff --git a/quest/m1/ffi-bench.md b/quest/m1/ffi-bench.md index 2a4b04743..6c2e167a2 100644 --- a/quest/m1/ffi-bench.md +++ b/quest/m1/ffi-bench.md @@ -5,7 +5,7 @@ `just bench-ffi` runs here, nightly in CI: it builds moq-ffi at a pinned moq revision against [the fork](/uniffi/README.md) and measures every wrapper (Python, Go, Kotlin, Swift, Dart, C++, and the browser over ubrn) as moq's -`bench/` does today. Every fork perf quest states its effect with these +`bench/` does today. Each [exporter](/quest/m1/ffi-export.md) generator states its effect against these numbers. moq deletes its copy (`just bench-ffi`, `bench/ffi-gen`, and their nightly jobs) in a paired PR. diff --git a/quest/m1/ffi-bytes.md b/quest/m1/ffi-bytes.md deleted file mode 100644 index 2a892348c..000000000 --- a/quest/m1/ffi-bytes.md +++ /dev/null @@ -1,53 +0,0 @@ -# [L] Binding payloads cross the FFI without per-byte copies - -## Goal - -A binding moves a frame payload across the FFI with no per-byte loop: every -copy on the path is a bulk copy, and the report counts them per direction. -Proven on the [binding benchmark](/quest/m1/ffi-bench.md) in every wrapper -(Python, Go, Kotlin, Swift, Dart, C++, and the browser). - -## Plan - -Decided with the maintainer on 2026-10-13 in moq, and moved here on 2026-10-23 -with the binding benchmark: - -- **The browser too.** Since 2026-10-17 - ([moq-dev/moq#5838](https://github.com/moq-dev/moq/pull/5838)) the browser - binds moq-ffi through UniFFI over ubrn, and pays the same per-byte path: about - 7 ns per byte written and 8 ns read at 128 KiB in Chromium, against BoltFFI's - 0.5 and 1.3. -- **Benchmark first.** Measure every wrapper before and after, and add a Rust - microbenchmark of the fork's lift and lower for `Vec` beside the patch it - proves. -- **Bulk copy in the fork's core.** UniFFI lifts and lowers `Vec` through - the generic `Vec` path, one byte at a time with a bounds check each - (`uniffi_core` `ffi_converter_impls.rs`), in both directions - ([mozilla/uniffi-rs#2846](https://github.com/mozilla/uniffi-rs/issues/2846)). - That path covers arguments, record fields (`MoqFrame.payload`, video and - audio frames), and returns (`read_frame`, `recv_datagram`). Make it one - `memcpy`. The serialized format is unchanged, so no generator or binding API - changes. Two copies remain for records and returns (the wrapper's container - to `RustBuffer`, then `RustBuffer` to `Vec`); removing the second is - [zero-copy returns](/quest/m2/ffi-bytes-return.md). - [moq-dev/moq#2946](https://github.com/moq-dev/moq/issues/2946) already - removed the per-byte copy on the Python side. -- **The C++ generator copies per byte on the foreign side too** - (`bytes_conv.cpp`, `RustStream >>`), capping it at 77 MB/s at 1 MiB. Fix it - here, since it is the same problem. -- **`&[u8]` arguments only if the numbers say so.** UniFFI 0.32 makes `&[u8]` - arguments zero-copy, but only for sync calls that take bytes directly, such - as the `write(payload)` methods. It cannot be used in records, async calls, - or callback interfaces. Adopting it means fixing the Go and C++/C generators - (both lower to `RustBuffer` where the declaration expects `ForeignBytes`, so - they would not compile) and Dart (copies and never frees). Kotlin's parameter - type would become `ByteBuffer`. Do it only if the benchmark shows the - remaining copy matters after the bulk copy; otherwise record the numbers and - skip it. - -Public API: none unless `&[u8]` lands, which changes Kotlin's parameter type. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m1/ffi-export-decision.md b/quest/m1/ffi-export-decision.md deleted file mode 100644 index dbcf8edb4..000000000 --- a/quest/m1/ffi-export-decision.md +++ /dev/null @@ -1,46 +0,0 @@ -# [XS] Waiting: decide whether the exporter replaces the UniFFI fork - -## Goal - -The maintainer decides, from [the exporter spike's report](https://github.com/kixelated/rust2/pull/41), -whether [rust2-ffi](/ffi/README.md) replaces [the UniFFI fork](/uniffi/README.md) for moq, -and so whether the fork's paused feature quests fold into it. Check: ask the maintainer. -Delete this quest once decided, rescoping or deleting each quest that requires it. - -## Plan - -The spike's recommendation: adopt the exporter, and fold every paused quest into it. - -- It exports 87% of moq-net's types and 81% of their methods and fields with no - attributes, and its C test publishes and subscribes to a track against the real - library, with every read a polled future. Four more rules (tuples as out parameters, - `Path<'static>`, a clone for a borrowed `Clone` return, and `Range`) cover most of the - rest; the `poll_*` methods with an async twin are 39 of the 112 refused methods. -- Its frame writes cost what moq's hand-written `rs/moq-c` does (within 5%, the rest a - timestamp's handle), so call overhead is no reason to keep a wrapper. -- What moq-ffi adds over moq-net is mostly other crates (sessions over moq-native, media - over hang and the codecs) and a runtime to drive sessions, not reshaping moq-net. - -Each paused quest, if adopted: - -- [C-first bindings spike](/quest/m2/uniffi-c-first-spike.md): done in kind. The export is - C with nothing underneath, callbacks are C, and the name clash is refused at both spans - with a `rename` to fix it. C++ per standard layers on its C ABI, as a generator. -- [Namespaced contract](/quest/m2/uniffi-contract.md) and [checksums](/quest/m2/ffi-checksums.md): - the export has neither. A header and library from different builds still mix silently, - so the exporter needs one contract symbol per build, checked at load. -- [Payload bytes](/quest/m1/ffi-bytes.md) and [zero-copy returns](/quest/m2/ffi-bytes-return.md): - done at the C ABI. A sync call borrows a payload argument with no copy, and a returned - `Bytes` is handed over without one; each language's generator must keep that. -- [Cheaper async](/quest/m2/ffi-async.md) and [foreign poll](/quest/m1/ffi-poll-protocol.md): - a future ready on its first poll costs three crossings (call, poll, free), not UniFFI's - five, and the poll that finishes writes the result, so a cancel never loses a frame. A - repeated waker is reused, not re-registered. Left: a future handle per read. -- [Code size](/quest/m2/ffi-code-size.md): moq-net's header is 1003 functions, 99 KB - without its docs; measure per language once generators exist. -- [Kotlin calls](/quest/m1/kt-ffi-calls.md): JNI or Panama becomes the Kotlin generator's - choice over the C ABI, rather than a patch to the fork's JNA bindings. - -## Related - -- [Exporter](/quest/m1/ffi-export.md) - the work that follows, if adopted diff --git a/quest/m1/ffi-export.md b/quest/m1/ffi-export.md index a60262633..af834971d 100644 --- a/quest/m1/ffi-export.md +++ b/quest/m1/ffi-export.md @@ -2,32 +2,48 @@ ## Goal -[rust2-ffi](/ffi/README.md) exports what moq's bindings need from moq's own crates, with -no attributes and no hand-written wrapper beyond what the census shows is genuinely new -API, and generates the languages moq ships on its C ABI. moq-ffi shrinks to that remainder. +[rust2-ffi](/ffi/README.md) replaces [the UniFFI fork](/uniffi/README.md) for moq: it exports +what moq's bindings need from moq's own crates, with no attributes and no hand-written wrapper +beyond what the census shows is genuinely new API, and generates the languages moq ships on its +C ABI. moq-ffi shrinks to that remainder. The fork stays in maintenance, building moq's bindings +until then. ## Plan -From the spike ([kixelated/rust2#41](https://github.com/kixelated/rust2/pull/41)); split -into quests once the decision lands, ranked by what the census refuses: +Decided with the maintainer on 2026-10-25, from the spike +([kixelated/rust2#41](https://github.com/kixelated/rust2/pull/41)): adopt the exporter, and fold +the fork's paused feature quests into it. Split into quests as work starts, ranked by what the +census refuses and what moq waits on: - **Rules the census asks for**: tuples as out parameters (`origin::Producer::new`, so an - origin can be made), `Path<'a>` exported as `Path<'static>`, a clone for a borrowed - return of a `Clone` object (the 21 `info()` getters), `Range` and `RangeBounds`, - and a policy for `poll_*` methods: 39 of 46 have an async twin, which may make them - redundant, or the poll protocol may want them in place of the twin. -- **Several crates**: moq-native's sessions and the media crates are where moq-ffi's - remaining API lives. Export each with its own census, naming another export's types - across crates, as moq-pattern's re-exports already need. + origin can be made), `Path<'a>` exported as `Path<'static>`, `Range` and + `RangeBounds`, and the borrowed `info()` returns of non-`Copy` objects, whose clone is a new + handle. +- **Several crates**: moq-native's sessions and the media crates hold moq-ffi's remaining API. + Export each with its own census, naming another export's types across crates, as + moq-pattern's re-exports already need. - **Driving**: sessions and origins run a `Driver` polled with a time and a `kio::Waiter`. Decide between exporting that poll, a generated thread that drives it, or moq-native's runtime helpers. -- **A contract symbol** per build, so a header and a library from different builds refuse - to load together. -- **Generators**: the IR holds what each language needs (paths, docs, receivers, exact - borrow forms). Start with the language whose binding costs moq the most today, measured - on the [binding benchmark](/quest/m1/ffi-bench.md). +- **A contract symbol** per build, checked when bindings load, so a header and a library from + different builds refuse to mix. It replaces the fork's namespaced contract and per-method + checksums, which the export never had. +- **Generators** on the C ABI, measured on the [binding benchmark](/quest/m1/ffi-bench.md): + - C++ per standard (17, 20, 23) over the one C ABI, compiled with GCC, Clang, and MSVC, with + and without exceptions and RTTI; OBS builds at C17 and C++17. + - Kotlin through JNI or Panama rather than JNA: the fork measured 3.2 us per call against + 7 ns for upstream's JNI bindgen. + - Each keeps the C ABI's bulk and zero-copy payloads (no per-byte loop on either side) and + reports its generated size, raw and gzipped, against the fork's (Python 653 KiB, Kotlin + 914 KiB, Swift 684 KiB for moq-ffi). +- **Async in each language**: the C ABI's futures already take the result in the poll that + finishes them, so a cancel never loses a frame, cost three crossings when ready at once, + and reuse a repeated waker. Each language's native future around them must latch a wake + that lands between `PENDING` and parking, prove no loss on cancel in a test that forces that + window, and pick a semantic for concurrent pollers. Go's cancel contract (moq's + `go/wrapper/doc.go` ends the stream) is decided then. A hot read still makes a future handle + per read; measure it before adding a per-handle poll. -## Required +## Related -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - whether the exporter replaces the UniFFI fork +- [Binding benchmark](/quest/m1/ffi-bench.md) - the fork's numbers, the baseline each generator is measured against diff --git a/quest/m1/ffi-poll-protocol.md b/quest/m1/ffi-poll-protocol.md deleted file mode 100644 index 16b7f889a..000000000 --- a/quest/m1/ffi-poll-protocol.md +++ /dev/null @@ -1,82 +0,0 @@ -# [L] Foreign poll for hot reads - -## Goal - -Track and group reads (`recv_group`, `next_group`, `read_frame`, and -`recv_datagram`) reach every wrapper as a sync poll plus a waker registered once -per handle. The fork's generators build each language's native future around -them, so a ready read costs no event-loop round trip. A cancelled read never -loses a frame. Other async exports keep UniFFI's `RustFuture`. - -## Plan - -Decided with the maintainer on 2026-10-16 in moq, from -[the spike](https://github.com/moq-dev/moq/pull/5851) (Shape B′, prototype on -moq's `spike/ffi-poll-prototype`), and moved here on 2026-10-23 with the rest -of the fork's perf work. The generator half lands here; moq-ffi's export -changes land as a paired moq PR. The spike measured, on a loaded host: - -- Python: a ready `read_frame` took 7.4 µs against 24.5 µs for Shape A. Burst - throughput was 1.7x Shape A's, with no loop wakeup per ready read. -- Go: a ready `read_frame` took 0.67 µs against 1.2. At 64 subscribers - throughput was 1108 MB/s against 713, at 8.2 µs CPU per frame against 11.5. -- Cancel: Shape A and `Task` lose a frame whose `RustFuture` finished before - the foreign side dropped it. Python asyncio and Go ctx cancels both hit this. - A sync poll cannot, since the caller takes the item in the same call. - -Things to carry over and check: - -- **Register the waker, don't pass it per poll.** The spike's per-call - `poll_x(waker)` registered a new callback handle in the generator's global - map on every poll and freed it through another callback. That dropped Go at - 64 subscribers to 89 MB/s. A handle's waker is set once. Decide how a new - group inherits its track's waker, rather than paying an extra call per group. -- **Generated, not hand-written.** The per-language future glue (asyncio, Go - channel and ctx, Kotlin and Swift continuations, Dart, C++, C) belongs in the - generators, so moq-ffi exports a poll once. The Go wrapper's bridge goroutine - can go for these reads. -- **Go's cancel contract.** moq's `go/wrapper/doc.go` promises that cancelling - a `RecvGroup` or `ReadFrame` context ends the stream. The protocol makes a - per-read cancel safe. Decide with the maintainer whether a cancel now ends - only that read or still ends the stream. If it changes, update the doc, the - tests, and the PR's API report; the other wrappers face the same question. -- **Latch wakes.** A wake that lands after a poll returns `Pending` but before - the native future parks must not be lost. The spike's Go waker was a buffered - channel, and its Python one swapped in a fresh future before each poll. Each - backend needs an equivalent handshake and a test that forces that - interleaving. -- **Prove no-loss per backend.** A sync poll only moves the race into the - generated glue: if it polls an item out and then sees its future cancelled, - the item is gone. Each backend that can cancel must force that window in a - test. Either the result is delivered or the next read gets the item. The - spike's Python and Go cancel probes are a starting point. -- **Concurrent pollers on one handle share one waker.** Pick a semantic and - test it: either reject a second concurrent read, or wake every poller. -- **Reader modes are chosen up front** (moq API audit, 2026-10-22). Today one - `MoqTrackConsumer` offers arrival-order reads, ordered reads, and - `read_frame`; the first read commits a mode and later calls fail - `AlreadyCommitted`, and track-level `read_frame` silently returns only each - group's first frame (moq's `rs/moq-ffi/src/consumer.rs`). Since this quest - reshapes these reads anyway, land the split here so they break once: - `MoqTrackConsumer::ordered() -> MoqOrderedTrackConsumer` takes over the - handle like Rust's `Subscriber::ordered()`, the base consumer keeps - `recv_*`, and `read_frame` moves to the ordered reader returning the group - and frame position like JS. Python's `__aiter__` stops committing silently. -- Measure every generated wrapper (Go, Python, Kotlin, Swift, Dart, C++) on the - [binding benchmark](/quest/m1/ffi-bench.md); the spike covered only Go and - Python. Sweep publishers as well as subscribers, since the generator's - callback-handle map is shared process-wide. - -Public API: these reads gain a poll protocol in every binding; their async -signatures stay where a language keeps both. Go's read cancel may change from -terminal to per-read. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Binding benchmark](/quest/m1/ffi-bench.md) - the numbers every wrapper is measured on -- [moq's poll-native async](/quest/m1/moq-poll-migrate.md) - the kio poll each export wraps, with `ffi::Task` gone - -## Related - -- [Kotlin calls](/quest/m1/kt-ffi-calls.md) - the Kotlin call overhead this protocol also pays diff --git a/quest/m1/kt-ffi-calls.md b/quest/m1/kt-ffi-calls.md deleted file mode 100644 index b75c2551f..000000000 --- a/quest/m1/kt-ffi-calls.md +++ /dev/null @@ -1,45 +0,0 @@ -# [M] Kotlin binding calls without JNA overhead - -## Goal - -A Kotlin call into moq-ffi costs about what the same call costs from Python or -Go, sync and async alike, proven on the -[binding benchmark](/quest/m1/ffi-bench.md). - -## Plan - -Measured 2026-10-15 in moq: a sync `sequence()` took 11-22 us from Kotlin -against 1.3 us from Python and 0.12 us from Go, and the 100 B throughput case -kept about 5.8 cores busy for 2 MB/s. - -Decided with the maintainer on 2026-10-15 in moq, and moved here on 2026-10-23: - -- **Profile first** (JFR or async-profiler) and confirm each cause before - changing anything. The two suspects in the generated Kotlin: - - Every call allocates a JNA `Structure` (`UniffiRustCallStatus`, which - nests a `RustBuffer.ByValue`), and JNA builds and syncs those by - reflection - ([mozilla/uniffi-rs#3011](https://github.com/mozilla/uniffi-rs/issues/3011)). - - The async continuation is a plain JNA `Callback` with no - `CallbackThreadInitializer`, so each wakeup from a Rust worker attaches - that thread to the JVM and detaches it again. -- **Fix in the fork's Kotlin generator**, not by patching generated code. Both - costs are one quest: same root, same generator, same proof. Prefer a shape - that keeps the wrapper's API unchanged. -- The BoltFFI spike measured the target: its JNI backend makes a no-op call in - 6 ns and a 100 B `write_frame` in 134 ns, against UniFFI's 3.2 and 12.8 us. - -Decided with the maintainer on 2026-10-23: try cherry-picking upstream's -experimental Kotlin JNI bindgen -([mozilla/uniffi-rs#2911](https://github.com/mozilla/uniffi-rs/pull/2911), on -upstream `main` after 0.32.2, unreleased) before hand-fixing JNA. Its author -measured a call at 3.04 us to 7 ns and bytes at 14.7 us to 87 ns -([gist](https://gist.github.com/bendk/7bc8886cb33b8bd5d257336dc33d54a5)), -about even with BoltFFI. List it as a carried change in the fork's README. - -Public API: none expected. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Binding benchmark](/quest/m1/ffi-bench.md) - the before and after numbers diff --git a/quest/m1/moq-poll-migrate.md b/quest/m1/moq-poll-migrate.md deleted file mode 100644 index e4c2254ed..000000000 --- a/quest/m1/moq-poll-migrate.md +++ /dev/null @@ -1,16 +0,0 @@ -# [XS] Waiting: moq's poll-native async - -## Goal - -moq has landed its poll-native async migration -([moq-dev/moq `quest/m2/ffi-poll-migrate.md`](https://github.com/moq-dev/moq/blob/main/quest/m2/ffi-poll-migrate.md)): -moq-ffi's kio-backed async exports are a `kio::wait` over their `poll_*`, with -`ffi::Task` gone from those paths. Check: that quest file is gone from moq's -`main`. Delete this quest once it holds. - -## Plan - -Decided with the maintainer on 2026-10-23: [foreign poll](/quest/m1/ffi-poll-protocol.md) -moved here with the rest of the fork's perf work, but it wraps the polls this -moq migration exposes. This quest stands in for that cross-repository blocker -so foreign poll resurfaces when it clears. diff --git a/quest/m2/README.md b/quest/m2/README.md index 8a2c16113..e22b8001d 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -16,7 +16,7 @@ Decided with the maintainer on 2026-10-24: the translator's output ranks correct then speed, then the size of the consumer's final tree-shaken, minified JS; readability is not a goal, and types must be solid at the API boundary ([design](/ts/README.md#design)). -The fork's feature quests here pause until the [exporter decision](/quest/m1/ffi-export-decision.md); +The fork's feature quests folded into the [exporter](/quest/m1/ffi-export.md); [m1](/quest/m1/README.md#plan) records why. ## Required @@ -34,10 +34,4 @@ The fork's feature quests here pause until the [exporter decision](/quest/m1/ffi - [Tree-shaking spike](/quest/m2/ts-shake-spike.md) - classes, free functions, or free functions behind root facades, measured on speed, shaken size, and caller code - [Tree-shakable runtime](/quest/m2/ts-runtime-shake.md) - `rt`'s adaptors and formatters become individually exported functions, kept only if no slower - [Translate moq-net's model to TypeScript](/quest/m2/ts-model.md) - the driver grows from moq-net's codec to its model, for moq to compare against WASM -- [Zero-copy byte returns](/quest/m2/ffi-bytes-return.md) - returned payloads reach the host without a copy, if the payload numbers justify it -- [Cheaper async](/quest/m2/ffi-async.md) - `RustFuture` exports cost fewer crossings, if the numbers show they matter -- [C-first bindings spike](/quest/m2/uniffi-c-first-spike.md) - C directly on the UniFFI ABI with per-standard C++ on top, measured against C-over-C++ on a moq-ffi slice - [Nightly MSVC and macOS](/quest/m2/uniffi-ci-msvc-macos.md) - the C and C++ fixtures compile nightly with MSVC and Apple Clang, at C++17 and C++20, and without exceptions or RTTI -- [Namespaced FFI contract](/quest/m2/uniffi-contract.md) - bindings and a cdylib from different UniFFI forks refuse to load together -- [Drop checksums](/quest/m2/ffi-checksums.md) - bindings load without a checksum call per method -- [Smaller bindings](/quest/m2/ffi-code-size.md) - generated bindings shrink in every language, measured per template diff --git a/quest/m2/ffi-async.md b/quest/m2/ffi-async.md deleted file mode 100644 index 83ac484a4..000000000 --- a/quest/m2/ffi-async.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] Cheaper async for RustFuture exports - -## Goal - -An async export that stays on UniFFI's `RustFuture` (connect, accept, session -status, and the other exports [foreign poll](/quest/m1/ffi-poll-protocol.md) -leaves alone) costs fewer FFI crossings per call in every generator, proven on -the [binding benchmark](/quest/m1/ffi-bench.md), with no change to the -bindings' async signatures. - -## Plan - -Decided with the maintainer on 2026-10-23: its own quest, after foreign poll, -so it reuses that waker design and measures only what remains. - -- UniFFI 0.32 spends at least five crossings on a future that is ready on its - first poll (call, poll, continuation, complete, free), plus a poll and a - callback per extra wake. Measure the share these exports actually take - before changing the protocol; if it is noise, delete this quest and record - the numbers. -- The fork may change the FFI contract here; keep it under the fork's own - contract namespace so it never mixes with upstream UniFFI. - -Public API: none expected. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Foreign poll for hot reads](/quest/m1/ffi-poll-protocol.md) - the waker design this reuses diff --git a/quest/m2/ffi-bytes-return.md b/quest/m2/ffi-bytes-return.md deleted file mode 100644 index e33578c1e..000000000 --- a/quest/m2/ffi-bytes-return.md +++ /dev/null @@ -1,29 +0,0 @@ -# [M] Zero-copy byte returns - -## Goal - -A frame payload returned to a binding (`read_frame`, `recv_datagram`, decoded -media) reaches the host without a copy, through a Rust-owned buffer the host -releases, in every generator of [the fork](/uniffi/README.md). Proven on the -[binding benchmark](/quest/m1/ffi-bench.md). - -## Plan - -Decided with the maintainer on 2026-10-13 in moq, and moved here on 2026-10-23: -build it in the fork rather than wait for upstream -([mozilla/uniffi-rs#2847](https://github.com/mozilla/uniffi-rs/issues/2847)). -Gated on the payload numbers: start only if, after the bulk copy, the remaining -return copy is a measurable share of the read path. Otherwise delete this quest -and record why. - -- The buffer's lifetime must be explicit in each language: a host that keeps a - payload view after release reads freed memory. Prefer a host-owned type that - frees on its finalizer or close, matching each wrapper's handle idiom. -- Every generator gets the change, including Go, Dart, C++, and C. - -Public API: returned payload types may change per language. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Payload bytes](/quest/m1/ffi-bytes.md) - the numbers that justify it diff --git a/quest/m2/ffi-checksums.md b/quest/m2/ffi-checksums.md deleted file mode 100644 index 809511fdd..000000000 --- a/quest/m2/ffi-checksums.md +++ /dev/null @@ -1,25 +0,0 @@ -# [S] Drop the fork's per-method checksums - -## Goal - -Bindings generated by [the fork](/uniffi/README.md) load without calling a -checksum function per method, and the library no longer exports those -functions. The [binding benchmark](/quest/m1/ffi-bench.md) reports load time, -library size, and symbol count before and after. - -## Plan - -Decided with the maintainer on 2026-10-23: the fork's own contract namespace -already makes mixing with upstream UniFFI fail at load time, which is what the -checksums guard per method. Upstream can skip the check (`omit_checksums`) but -still compiles the functions in -([mozilla/uniffi-rs#2725](https://github.com/mozilla/uniffi-rs/issues/2725)). -Expect a small win; record the numbers either way. - -Public API: none; generated bindings lose their checksum calls. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Namespaced FFI contract](/quest/m2/uniffi-contract.md) - what refuses a mismatched library once the checksums are gone -- [Binding benchmark](/quest/m1/ffi-bench.md) - load time, size, and symbol numbers diff --git a/quest/m2/ffi-code-size.md b/quest/m2/ffi-code-size.md deleted file mode 100644 index b5f66d99c..000000000 --- a/quest/m2/ffi-code-size.md +++ /dev/null @@ -1,22 +0,0 @@ -# [M] Smaller generated bindings - -## Goal - -The fork's generators emit measurably smaller bindings for moq-ffi in every -language, with unchanged behavior, reported raw and gzipped by the -[binding benchmark](/quest/m1/ffi-bench.md). - -## Plan - -Decided with the maintainer on 2026-10-23: measure first. moq-ffi's bindings -are 653 KiB in Python, 914 KiB in Kotlin, and 684 KiB in Swift, and BoltFFI's -were 2 to 3x smaller. Attribute the size per template (converters, checksums, -per-method boilerplate) before shrinking, and stop where the remaining gain is -not worth the template complexity. - -Public API: generated code changes shape; wrapper APIs do not. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends -- [Binding benchmark](/quest/m1/ffi-bench.md) - the size report diff --git a/quest/m2/uniffi-c-first-spike.md b/quest/m2/uniffi-c-first-spike.md deleted file mode 100644 index 0fc02a610..000000000 --- a/quest/m2/uniffi-c-first-spike.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] C-first bindings spike - -## Goal - -A prototype of a C-first layering in [the fork](/uniffi/README.md)'s generators: -the C API sits directly on UniFFI's `extern "C"` ABI with no C++ underneath, and -the C++ output is generated per standard (for example C++17, 20, and 23) on top -of that one C ABI. It covers a slice of moq-ffi with an async call, an error, -bytes, and a record, and is compared with today's C-over-C++ on call overhead, -generated size, and the compile matrix (GCC, Clang, and MSVC, with and without -exceptions and RTTI). Its report plans the full rewrite. - -## Plan - -Decided with the maintainer on 2026-10-24, after -[kixelated/rust2#34](https://github.com/kixelated/rust2/pull/34) left the C++ -generator with two error styles that each support only part of UniFFI: - -- C-first replaces today's layering, where the C backend wraps expected-style C++. -- The generated C replaces moq's hand-written cbindgen `rs/moq-c`; moq's quest for - that follows this spike. -- Callback interfaces are added at the C level, which subsumes giving the - expected style callback interfaces. -- The exceptions style goes away with the old C++ layer. -- Per-standard C++ output was chosen over one C++17 header with feature tests. - C++ types may differ per standard, but every variant links against the same C - ABI. The C++ layer may be headers or compiled `.cpp` files built per standard; - pick whichever measures better and record why. -- Both outputs take a `--std` flag that opts into newer output, defaulting to the - oldest standard (C11, C++17): - - C: `c11` (today's floor, for anonymous unions), `c17`, or `c23`. C23 can opt - into `bool` and `nullptr`, typed enums (`enum : uint8_t`), `[[nodiscard]]` on - fallible calls, and `constexpr` constants. - - C++: `17`, `20`, or `23` selects the per-standard output. - - The C ABI is identical across `--std` values, so one library build serves - every consumer; only declarations and annotations change. Measure what each - opt-in buys and drop any that changes nothing measurable. -- OBS builds at C17 and C++17 with exceptions and RTTI on, and its plugin API is - C (obs-studio's `cmake/common/compiler_common.cmake`). -- The C name clash moq-ffi hits (`moq_audio_encoder_finish` emitted twice) is - fixed in the generator's naming rule. -- moq's expected-style C++ bindings are today's baseline; the rewrite may change - them, so the report says how moq migrates. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends - -## Related - -- [Nightly MSVC and macOS](/quest/m2/uniffi-ci-msvc-macos.md) - the compile matrix this spike measures by hand, run nightly diff --git a/quest/m2/uniffi-contract.md b/quest/m2/uniffi-contract.md deleted file mode 100644 index 1ddd8682e..000000000 --- a/quest/m2/uniffi-contract.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Namespaced FFI contract in the UniFFI fork - -## Goal - -A library built with [the fork](/uniffi/README.md) and bindings from upstream -UniFFI, or the reverse, fail loudly when the bindings load instead of mixing -silently. Lands with or before the fork's first change to the FFI contract -(metadata, checksums, or scaffolding signatures). - -## Plan - -The import kept upstream 0.32's contract (version 30) and every symbol name so -moq's generated bindings stayed byte-identical. A namespace necessarily changes -every generated binding, so it waits for the first change that changes them -anyway. - -- Prefer a fork-specific contract symbol (for example - `ffi__rust2_uniffi_contract_version`) over a new version number, - which can collide with an upstream bump. Every generator (Kotlin, Swift, - Python, Go, Dart, C++, and C) must check it. -- Prove it with a fixture: each generator's bindings refuse a cdylib built - with upstream UniFFI. -- [Drop checksums](/quest/m2/ffi-checksums.md) is the first consumer: the - namespace is what refuses a mismatched library once the per-method - checksums are gone. - -Public API: the generated contract check, and the scaffolding's exported -contract symbol. - -## Required - -- [Waiting: the exporter decision](/quest/m1/ffi-export-decision.md) - paused until the maintainer decides whether this folds into the exporter, as the spike recommends From da759a4700a67fa35c19335cb7a8f70b42360cf4 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 22:24:22 -0700 Subject: [PATCH 12/16] fix(ffi): compare a handle with itself under one borrow, and refuse an Option inside a Box inside an Option Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- ffi/fixtures/api/examples/transcript.rs | 6 +++++- ffi/fixtures/api/src/lib.rs | 19 +++++++++++++++++++ ffi/fixtures/reject/expected.txt | 9 +++++---- ffi/fixtures/reject/src/lib.rs | 5 +++++ ffi/src/collect.rs | 4 +++- ffi/src/glue.rs | 3 ++- ffi/tests/api.c | 6 ++++++ 7 files changed, 45 insertions(+), 7 deletions(-) diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index 86169864c..3afb06117 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -7,7 +7,7 @@ use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use std::task::{Context, Poll, Wake, Waker}; -use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Node, Point, Shape, Stamp}; +use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Node, Point, Shape, Stamp, Tally}; use bytes::Bytes; /// Keeps even levels, as `tests/api.c`'s implementation does. @@ -123,4 +123,8 @@ fn main() { next: Some(Box::new(Node { value: 2, next: None })), }; println!("node {}", list.sum()); + + let tally = Tally::new(); + tally.bump(); + println!("tally {} {}", tally.bump(), tally == tally); } diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index f1575896d..a538a6fc6 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -285,6 +285,25 @@ impl Node { } } +/// A tally: `Send` but not `Sync`, so even `&self` borrows it exclusively, and comparing +/// a handle with itself is one borrow. +#[derive(Debug, Default, PartialEq)] +pub struct Tally { + count: std::cell::Cell, +} + +impl Tally { + pub fn new() -> Self { + Self::default() + } + + /// Counts through `&self`, which only an exclusive borrow makes sound across threads. + pub fn bump(&self) -> u32 { + self.count.set(self.count.get() + 1); + self.count.get() + } +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index b5dc7fe37..4d41e225c 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -1,9 +1,10 @@ fixtures/reject/src/lib.rs:14:1: rust2-ffi: cannot export fn `map`: foreign type `std::collections::HashMap`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:26:1: rust2-ffi: cannot export fn `borrowing`: borrowing future from a function that is not async; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:35:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:43:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:54:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C +fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:36:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:40:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:48:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:59:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C fixtures/reject/src/lib.rs:6:1: rust2-ffi: cannot export struct `Wrap`: generic type; exclude it in the config to leave it out fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclude it in the config to leave it out diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs index 06e2468ad..4d200fcf1 100644 --- a/ffi/fixtures/reject/src/lib.rs +++ b/ffi/fixtures/reject/src/lib.rs @@ -27,6 +27,11 @@ pub fn borrowing(name: &str) -> impl Future + '_ { async move { name.len() } } +/// An option inside an option, through a `Box`: C has one `None` per option. +pub fn nested(value: Option>>) -> bool { + value.is_some() +} + /// A static. pub static COUNT: u8 = 0; diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index cb1e97fe6..9cfc0af5b 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -1091,7 +1091,9 @@ impl<'tcx> Collector<'tcx> { Type::Duration } else if tcx.is_diagnostic_item(sym::Option, did) { let inner = self.ty(args.type_at(0), pos.inner())?; - if matches!(inner, Type::Option(_)) { + // C has one `None` per option, so it cannot hold one inside another, even + // through a `Box`. + if matches!(inner.base(), Type::Option(_)) { return Err(why("nested Option", ty.to_string())); } Type::Option(Box::new(inner)) diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 8e653f609..8b1fd298a 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -313,7 +313,8 @@ impl Gen<'_> { } if traits.eq { self.line(format!( - "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: {handle}, b: {handle}) -> bool {{\n\tlet w = \"{name}_eq\";\n\tlet a = {};\n\tlet b = {};\n\t<{path} as ::std::cmp::PartialEq>::eq(&*a, &*b)\n}}\n", + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: {handle}, b: {handle}) -> bool {{\n\tlet w = \"{name}_eq\";\n\t// One handle twice is one borrow, which an exclusive one must be.\n\tif a == b {{\n\t\tlet a = {};\n\t\treturn <{path} as ::std::cmp::PartialEq>::eq(&*a, &*a);\n\t}}\n\tlet a = {};\n\tlet b = {};\n\t<{path} as ::std::cmp::PartialEq>::eq(&*a, &*b)\n}}\n", + borrow("a"), borrow("a"), borrow("b") )); diff --git a/ffi/tests/api.c b/ffi/tests/api.c index f50940ae0..b96d90a07 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -163,6 +163,12 @@ static int script(void) { api_node_push(list, 2); printf("node %llu\n", (unsigned long long)api_node_sum(list)); api_node_free(list); + + api_tally *tally = api_tally_new(); + api_tally_bump(tally); + uint32_t count = api_tally_bump(tally); + printf("tally %u %s\n", count, api_tally_eq(tally, tally) ? "true" : "false"); + api_tally_free(tally); /* Each future dropped its waker once it finished. */ return drops == 3 ? 0 : 1; } From a06d781fc9e58b05660d0d3a71c468ae17a5195f Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sat, 24 Oct 2026 23:53:41 -0700 Subject: [PATCH 13/16] fix(ffi): follow the library's own name, and refuse a handle lent inside a value Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/src/rustc.rs | 10 ++++++---- ffi/README.md | 2 +- ffi/fixtures/api/Cargo.toml | 4 ++++ ffi/fixtures/api/examples/transcript.rs | 10 +++++----- ffi/fixtures/reject/expected.txt | 9 +++++---- ffi/fixtures/reject/src/lib.rs | 9 +++++++++ ffi/src/collect.rs | 11 ++++++++--- ffi/src/config.rs | 9 ++------- ffi/src/driver.rs | 4 ++-- ts/src/config.rs | 5 ----- ts/src/driver.rs | 2 +- 11 files changed, 43 insertions(+), 32 deletions(-) diff --git a/driver/src/rustc.rs b/driver/src/rustc.rs index 78a409c29..29fb8e346 100644 --- a/driver/src/rustc.rs +++ b/driver/src/rustc.rs @@ -45,9 +45,11 @@ struct Plain; impl Callbacks for Plain {} -/// Whether rustc's `args` compile the library of `crate_name`, not its tests. -pub fn compiles_lib(args: &[String], crate_name: &str) -> bool { - let name = args.windows(2).find(|w| w[0] == "--crate-name").map(|w| w[1].as_str()); +/// Whether rustc's `args` compile the library of the cargo package `package`, not its +/// tests. Cargo names the package being compiled in `CARGO_PKG_NAME`, whatever its +/// library target is called. +pub fn compiles_lib(args: &[String], package: &str) -> bool { + let ours = std::env::var("CARGO_PKG_NAME").is_ok_and(|name| name == package); let lib = args.windows(2).any(|w| w[0] == "--crate-type" && w[1] == "lib"); - name == Some(crate_name) && lib && !args.iter().any(|a| a == "--test") + ours && lib && !args.iter().any(|a| a == "--test") } diff --git a/ffi/README.md b/ffi/README.md index 17a49dde2..7f1df1946 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -19,7 +19,7 @@ shared library. ```toml # ffi.toml, beside the package's Cargo.toml unless --manifest-path says otherwise. package = "moq-net" -# The prefix of every C name, the crate name by default. +# The prefix of every C name, the package's name in snake case by default. prefix = "moq" # Paths from the crate root left out: a module, an item, or one method or field. Each # must name something exported. Nothing else leaves an item out. diff --git a/ffi/fixtures/api/Cargo.toml b/ffi/fixtures/api/Cargo.toml index 78c79a72b..aaa48e8eb 100644 --- a/ffi/fixtures/api/Cargo.toml +++ b/ffi/fixtures/api/Cargo.toml @@ -6,6 +6,10 @@ edition = "2024" license = "MIT OR Apache-2.0" publish = false +# Named apart from the package, which the export must follow. +[lib] +name = "api_lib" + [dependencies] bytes = "1.11.1" diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index 3afb06117..d46af2e7f 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -7,7 +7,7 @@ use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use std::task::{Context, Poll, Wake, Waker}; -use api_fixture::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Node, Point, Shape, Stamp, Tally}; +use api_lib::{Channel, Counter, Event, LIMIT, Log, Logger, Message, Node, Point, Shape, Stamp, Tally}; use bytes::Bytes; /// Keeps even levels, as `tests/api.c`'s implementation does. @@ -68,10 +68,10 @@ fn main() { let label = c.into_label(Some(p)); println!("label {label:?}"); - println!("{}", api_fixture::greet("x", Shape::Square)); - println!("len {}", api_fixture::len(b"abc")); + println!("{}", api_lib::greet("x", Shape::Square)); + println!("len {}", api_lib::len(b"abc")); for event in [Event::Moved(p), Event::Named { name: "n".to_string() }, Event::Done] { - println!("{}", api_fixture::describe(&event)); + println!("{}", api_lib::describe(&event)); } let stamp = Stamp::from_millis(2500); @@ -83,7 +83,7 @@ fn main() { println!("stamp {:?}", message.stamp.unwrap()); println!("sent {}", message.sent()); - println!("kept {}", api_fixture::emit(Print, vec![1, 2, 3, 4])); + println!("kept {}", api_lib::emit(Print, vec![1, 2, 3, 4])); let logger = Logger::new(Box::new(Print)); println!("write {}", logger.write("hi")); drop(logger); diff --git a/ffi/fixtures/reject/expected.txt b/ffi/fixtures/reject/expected.txt index 4d41e225c..4d2e14317 100644 --- a/ffi/fixtures/reject/expected.txt +++ b/ffi/fixtures/reject/expected.txt @@ -2,9 +2,10 @@ fixtures/reject/src/lib.rs:14:1: rust2-ffi: cannot export fn `map`: foreign type fixtures/reject/src/lib.rs:19:1: rust2-ffi: cannot export fn `generic`: generic parameter `std::marker::Copy`; exclude it in the config to leave it out fixtures/reject/src/lib.rs:26:1: rust2-ffi: cannot export fn `borrowing`: borrowing future from a function that is not async; exclude it in the config to leave it out fixtures/reject/src/lib.rs:31:1: rust2-ffi: cannot export fn `nested`: nested Option `std::option::Option>>`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:36:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:40:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:48:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out -fixtures/reject/src/lib.rs:59:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C +fixtures/reject/src/lib.rs:40:1: rust2-ffi: cannot export fn `peek`: reference to a handle inside a value `std::boxed::Box`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:45:1: rust2-ffi: cannot export static `COUNT`: static; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:49:1: rust2-ffi: cannot export macro `noop`: macro; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:57:1: rust2-ffi: cannot export fn `excluded`: excluded type `Excluded`; exclude it in the config to leave it out +fixtures/reject/src/lib.rs:68:2: rust2-ffi: fn `audio::encoder_finish` and fn `audio_encoder::finish` are both `reject_audio_encoder_finish` in C fixtures/reject/src/lib.rs:6:1: rust2-ffi: cannot export struct `Wrap`: generic type; exclude it in the config to leave it out fixtures/reject/src/lib.rs:9:1: rust2-ffi: cannot export fn `pair`: tuple; exclude it in the config to leave it out diff --git a/ffi/fixtures/reject/src/lib.rs b/ffi/fixtures/reject/src/lib.rs index 4d200fcf1..e7626c730 100644 --- a/ffi/fixtures/reject/src/lib.rs +++ b/ffi/fixtures/reject/src/lib.rs @@ -32,6 +32,15 @@ pub fn nested(value: Option>>) -> bool { value.is_some() } +/// An object, since its field is private. +pub struct Opaque(u8); + +/// A handle lent inside a `Box`: it would cross by value, moving it out of the caller's +/// handle for a call that only reads it. +pub fn peek(value: &Box) -> u8 { + value.0 +} + /// A static. pub static COUNT: u8 = 0; diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 9cfc0af5b..7c6081af3 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -16,7 +16,6 @@ use rustc_span::{Span, sym}; use rustc_trait_selection::infer::InferCtxtExt; use rustc_trait_selection::traits::query::evaluate_obligation::InferCtxtExt as _; -use crate::config::Config; use crate::ir::{ Access, Api, Callback, Constant, Dyn, Enum, Field, Function, Int, Literal, Mutability, Object, Param, Path, Receiver, Record, Traits, Type, Variant, @@ -93,7 +92,7 @@ struct Collector<'tcx> { } /// Collect the crate's exported API, leaving out what `exclude` names. -pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> Collected { +pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, exclude: &[String]) -> Collected { let bytes = tcx .crates(()) .iter() @@ -118,7 +117,8 @@ pub fn collect<'tcx>(tcx: TyCtxt<'tcx>, config: &Config, exclude: &[String]) -> twins: Vec::new(), bytes, api: Api { - krate: config.crate_name(), + // The library's name, which may not be the package's. + krate: tcx.crate_name(rustc_hir::def_id::LOCAL_CRATE).to_string(), records: Vec::new(), enums: Vec::new(), objects: Vec::new(), @@ -1071,6 +1071,11 @@ impl<'tcx> Collector<'tcx> { } (_, Pos::Field, _) => return Err(why("reference field", inner.to_string())), (Type::Object(_), Pos::Param, _) => {} + // Lent only through a handle: one inside a `Box` or `Option` crosses by + // value, which would move it out of the caller's handle. + (_, Pos::Param, _) if self.holds_handle(*inner) => { + return Err(why("reference to a handle inside a value", inner.to_string())); + } (_, Pos::Param, Mutability::Mut) => return Err(why("&mut of a value", inner.to_string())), _ => {} } diff --git a/ffi/src/config.rs b/ffi/src/config.rs index 031f17f9d..a96ece212 100644 --- a/ffi/src/config.rs +++ b/ffi/src/config.rs @@ -10,7 +10,7 @@ use serde::Deserialize; pub struct Config { /// The cargo package whose library is exported. pub package: String, - /// The prefix of every C name, the crate name by default. + /// The prefix of every C name, the package's name in snake case by default. pub prefix: Option, /// Paths from the crate root left out of the export: a module, an item, or one /// method (`track::Producer::poll_closed`). Each must name something exported. @@ -29,14 +29,9 @@ impl Config { toml::from_str(&text).map_err(|err| format!("parsing {}: {err}", path.display())) } - /// The library's crate name, as rustc is given it. - pub fn crate_name(&self) -> String { - self.package.replace('-', "_") - } - /// The prefix of every C name. pub fn prefix(&self) -> String { - self.prefix.clone().unwrap_or_else(|| self.crate_name()) + self.prefix.clone().unwrap_or_else(|| self.package.replace('-', "_")) } } diff --git a/ffi/src/driver.rs b/ffi/src/driver.rs index ac92b313d..f99fa62a6 100644 --- a/ffi/src/driver.rs +++ b/ffi/src/driver.rs @@ -43,7 +43,7 @@ impl Export { return Ok(None); }; let config = Config::load(path.as_ref())?; - if !rust2_driver::rustc::compiles_lib(args, &config.crate_name()) { + if !rust2_driver::rustc::compiles_lib(args, &config.package) { return Ok(None); } let output = match ( @@ -85,7 +85,7 @@ impl Callbacks for Export { Output::Census(_) => &[][..], Output::Dir(_) => &self.config.exclude[..], }; - let collected = collect::collect(tcx, &self.config, exclude); + let collected = collect::collect(tcx, exclude); let written = match &self.output { Output::Census(path) => { let abi = Abi::new(&collected.api, &self.config.prefix(), &self.config.rename); diff --git a/ts/src/config.rs b/ts/src/config.rs index 8b2ef1f1c..88abccf4c 100644 --- a/ts/src/config.rs +++ b/ts/src/config.rs @@ -28,11 +28,6 @@ impl Config { let text = std::fs::read_to_string(path).map_err(|err| format!("reading {}: {err}", path.display()))?; toml::from_str(&text).map_err(|err| format!("parsing {}: {err}", path.display())) } - - /// The library's crate name, as rustc is given it. - pub fn crate_name(&self) -> String { - self.package.replace('-', "_") - } } /// Environment variables the CLI hands the wrapper. diff --git a/ts/src/driver.rs b/ts/src/driver.rs index 8bed02e92..d9a39e1d2 100644 --- a/ts/src/driver.rs +++ b/ts/src/driver.rs @@ -52,7 +52,7 @@ impl Translate { return Ok(None); }; let config = Config::load(path.as_ref())?; - if !rust2_driver::rustc::compiles_lib(args, &config.crate_name()) { + if !rust2_driver::rustc::compiles_lib(args, &config.package) { return Ok(None); } let output = match ( From 72dcb0ae9a1e508b5b6ebfb7bb309b11386b4030 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sun, 25 Oct 2026 00:08:59 -0700 Subject: [PATCH 14/16] fix(ffi): keep types with their own Drop behind handles; drivers accept rlib and fail when no library ran Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/src/cargo.rs | 20 ++++++++++++++++---- driver/src/rustc.rs | 16 ++++++++++++++-- ffi/README.md | 4 ++-- ffi/fixtures/api/examples/transcript.rs | 5 +++++ ffi/fixtures/api/src/lib.rs | 25 +++++++++++++++++++++++++ ffi/src/collect.rs | 3 +++ ffi/tests/api.c | 6 ++++++ 7 files changed, 71 insertions(+), 8 deletions(-) diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs index 4e20246ec..8165ed763 100644 --- a/driver/src/cargo.rs +++ b/driver/src/cargo.rs @@ -140,17 +140,29 @@ impl Check<'_> { cmd }; run_cargo(cargo("clean").arg("--quiet"))?; + let ran = target_dir.join(format!("{}.ran", self.tool)); + match std::fs::remove_file(&ran) { + Err(err) if err.kind() != std::io::ErrorKind::NotFound => { + return Err(format!("removing {}: {err}", ran.display())); + } + _ => {} + } let status = cargo("check") .arg("--lib") .args(self.args) .env("RUSTC_WRAPPER", &exe) + .env(crate::rustc::RAN, &ran) .envs(self.env.iter().copied()) .status() .map_err(|err| format!("running cargo: {err}"))?; - Ok(match status.success() { - true => ExitCode::SUCCESS, - false => ExitCode::FAILURE, - }) + if !status.success() { + return Ok(ExitCode::FAILURE); + } + // A library the wrapper never recognized would otherwise succeed with nothing written. + if !ran.exists() { + return Err(format!("cargo compiled no library of package {}", self.package)); + } + Ok(ExitCode::SUCCESS) } } diff --git a/driver/src/rustc.rs b/driver/src/rustc.rs index 29fb8e346..0080a418d 100644 --- a/driver/src/rustc.rs +++ b/driver/src/rustc.rs @@ -35,11 +35,21 @@ pub fn run( Err(err) => early_dcx.early_fatal(format!("{tool}: {err}")), }; rustc_driver::catch_with_exit_code(|| match job { - Some(mut job) => rustc_driver::compiler_entrypoint(&args, job.as_mut()), + Some(mut job) => { + rustc_driver::compiler_entrypoint(&args, job.as_mut()); + // Tell the CLI its library was compiled with the job. + if let Some(ran) = std::env::var_os(RAN) { + let _ = std::fs::write(ran, ""); + } + } None => rustc_driver::compiler_entrypoint(&args, &mut Plain), }) } +/// The file the wrapper creates once it has run a job, so the CLI knows cargo compiled +/// the configured library at all. +pub(crate) const RAN: &str = "RUST2_DRIVER_RAN"; + /// Compiles a crate as rustc would. struct Plain; @@ -50,6 +60,8 @@ impl Callbacks for Plain {} /// library target is called. pub fn compiles_lib(args: &[String], package: &str) -> bool { let ours = std::env::var("CARGO_PKG_NAME").is_ok_and(|name| name == package); - let lib = args.windows(2).any(|w| w[0] == "--crate-type" && w[1] == "lib"); + let lib = args + .windows(2) + .any(|w| w[0] == "--crate-type" && matches!(w[1].as_str(), "lib" | "rlib")); ours && lib && !args.iter().any(|a| a == "--test") } diff --git a/ffi/README.md b/ffi/README.md index 7f1df1946..c88237a4a 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -38,8 +38,8 @@ export nothing of their own. | Rust | C | | --- | --- | -| a struct whose fields are all `pub`, not `#[non_exhaustive]`, and which map | a record: a struct, copied across | -| an enum whose fields map | a C enum without fields, or a struct of a tag and a union | +| a struct whose fields are all `pub`, not `#[non_exhaustive]`, which map, with no `Drop` of its own | a record: a struct, copied across | +| an enum whose fields map, with no `Drop` of its own | a C enum without fields, or a struct of a tag and a union | | any other type, if `Send` | an object: an opaque handle to an `Arc`, freed with `_free` | | a `pub` field of an object | a getter returning a copy | | a `pub` trait | a callback interface: a table of C functions and their data | diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index d46af2e7f..0dff6ac1f 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -127,4 +127,9 @@ fn main() { let tally = Tally::new(); tally.bump(); println!("tally {} {}", tally.bump(), tally == tally); + + let token = api_lib::Token::new(7); + println!("token {} dropped {}", token.id, api_lib::dropped()); + drop(token); + println!("dropped {}", api_lib::dropped()); } diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index a538a6fc6..0f5e90346 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -304,6 +304,31 @@ impl Tally { } } +static DROPPED: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0); + +/// A token: every field is `pub`, but its `Drop` must run when C frees it, so it is an +/// object rather than a record. +pub struct Token { + pub id: u32, +} + +impl Token { + pub fn new(id: u32) -> Self { + Self { id } + } +} + +impl Drop for Token { + fn drop(&mut self) { + DROPPED.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + } +} + +/// How many tokens have dropped. +pub fn dropped() -> u32 { + DROPPED.load(std::sync::atomic::Ordering::Relaxed) +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/src/collect.rs b/ffi/src/collect.rs index 7c6081af3..beb94461d 100644 --- a/ffi/src/collect.rs +++ b/ffi/src/collect.rs @@ -242,6 +242,9 @@ impl<'tcx> Collector<'tcx> { let decl = match tcx.def_kind(def_id) { DefKind::Union => Decl::Refused(why("union", "")), DefKind::Struct | DefKind::Enum | DefKind::Trait if generic() => Decl::Refused(why("generic type", "")), + // A value is copied across and lowered into memory C frees, so its own `Drop` + // would run when Rust lets go of it, not when C does. + DefKind::Struct | DefKind::Enum if tcx.adt_destructor(def_id).is_some() => self.object(def_id), DefKind::Struct => { let variant = tcx.adt_def(def_id).non_enum_variant(); let record = !variant.fields.is_empty() diff --git a/ffi/tests/api.c b/ffi/tests/api.c index b96d90a07..830e00cb3 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -169,6 +169,12 @@ static int script(void) { uint32_t count = api_tally_bump(tally); printf("tally %u %s\n", count, api_tally_eq(tally, tally) ? "true" : "false"); api_tally_free(tally); + + /* Its Drop runs when C frees the handle, not before. */ + api_token *token = api_token_new(7); + printf("token %u dropped %u\n", api_token_id(token), api_dropped()); + api_token_free(token); + printf("dropped %u\n", api_dropped()); /* Each future dropped its waker once it finished. */ return drops == 3 ? 0 : 1; } From 46c5fa2ee5d95b7b15f40ed1bfc710c78f971417 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sun, 25 Oct 2026 00:18:35 -0700 Subject: [PATCH 15/16] fix(driver): a marker per run, since runs share a target directory Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/src/cargo.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs index 8165ed763..0b8021d17 100644 --- a/driver/src/cargo.rs +++ b/driver/src/cargo.rs @@ -140,7 +140,8 @@ impl Check<'_> { cmd }; run_cargo(cargo("clean").arg("--quiet"))?; - let ran = target_dir.join(format!("{}.ran", self.tool)); + // Its own, since runs may share a target directory. + let ran = target_dir.join(format!("{}-{}.ran", self.tool, std::process::id())); match std::fs::remove_file(&ran) { Err(err) if err.kind() != std::io::ErrorKind::NotFound => { return Err(format!("removing {}: {err}", ran.display())); @@ -159,7 +160,9 @@ impl Check<'_> { return Ok(ExitCode::FAILURE); } // A library the wrapper never recognized would otherwise succeed with nothing written. - if !ran.exists() { + let compiled = ran.exists(); + let _ = std::fs::remove_file(&ran); + if !compiled { return Err(format!("cargo compiled no library of package {}", self.package)); } Ok(ExitCode::SUCCESS) From e67985325450b473b4f0bcfa1d516e2e37c8d2ed Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Sun, 25 Oct 2026 00:22:21 -0700 Subject: [PATCH 16/16] fix(ffi): share a value that is not Sync on one thread, and take a relative target directory as the caller's Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0115AT2ue6x9cT5e5J9SZtCn --- driver/src/cargo.rs | 3 +- ffi/README.md | 3 +- ffi/fixtures/api/examples/transcript.rs | 1 + ffi/fixtures/api/src/lib.rs | 5 +++ ffi/runtime/rt.rs | 57 ++++++++++++++++++++++++- ffi/src/glue.rs | 36 +++++++++------- ffi/src/ir.rs | 2 +- ffi/tests/api.c | 1 + ffi/tests/fixtures.rs | 23 ++++++++++ 9 files changed, 112 insertions(+), 19 deletions(-) diff --git a/driver/src/cargo.rs b/driver/src/cargo.rs index 0b8021d17..0002eb8df 100644 --- a/driver/src/cargo.rs +++ b/driver/src/cargo.rs @@ -118,7 +118,8 @@ impl Check<'_> { pub fn run(&self) -> Result { let exe = std::env::current_exe().map_err(|err| format!("finding this executable: {err}"))?; let target_dir = match std::env::var_os("CARGO_TARGET_DIR") { - Some(dir) => PathBuf::from(dir), + // Absolute, as the caller meant it: cargo runs in the package's directory. + Some(dir) => absolute(Path::new(&dir))?, // Apart from the workspace's own builds, which a different rustc would invalidate. None => workspace_root(self.manifest)?.join("target").join(self.tool), }; diff --git a/ffi/README.md b/ffi/README.md index c88237a4a..1e42fb298 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -65,7 +65,8 @@ new one. Everything else is refused, and the census counts why. - **Handles** are `Arc`s, and a call borrows the value as Rust's receiver or parameter does, checked at run time: shared for `&T`, exclusive for `&mut T`, and moved out for `T`, after which the handle is only freed. A `Copy` value is copied out instead, and a - value that is not `Sync` is borrowed exclusively even through `&T`. A borrow Rust would + value that is not `Sync` is shared on one thread at a time, and held exclusively by a + future, which may be polled on any thread. A borrow Rust would refuse at compile time aborts, naming the function, as does a null or moved-out handle: there is no Rust caller to return an error to. - **Values** are copied in from the caller's memory, which Rust never frees, and lowered diff --git a/ffi/fixtures/api/examples/transcript.rs b/ffi/fixtures/api/examples/transcript.rs index 0dff6ac1f..f422acf8f 100644 --- a/ffi/fixtures/api/examples/transcript.rs +++ b/ffi/fixtures/api/examples/transcript.rs @@ -127,6 +127,7 @@ fn main() { let tally = Tally::new(); tally.bump(); println!("tally {} {}", tally.bump(), tally == tally); + println!("both {}", api_lib::bump_both(&tally, &tally)); let token = api_lib::Token::new(7); println!("token {} dropped {}", token.id, api_lib::dropped()); diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index 0f5e90346..8a7f1e244 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -329,6 +329,11 @@ pub fn dropped() -> u32 { DROPPED.load(std::sync::atomic::Ordering::Relaxed) } +/// Both tallies bumped: C may pass one handle twice, which Rust allows of `&`. +pub fn bump_both(a: &Tally, b: &Tally) -> u32 { + a.bump() + b.bump() +} + /// The length of a payload, borrowed for the call. pub fn len(payload: &[u8]) -> usize { payload.len() diff --git a/ffi/runtime/rt.rs b/ffi/runtime/rt.rs index e064a6e31..b202f9b1e 100644 --- a/ffi/runtime/rt.rs +++ b/ffi/runtime/rt.rs @@ -136,12 +136,22 @@ const TAKEN: usize = usize::MAX - 1; /// A value behind a handle: shared through an `Arc`, and borrowed as Rust borrows it, with /// the borrow checked at run time. `state` counts shared borrows, or is [`EXCLUSIVE`] -/// while one exclusive borrow lasts, or [`TAKEN`] once the value moved out. +/// while one exclusive borrow lasts, or [`TAKEN`] once the value moved out. A value that is +/// not `Sync` is shared on one thread at a time instead: `state` is that thread's id, and +/// `depth` counts its borrows, which only that thread touches. pub struct Object { state: AtomicUsize, + depth: UnsafeCell, value: UnsafeCell>, } +/// This thread's id for [`Object::borrow_local`]: the address of a thread local, which no +/// other live thread shares and which is neither 0 nor a sentinel. +fn thread() -> usize { + thread_local!(static ID: u8 = const { 0 }); + ID.with(|id| std::ptr::from_ref(id) as usize) +} + // SAFETY: the value moves between threads only by `take` or an exclusive borrow, and is // shared only by shared borrows, which the export takes only of `Sync` types. unsafe impl Send for Object {} @@ -153,6 +163,7 @@ impl Object { pub fn new(value: T) -> *const c_void { Arc::into_raw(Arc::new(Self { state: AtomicUsize::new(0), + depth: UnsafeCell::new(0), value: UnsafeCell::new(ManuallyDrop::new(value)), })) .cast() @@ -209,6 +220,27 @@ impl Object { Shared { object } } + /// Borrow a value that is not `Sync` shared for a call: any number of times on one + /// thread, as Rust allows, and on no other thread meanwhile. + /// + /// # Safety + /// As [`Self::borrow`]. + pub unsafe fn borrow_local<'a>(handle: *const c_void, what: &str) -> Local<'a, T> { + // SAFETY: the caller's contract. + let object = unsafe { Self::get(handle, what) }; + let me = thread(); + match object.state.compare_exchange(0, me, Ordering::Acquire, Ordering::Relaxed) { + Ok(_) => {} + Err(owner) if owner == me => {} + Err(TAKEN) => fail(what, "a handle's value was moved out"), + Err(EXCLUSIVE) => fail(what, "a handle is borrowed exclusively"), + Err(_) => fail(what, "a handle is borrowed on another thread"), + } + // SAFETY: only the thread in `state` touches `depth`. + unsafe { *object.depth.get() += 1 }; + Local { object } + } + /// Borrow the value exclusively for a call. /// /// # Safety @@ -314,6 +346,29 @@ impl Drop for Shared<'_, T> { } } +pub struct Local<'a, T> { + object: &'a Object, +} + +impl Deref for Local<'_, T> { + type Target = T; + fn deref(&self) -> &T { + // SAFETY: this thread holds the value shared. + unsafe { &*self.object.value.get() } + } +} + +impl Drop for Local<'_, T> { + fn drop(&mut self) { + // SAFETY: this thread is the one in `state`, so `depth` is its own. + let depth = unsafe { &mut *self.object.depth.get() }; + *depth -= 1; + if *depth == 0 { + self.object.state.store(0, Ordering::Release); + } + } +} + pub struct Exclusive<'a, T> { object: &'a Object, } diff --git a/ffi/src/glue.rs b/ffi/src/glue.rs index 8b1fd298a..bee9963f3 100644 --- a/ffi/src/glue.rs +++ b/ffi/src/glue.rs @@ -153,19 +153,26 @@ impl Gen<'_> { true => format!("lift_{}({e}, w)", self.abi.enumeration(*i)), false => format!("lift_{}(&{e}, w)", self.abi.enumeration(*i)), }, - // A value that is not `Sync` may change through `&self`, so it is read exclusively. - Type::Object(i) => match (self.abi.api.objects[*i].copy, self.abi.api.objects[*i].sync) { - (true, true) => format!("*unsafe {{ rt::Object::<{}>::borrow({e}, w) }}", self.object_path(*i)), - (true, false) => format!( - "*unsafe {{ rt::Object::<{}>::borrow_mut({e}, w) }}", - self.object_path(*i) + Type::Object(i) => match self.abi.api.objects[*i].copy { + true => format!( + "*unsafe {{ rt::Object::<{}>::{}({e}, w) }}", + self.object_path(*i), + self.shared(*i) ), - (false, _) => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), + false => format!("unsafe {{ rt::Object::<{}>::take({e}, w) }}", self.object_path(*i)), }, Type::Callback(i, form) => abi::dyn_wrap(*form, &format!("Foreign_{}({e})", self.abi.callback(*i))), } } + /// How a call borrows object `i` shared: across threads if it is `Sync`, else on one. + fn shared(&self, i: usize) -> &'static str { + match self.abi.api.objects[i].sync { + true => "borrow", + false => "borrow_local", + } + } + /// The C value of the Rust value `e` of type `ty`, which the caller frees. fn lower(&self, ty: &Type, e: &str) -> String { match ty { @@ -282,10 +289,7 @@ impl Gen<'_> { self.line(format!( "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_free(this: *const c_void) {{\n\tunsafe {{ rt::Object::<{path}>::free(this) }}\n}}\n" )); - let borrow = match object.sync { - true => "borrow", - false => "borrow_mut", - }; + let borrow = self.shared(i); self.traits(&name, &path, object.traits, |e| { format!("unsafe {{ rt::Object::<{path}>::{borrow}({e}, w) }}") }); @@ -313,8 +317,7 @@ impl Gen<'_> { } if traits.eq { self.line(format!( - "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: {handle}, b: {handle}) -> bool {{\n\tlet w = \"{name}_eq\";\n\t// One handle twice is one borrow, which an exclusive one must be.\n\tif a == b {{\n\t\tlet a = {};\n\t\treturn <{path} as ::std::cmp::PartialEq>::eq(&*a, &*a);\n\t}}\n\tlet a = {};\n\tlet b = {};\n\t<{path} as ::std::cmp::PartialEq>::eq(&*a, &*b)\n}}\n", - borrow("a"), + "#[unsafe(no_mangle)]\npub unsafe extern \"C\" fn {name}_eq(a: {handle}, b: {handle}) -> bool {{\n\tlet w = \"{name}_eq\";\n\tlet a = {};\n\tlet b = {};\n\t<{path} as ::std::cmp::PartialEq>::eq(&*a, &*b)\n}}\n", borrow("a"), borrow("b") )); @@ -674,9 +677,12 @@ impl Gen<'_> { match ty { Type::Ref(m, inner) => match (&**inner, m, future) { (Type::Object(i), _, _) => { - let exclusive = *m == Mutability::Mut || !self.abi.api.objects[*i].sync; + let sync = self.abi.api.objects[*i].sync; + // A future may be polled on any thread, so it holds a value that is not + // `Sync` exclusively. + let exclusive = *m == Mutability::Mut || (future && !sync); let borrow = match (exclusive, future) { - (false, false) => "borrow", + (false, false) => self.shared(*i), (true, false) => "borrow_mut", (false, true) => "borrow_arc", (true, true) => "borrow_mut_arc", diff --git a/ffi/src/ir.rs b/ffi/src/ir.rs index f73a4666b..e07a1f60b 100644 --- a/ffi/src/ir.rs +++ b/ffi/src/ir.rs @@ -74,7 +74,7 @@ pub struct Object { pub path: Path, pub span: Span, pub docs: String, - /// Whether it is `Sync`: if not, even its `&self` methods borrow it exclusively. + /// Whether it is `Sync`: if not, `&self` borrows it on one thread at a time. pub sync: bool, /// Whether it is `Copy`: taken by value, it is copied out of its handle, as Rust /// copies it, rather than moved out. diff --git a/ffi/tests/api.c b/ffi/tests/api.c index 830e00cb3..9c1fc0907 100644 --- a/ffi/tests/api.c +++ b/ffi/tests/api.c @@ -168,6 +168,7 @@ static int script(void) { api_tally_bump(tally); uint32_t count = api_tally_bump(tally); printf("tally %u %s\n", count, api_tally_eq(tally, tally) ? "true" : "false"); + printf("both %u\n", api_bump_both(tally, tally)); api_tally_free(tally); /* Its Drop runs when C frees the handle, not before. */ diff --git a/ffi/tests/fixtures.rs b/ffi/tests/fixtures.rs index 7cbaaa135..7cb49091d 100644 --- a/ffi/tests/fixtures.rs +++ b/ffi/tests/fixtures.rs @@ -107,6 +107,29 @@ fn api() { } } +/// A relative `CARGO_TARGET_DIR` is the caller's, wherever cargo runs. +#[test] +fn relative_target() { + let dir = scratch().join("relative"); + std::fs::create_dir_all(&dir).unwrap(); + let census = dir.join("census.md"); + let output = Command::new(env!("CARGO_BIN_EXE_rust2-ffi")) + .arg("--config") + .arg(manifest_dir().join("fixtures/api/ffi.toml")) + .arg("--census") + .arg(&census) + .current_dir(&dir) + .env("CARGO_TARGET_DIR", "build") + .output() + .expect("running rust2-ffi"); + assert!( + output.status.success(), + "the census failed:\n{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(census.exists() && dir.join("build").exists()); +} + #[test] fn reject() { let out = scratch().join("reject").join("out");