//! The C++ header: header-only classes over the C header's declarations, from C++17, with //! exceptions and RTTI on or off. //! //! Each name is its C name without the prefix, in a namespace of the prefix: `moq_track` //! is `moq::track`, and a method is its C name without its type's (`moq_track_close` is //! `moq::track::close`). C names are unique, so these are too, once a keyword, or a member //! named as its class or a field, takes a trailing `_`; so does a parameter named as a //! member or as anything in the namespace, which it would hide. An object is a class owning //! its handle through a `std::unique_ptr`, so it moves, or where `Clone` makes a value no //! call tells apart but by an `Arc`'s or `Rc`'s count, a `std::shared_ptr` its copies //! share; a record a struct, and a `Copy` type with private fields a class over its C //! struct's bytes, which only Rust makes or reads; an enum an //! `enum class`, or for one with data a `std::variant` of a struct per variant, with its //! methods free functions; a closure, a future, or a reader C++ implements a template //! parameter. The runtime they share, [`runtime/rt.hpp`](../runtime/rt.hpp), holds the //! handles, bytes, results, wakers, futures, and readers. //! //! The items are split into a header per crate, each including the shared `rt.hpp`, which //! holds the runtime and declares every type, and the headers of the crates its items name, //! all before it in dependency order: a class declares each of its methods, and the header //! of the crate the method belongs to, which an instance makes a later one, defines it. //! `.hpp` includes them all. use std::collections::{BTreeMap, BTreeSet}; use crate::abi::{self, Abi, Ty}; use crate::c::decl; use crate::ir::{Closure, Family, Function, Int, Literal, Receiver, Traits, Type}; const RUNTIME: &str = include_str!("../runtime/rt.hpp"); /// The generated C++ headers and their public names. pub(crate) struct Output { /// Each header by its path under `include/`. pub(crate) files: Vec<(String, String)>, pub(crate) names: BTreeMap, } /// The headers for `abi`: the umbrella `.hpp`, the shared `/rt.hpp`, and a /// `/.hpp` per crate; or the members two items name alike. pub(crate) fn headers(abi: &Abi<'_>, packages: &str) -> Result { let p = &abi.prefix; let mut h = Header { locked: BTreeMap::new(), abi, ns: p.clone(), krate: String::new(), files: crate::go::packages(abi), out: String::new(), defs: String::new(), hashes: String::new(), defined: BTreeSet::new(), globals: runtime_names().map(str::to_string).collect(), errors: Vec::new(), }; // A C++ class is named by its C name alone. let api = abi.api; let classes = (0..api.records.len()) .map(|i| abi.record(i)) .chain((0..api.enums.len()).map(|i| abi.enumeration(i))) .chain((0..api.objects.len()).map(|i| abi.object(i))) .chain((0..api.callbacks.len()).map(|i| abi.callback(i))) .map(|c| { let name = h.name(&c); (c, name) }) .collect(); h.locked = crate::lock::types(abi, &classes); let mut headers = vec![(format!("{p}/rt.hpp"), h.shared(packages))]; let guard = format!("{}_HPP", p.to_uppercase()); let mut umbrella = format!( "// Generated by rust2-ffi: C++ over the C ABI of the pub API of {packages}, every crate's\n// header. Do not edit.\n\n#ifndef {guard}\n#define {guard}\n\n#include \"{p}/rt.hpp\"\n" ); for krate in &abi.api.crates { let name = h.files[krate].clone(); headers.push((format!("{p}/{name}.hpp"), h.krate(krate, packages))); umbrella.push_str(&format!("#include \"{p}/{name}.hpp\"\n")); } umbrella.push_str(&format!("\n#endif // {guard}\n")); headers.insert(0, (format!("{p}.hpp"), umbrella)); match h.errors.is_empty() { true => Ok(Output { files: headers, names: h.locked, }), false => Err(h.errors.join("\n")), } } /// How a method's type holds it. #[derive(Clone, Copy, PartialEq, Eq)] enum Owner { /// A class's member. Member, /// A free function whose first parameter is the value: an enum's. Free, } struct Header<'a> { locked: BTreeMap, abi: &'a Abi<'a>, ns: String, /// The crate whose header this writes, or none for the shared one. krate: String, /// Each crate's header's name, by crate. files: BTreeMap, /// The declarations, in the order C++ needs them. out: String, /// The definitions, after every type is complete. defs: String, /// `std::hash` of each class Rust hashes, after the namespace. hashes: String, /// The value types written so far, so each is written after what it holds. defined: BTreeSet, /// The names declared in the namespace, which a parameter named alike would hide. globals: BTreeSet, errors: Vec, } impl<'a> Header<'a> { fn line(&mut self, line: impl AsRef) { self.out.push_str(line.as_ref()); self.out.push('\n'); } fn def(&mut self, line: impl AsRef) { self.defs.push_str(line.as_ref()); self.defs.push('\n'); } /// A C name without the prefix, as C++ names it. fn name(&self, c: &str) -> String { escape(&c[self.abi.prefix.len() + 1..]) } /// A C name's C++ name, qualified. fn q(&self, c: &str) -> String { format!("::{}::{}", self.ns, self.name(c)) } /// The namespace's `detail`, qualified. fn d(&self) -> String { format!("::{}::detail", self.ns) } /// The names of `==`'s two arguments, apart from every name in the namespace, which /// they would hide. fn operands(&self) -> (String, String) { let a = parameter("a", |n| self.globals.contains(n)); let b = parameter("b", |n| self.globals.contains(n) || n == a); (a, b) } /// `name`, declared in the namespace. fn global(&mut self, name: &str) -> String { self.globals.insert(name.to_string()); name.to_string() } /// The C++ type of `ty` as a value: a field, or what a function returns, owning what /// it holds. fn owned(&self, ty: &Type) -> String { let abi = self.abi; match ty { Type::Const(_) => unreachable!("a const argument is no value"), Type::Jni(_) => unreachable!("only Kotlin exports what takes a JNI value"), Type::Array(n) => format!("::std::array<::std::uint8_t, {n}>"), Type::Unit => "void".to_string(), Type::Bool => "bool".to_string(), Type::Int(int) | Type::NonZero(int) => cpp_int(*int).to_string(), Type::F32 => "float".to_string(), Type::F64 => "double".to_string(), Type::Char => "char32_t".to_string(), Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes | Type::Path | Type::PathBuf => { format!("::{}::buf", self.ns) } Type::U128 => format!("::{}::u128", self.ns), Type::Duration => format!("::{}::duration", self.ns), Type::SocketAddr(family) => format!("::{}::{}", self.ns, crate::abi::addr(true, *family)), Type::IpAddr(family) => format!("::{}::{}", self.ns, crate::abi::addr(false, *family)), Type::List(_, inner) => format!("::std::vector<{}>", self.owned(inner)), Type::Waker => format!("::{}::waker", self.ns), Type::Option(inner) => format!("::std::optional<{}>", self.owned(inner)), Type::Box(inner) | Type::Ref(_, inner) => self.owned(inner), Type::Record(i) => self.q(&abi.record(*i)), Type::Enum(i) => self.q(&abi.enumeration(*i)), Type::Object(i) => self.q(&abi.object(*i)), Type::Callback(i, _) => format!("::std::unique_ptr<{}>", self.q(&abi.callback(*i))), Type::Closure(..) | Type::Future | Type::Reader => unreachable!("{ty:?} is a template parameter"), Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => self.q(&abi.range(ty)), Type::Tuple(elements) => { let elements: Vec = elements.iter().map(|e| self.owned(e)).collect(); format!("::std::tuple<{}>", elements.join(", ")) } } } /// The C++ type of a parameter of type `ty`. fn param(&self, ty: &Type) -> String { let abi = self.abi; // A value Rust writes back, through the caller's own. if let Type::Ref(_, inner) = ty && ty.written() { return format!("{} &", self.owned(inner)); } // Passed by value, so a `buf` Rust made moves back without a copy. if Abi::is_buf(ty) { return format!("::{}::input", self.ns); } match ty { Type::Option(inner) if Abi::is_buf(inner) => format!("::std::optional<::{}::input>", self.ns), // Moved out of, each handle as a handle taken by value is. Type::Option(inner) if matches!(inner.base(), Type::List(_, elem) if moves(abi, elem)) => { format!("::std::optional<{}>", self.items(inner.base())) } Type::Option(inner) if matches!(inner.base(), Type::List(..)) => { format!("const ::std::optional<{}> &", self.items(inner.base())) } // Moved out of, each handle as a handle taken by value is. Type::List(_, inner) if moves(abi, inner) => self.items(ty), Type::List(..) => format!("const {} &", self.items(ty)), Type::Option(inner) => match &**inner { // Lent, or copied out: a pointer, null for none. Type::Ref(m, object) if matches!(**object, Type::Object(_)) => { let constant = match m { crate::ir::Mutability::Not => "const ", crate::ir::Mutability::Mut => "", }; format!("{constant}{} *", self.owned(object)) } Type::Object(i) if abi.api.objects[*i].copy => format!("const {} *", self.owned(inner)), // Moved out of, as a handle taken by value is. _ if moves(abi, inner) => format!("::std::optional<{}>", self.held(inner)), _ => format!("const ::std::optional<{}> &", self.held(inner)), }, Type::Waker => format!("const ::{}::waker &", self.ns), Type::Ref(m, inner) if matches!(**inner, Type::Object(_)) => match m { crate::ir::Mutability::Not => format!("const {} &", self.owned(inner)), crate::ir::Mutability::Mut => format!("{} &", self.owned(inner)), }, Type::Ref(_, inner) | Type::Box(inner) => self.param(inner), Type::Object(i) if abi.api.objects[*i].copy => format!("const {} &", self.owned(ty)), Type::Record(_) | Type::Array(_) | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => { format!("const {} &", self.owned(ty)) } Type::Enum(i) if !abi.api.enums[*i].plain() => format!("const {} &", self.owned(ty)), // Moved out of, each handle as a handle taken by value is. Type::Tuple(_) if moves(abi, ty) => self.held(ty), Type::Tuple(_) => format!("const {} &", self.held(ty)), ty => self.owned(ty), } } /// The C++ type a `Vec` parameter of type `ty` takes: a vector, or, when its items hold /// views, the runtime's `items` lent or `taken` when they move handles, each of which /// also takes a returned vector of `buf`s as it is. fn items(&self, ty: &Type) -> String { let Type::List(_, inner) = ty else { unreachable!("{ty:?} is no Vec") }; let held = self.held(inner); match (held == self.owned(inner), moves(self.abi, inner)) { (true, _) => format!("::std::vector<{held}>"), (false, true) => format!("::{}::taken<{held}>", self.ns), (false, false) => format!("::{}::items<{held}>", self.ns), } } /// The C++ type a parameter's `Vec`, `Option`, or tuple holds a `ty` as: bytes as a view. fn held(&self, ty: &Type) -> String { match ty { ty if Abi::is_buf(ty) => format!("::{}::view", self.ns), Type::Tuple(elements) => { let elements: Vec = elements.iter().map(|e| self.held(e)).collect(); format!("::std::tuple<{}>", elements.join(", ")) } ty => self.owned(ty), } } /// Whether lowering a `ty` lowers a `Vec`, whose array lives in the arena `a_` until /// the call returns. fn arena(&self, ty: &Type) -> bool { let api = self.abi.api; match ty { // A block crosses in place. Type::List(..) if ty.block().is_some() => false, Type::List(..) => true, Type::Option(inner) | Type::Box(inner) | Type::Ref(_, inner) => self.arena(inner), Type::Tuple(elements) => elements.iter().any(|e| self.arena(e)), Type::Record(i) => api.records[*i].fields.iter().any(|f| self.arena(&f.ty)), Type::Enum(i) => (api.enums[*i].variants.iter()).any(|v| v.fields.iter().any(|f| self.arena(&f.ty))), _ => false, } } /// The arena a value's `lower` takes, if it lowers a `Vec`. fn arena_param(&self, ty: &Type) -> String { match self.arena(ty) { true => format!(", {}::arena &a_", self.d()), false => String::new(), } } /// The status a record's or enum's trait function takes, if a handle in it is checked: /// null, so a failed check aborts, as each other call of C++'s does. fn value_status(&self, ty: &Type) -> &'static str { match self.abi.value_status(ty) { true => ", nullptr", false => "", } } /// The arena a body lowering each of `tys` declares, if one needs it. fn scope<'t>(&self, tys: impl IntoIterator) -> String { match tys.into_iter().any(|ty| self.arena(ty)) { true => format!( " {}::arena a_; ", self.d() ), false => String::new(), } } /// Whether [`Self::arg`] takes Rust's bytes from a parameter of type `ty`. fn takes(ty: &Type) -> bool { match ty { _ if Abi::is_buf(ty) => true, Type::Option(inner) => Abi::is_buf(inner), Type::Ref(_, inner) | Type::Box(inner) => matches!(inner.base(), Type::Option(o) if Abi::is_buf(o)), _ => false, } } /// The C value of parameter `e` of type `ty`: a buffer's `input`, or a value passed for /// `&mut`, hands Rust's bytes over. fn arg(&self, ty: &Type, e: &str) -> String { let d = self.d(); match ty { _ if Abi::is_buf(ty) => format!("{d}::access::take({e})"), Type::Option(inner) if Abi::is_buf(inner) => format!("({e} ? {d}::access::take(*{e}) : {d}::none())"), Type::Ref(_, inner) | Type::Box(inner) if matches!(inner.base(), Type::Option(o) if Abi::is_buf(o)) => { self.arg(inner.base(), e) } _ => self.lower(ty, e), } } /// The C value of the C++ value `e` of type `ty`, as a parameter or a field passes it. fn lower(&self, ty: &Type, e: &str) -> String { let abi = self.abi; let d = self.d(); let ns = &self.ns; if Abi::is_buf(ty) { return format!("{d}::access::raw(::{ns}::view({e}))"); } match ty { Type::Const(_) => unreachable!("a const argument is no value"), Type::Jni(_) => unreachable!("only Kotlin exports what takes a JNI value"), Type::Array(n) => format!("{d}::lower_array<::{}>({e})", abi.array(*n)), Type::Unit => unreachable!("no value is unit"), Type::Bool | Type::Int(_) | Type::NonZero(_) | Type::F32 | Type::F64 => e.to_string(), Type::Char => format!("static_cast({e})"), Type::U128 | Type::Duration | Type::SocketAddr(_) | Type::IpAddr(_) | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => e.to_string(), Type::Waker => format!("{d}::give({d}::access::raw({e}))"), Type::List(_, inner) if ty.block().is_some() => format!("{d}::block<::{}>({e})", abi.list(inner)), Type::List(_, inner) => { let x = format!("x{}_", lists(inner)); format!( "a_.list<::{}>({e}, [&](auto &{x}) {{ return {}; }})", abi.list(inner), self.lower(inner, &x) ) } Type::Option(inner) => match inner.base() { Type::Object(_) => format!("({e} ? {} : nullptr)", self.lower(inner, &format!("*{e}"))), base @ Type::List(_, elem) => format!( "({e} ? {} : ::{}{{}})", self.lower(base, &format!("(*{e})")), abi.list(elem) ), // Through a view, so an empty buffer C++ made crosses as `Some`, not as null. _ if Abi::is_buf(inner) => format!("({e} ? {d}::access::raw(::{ns}::view(*{e})) : {d}::none())"), _ => { let c = abi.option(inner); let value = self.lower(inner, &format!("(*{e})")); format!("({e} ? ::{c}{{true, {value}}} : ::{c}{{}})") } }, Type::Ref(_, inner) if matches!(inner.base(), Type::Object(_)) => format!("{d}::access::raw({e})"), Type::Box(inner) | Type::Ref(_, inner) => self.lower(inner, e), Type::Record(_) | Type::Enum(_) if self.arena(ty) => format!("{d}::lower({e}, a_)"), Type::Record(_) => format!("{d}::lower({e})"), Type::Enum(i) => match abi.api.enums[*i].plain() { true => format!("static_cast<::{}>({e})", abi.enumeration(*i)), false => format!("{d}::lower({e})"), }, // A `Copy` value is copied out, and any other moved out. Type::Object(i) if abi.api.objects[*i].copy => format!("{d}::access::raw({e})"), Type::Object(_) => format!("{d}::access::own({e})"), Type::Callback(..) => format!("{d}::lower(::std::move({e}))"), Type::Closure(..) | Type::Future | Type::Reader => { unreachable!("{ty:?} lowers through its template parameter") } Type::Str | Type::String | Type::Slice | Type::Vec | Type::Bytes | Type::Path | Type::PathBuf => { unreachable!("a buffer is above") } Type::Tuple(elements) => { let fields: Vec = (0..elements.len()) .map(|n| self.lower(&elements[n], &format!("::std::get<{n}>({e})"))) .collect(); format!("::{}{{{}}}", abi.tuple(elements), fields.join(", ")) } } } /// The C++ value of the C value `e` of type `ty`, which it takes ownership of. `e` is /// named, so it may be read more than once. fn lift(&self, ty: &Type, e: &str) -> String { let abi = self.abi; let d = self.d(); if Abi::is_buf(ty) { return format!("{d}::access::adopt({e})"); } match ty { Type::Bool | Type::Int(_) | Type::NonZero(_) | Type::F32 | Type::F64 => e.to_string(), Type::Char => format!("static_cast({e})"), Type::U128 | Type::Duration | Type::SocketAddr(_) | Type::IpAddr(_) | Type::Range(_) | Type::Bound(_) | Type::Bounds(_) => e.to_string(), Type::List(_, inner) if ty.block().is_some() => format!( "{d}::lift_block<{}>({e}, &::{}_free)", self.owned(inner), abi.list(inner) ), Type::List(_, inner) => { let c = format!("c{}_", lists(inner)); format!( "{d}::lift_list<{}>({e}, [&](const auto &{c}) {{ return {}; }}, &::{}_free)", self.owned(inner), self.lift(inner, &c), abi.list(inner) ) } Type::Option(inner) => { let owned = self.owned(inner); match inner.base() { Type::Object(_) => { format!("({e} ? ::std::optional<{owned}>({d}::access::wrap<{owned}>({e})) : ::std::nullopt)") } Type::List(..) => format!( "({e}.ptr ? ::std::optional<{owned}>({}) : ::std::nullopt)", self.lift(inner, e) ), _ if Abi::is_buf(inner) => format!("{d}::access::adopt_option({e})"), _ => format!( "({e}.some ? ::std::optional<{owned}>({}) : ::std::nullopt)", self.lift(inner, &format!("{e}.value")) ), } } Type::Box(inner) | Type::Ref(_, inner) => self.lift(inner, e), Type::Record(_) => format!("{d}::lift({e})"), Type::Enum(i) => match abi.api.enums[*i].plain() { true => format!("static_cast<{}>({e})", self.owned(ty)), false => format!("{d}::lift({e})"), }, Type::Object(_) => format!("{d}::access::wrap<{}>({e})", self.owned(ty)), Type::Array(n) => format!("{d}::lift_array<{n}>({e})"), Type::Waker => format!("::{}::waker({d}::returned({e}))", self.ns), Type::Tuple(elements) => { let lifted: Vec = (elements.iter().enumerate()) .map(|(n, ty)| self.lift(ty, &format!("{e}._{n}"))) .collect(); format!("{}({})", self.owned(ty), lifted.join(", ")) } other => unreachable!("{other:?} is never returned"), } } /// The C++ type of a callback's parameter of type `ty`, lent for the call. fn lent(&self, ty: &Type) -> String { match ty { ty if Abi::is_buf(ty) => format!("::{}::view", self.ns), Type::Option(inner) => format!("::std::optional<{}>", self.lent(inner)), ty => self.owned(ty), } } /// The C++ value of a callback's C parameter `e` of type `ty`, lent for the call. fn lift_lent(&self, ty: &Type, e: &str) -> String { match ty { ty if Abi::is_buf(ty) => format!("::{}::view({e}.ptr, {e}.len)", self.ns), Type::Option(inner) if Abi::is_buf(inner) => format!( "({e}.ptr ? ::std::optional<::{ns}::view>(::{ns}::view({e}.ptr, {e}.len)) : ::std::nullopt)", ns = self.ns ), Type::Option(inner) => format!( "({e}.some ? ::std::optional<{}>({}) : ::std::nullopt)", self.lent(inner), self.lift_lent(inner, &format!("{e}.value")) ), ty => self.lift(ty, e), } } /// The shared header: the runtime, and every type declared, so any crate's signature /// may name any other's, as a method belonging to a later crate's instance does. fn shared(&mut self, packages: &str) -> String { let abi = self.abi; let api = abi.api; let p = abi.prefix.clone(); let ns = self.ns.clone(); let guard = format!("{}_HPP_RT", p.to_uppercase()); self.line(format!( "// Generated by rust2-ffi: the runtime of the C++ over the C ABI of the pub API of {packages},\n// and every type it declares. Do not edit.\n" )); self.line(format!("#ifndef {guard}\n#define {guard}\n")); self.line(format!("#include \"../{p}.h\"\n")); for include in [ "array", "atomic", "condition_variable", "cstddef", "cstdint", "cstdio", "cstdlib", "cstring", "functional", "initializer_list", "ios", "memory", "mutex", "optional", "string_view", "thread", "tuple", "type_traits", "utility", "variant", "vector", ] { self.line(format!("#include <{include}>")); } self.line( "#if defined(__cpp_impl_coroutine) && __cpp_impl_coroutine >= 201902L && __has_include()\n#include \n#endif\n", ); self.line(format!("namespace {ns} {{\n")); // Whether a call makes a value that is not `Send`, whose thread an executor drains. let drains = match self.abi.api.unsent() { true => format!( "inline constexpr bool drains = true;\n\ninline void c_thread_wake(c_waker wake) noexcept {{\n\t::{p}_thread_wake(wake);\n}}\n\ninline void c_thread_drain() noexcept {{\n\t::{p}_thread_drain();\n}}\n\n" ), false => "inline constexpr bool drains = false;\n\ninline void c_thread_wake(c_waker) noexcept {}\n\ninline void c_thread_drain() noexcept {}\n\n".to_string(), }; self.line(format!( "namespace detail {{\n\nusing c_buf = ::{p}_buf;\nusing c_waker = ::{p}_waker;\nusing c_foreign_future = ::{p}_foreign_future;\nusing c_foreign_reader = ::{p}_foreign_reader;\n\ninline void c_buf_free(c_buf buf) noexcept {{\n\t::{p}_buf_free(buf);\n}}\n\ninline c_buf c_buf_copy(c_buf view) noexcept {{\n\treturn ::{p}_buf_copy(view);\n}}\n\ninline c_buf c_buf_clone(c_buf buf) noexcept {{\n\treturn ::{p}_buf_clone(buf);\n}}\n\n{drains}}} // namespace detail\n" )); self.out.push_str(RUNTIME); self.line(format!( "\nnamespace detail {{\n\n// Checked at load, before any other call: a header and a library from different builds\n// must not mix.\ninline const bool contract = ::{p}_contract() == {upper}_CONTRACT ||\n\t(fail(\"{p}/rt.hpp and the library are from different builds\"), false);\n\n}} // namespace detail\n", upper = p.to_uppercase() )); let mut aliases = vec![ ("u128".to_string(), format!("{p}_u128")), ("duration".to_string(), format!("{p}_duration")), ]; for socket in [true, false] { for family in [Family::Any, Family::V4, Family::V6] { let name = crate::abi::addr(socket, family); aliases.push((name.to_string(), format!("{p}_{name}"))); } } if abi.ranges.values().any(|ty| matches!(ty, Type::Bound(_))) { aliases.push(("bound".to_string(), abi.rt("bound"))); } aliases.extend(abi.ranges.keys().map(|name| (self.name(name), name.clone()))); for (alias, c) in aliases { let alias = self.global(&alias); self.line(format!("using {alias} = ::{c};")); } self.line(""); // Every type declared, so any signature may name it; a plain enum is complete at // once, as C++ gives one with no underlying type `int`'s. for i in (0..api.enums.len()).filter(|&i| api.enums[i].plain()) { let name = self.global(&self.name(&abi.enumeration(i))); self.line(format!("enum class {name};")); } // Every class and struct, declared so any signature may name it. for (i, record) in api.records.iter().enumerate() { let name = self.global(&self.name(&abi.record(i))); // The key its definition uses, which MSVC's C4099 and Clang's // `-Wmismatched-tags` require match. match record.opaque { Some(_) => self.line(format!("class {name};")), None => self.line(format!("struct {name};")), } } for i in 0..api.objects.len() { let name = self.global(&self.name(&abi.object(i))); self.line(format!("class {name};")); } for i in 0..api.callbacks.len() { let name = self.global(&self.name(&abi.callback(i))); self.line(format!("class {name};")); } for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| !e.plain()) { let name = abi.enumeration(i); let payloads: Vec = e .variants .iter() .map(|v| self.global(&self.name(&abi::payload(&name, &v.name)))) .collect(); for payload in &payloads { self.line(format!("struct {payload};")); } let alias = self.global(&self.name(&name)); self.line(format!( "{}using {alias} = ::std::variant<{}>;", docs(&e.docs, ""), payloads.join(", ") )); } self.line(""); // Each future's type, by the operations it polls with, which its crate's header // defines. for (function, owner) in &self.functions() { let export = abi.export(function, owner.as_ref()); if let Some(abi::Future { handle, .. }) = &export.future { let name = self.global(&self.name(handle)); self.line(format!( "namespace detail {{\nstruct {name}_op;\n}}\nusing {name} = ::{ns}::future;" )); } } self.line(""); // The constants each crate's header defines, which a parameter named alike would hide. for constant in &api.constants { self.global(&self.name(&abi.name(&constant.path))); } self.line(format!("}} // namespace {ns}\n")); self.line(format!("#endif // {guard}")); std::mem::take(&mut self.out) } /// The header of `krate`: what belongs to it, after the headers of the crates it names. fn krate(&mut self, krate: &str, packages: &str) -> String { let abi = self.abi; let api = abi.api; let p = abi.prefix.clone(); let ns = self.ns.clone(); self.krate = krate.to_string(); // Named by the crate's place, not its name, which upper case could make the runtime's // `RT` or another crate's. let n = api .crates .iter() .position(|k| k == krate) .expect("each crate is listed"); let guard = format!("{}_HPP_CRATE{n}", p.to_uppercase()); self.line(format!( "// Generated by rust2-ffi: C++ over the C ABI of the pub API of the crate {krate} in\n// {packages}. Do not edit.\n" )); self.line(format!("#ifndef {guard}\n#define {guard}\n")); self.line("#include \"rt.hpp\""); for named in self.includes(krate) { self.line(format!("#include \"{}.hpp\"", self.files[&named])); } self.line(format!("\nnamespace {ns} {{\n")); let home = |h: &crate::ir::Home| h.krate == krate; for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| e.plain() && home(&e.home)) { let name = self.name(&abi.enumeration(i)); let variants: Vec = e .variants .iter() .map(|v| format!("\t{} = {},", escape(&abi::snake(&v.name)), v.discriminant)) .collect(); self.line(format!( "{}enum class {name} {{\n{}\n}};\n", docs(&e.docs, ""), variants.join("\n") )); } let constants: Vec<_> = api.constants.iter().filter(|c| home(&c.home)).collect(); for constant in &constants { let ty = match constant.value { Literal::Bool(_) => "bool", Literal::Int(int, _) => cpp_int(int), }; let name = self.name(&abi.name(&constant.path)); self.locked .insert(format!("const {}", constant.path.join("::")), name.clone()); self.line(format!( "{}inline constexpr {ty} {name} = {};", docs(&constant.docs, ""), abi.constant(&constant.path) )); } if !constants.is_empty() { self.line(""); } for i in (0..api.objects.len()).filter(|&i| home(&api.objects[i].home)) { self.object(i); } for i in (0..api.callbacks.len()).filter(|&i| home(&api.callbacks[i].home)) { self.callback(i); } // Value types, each after the values it holds. for i in (0..api.records.len()).filter(|&i| home(&api.records[i].home)) { self.value(&Type::Record(i)); } for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| home(&e.home)) { match e.plain() { true => self.enumeration(i), false => self.value(&Type::Enum(i)), } } self.conversions(); for (function, owner) in &self.functions() { if home(&function.home) { self.future(function, owner.as_ref()); } } let defs = std::mem::take(&mut self.defs); self.out.push_str(&defs); // The methods of another crate's types that belong here, as an instance naming this // crate's types does: declared in their class, defined here. for (i, object) in api.objects.iter().enumerate().filter(|(_, o)| !home(&o.home)) { let owner = Ty::Handle { name: abi.object(i), constant: false, }; let taken = vec![self.name(&abi.object(i))]; for method in object.methods.iter().filter(|m| home(&m.home)) { self.function(method, Some(&owner), Some((&taken, Owner::Member))); } } for (i, record) in api.records.iter().enumerate().filter(|(_, r)| !home(&r.home)) { let owner = Ty::Struct(abi.record(i)); let mut taken: Vec = record.fields.iter().map(|f| escape(&f.name)).collect(); taken.push(self.name(&abi.record(i))); for method in record.methods.iter().filter(|m| home(&m.home)) { self.function(method, Some(&owner), Some((&taken, Owner::Member))); } } for (i, e) in api.enums.iter().enumerate().filter(|(_, e)| !home(&e.home)) { let owner = abi.ty(&Type::Enum(i)); for method in e.methods.iter().filter(|m| home(&m.home)) { self.function(method, Some(&owner), Some((&[], Owner::Free))); } } for function in api.functions.iter().filter(|f| home(&f.home)) { self.function(function, None, None); } let defs = std::mem::take(&mut self.defs); self.out.push_str(&defs); self.line(format!("}} // namespace {ns}\n")); let hashes = std::mem::take(&mut self.hashes); self.out.push_str(&hashes); self.line(format!("#endif // {guard}")); std::mem::take(&mut self.out) } /// The other crates whose types what belongs to `krate` names, each before it in /// dependency order, as [`crate::ir::Home`] places an instance. fn includes(&mut self, krate: &str) -> BTreeSet { let api = self.abi.api; let mut tys: Vec<&Type> = Vec::new(); let mut owners: Vec = Vec::new(); for (i, r) in api.records.iter().enumerate() { if r.home.krate == krate { tys.extend(r.fields.iter().map(|f| &f.ty)); } if r.methods.iter().any(|m| m.home.krate == krate) { owners.push(Type::Record(i)); } } for (i, e) in api.enums.iter().enumerate() { if e.home.krate == krate { tys.extend(e.variants.iter().flat_map(|v| &v.fields).map(|f| &f.ty)); } if e.methods.iter().any(|m| m.home.krate == krate) { owners.push(Type::Enum(i)); } } for (i, o) in api.objects.iter().enumerate() { if o.methods.iter().any(|m| m.home.krate == krate) { owners.push(Type::Object(i)); } } let methods = (api.records.iter().flat_map(|r| &r.methods)) .chain(api.enums.iter().flat_map(|e| &e.methods)) .chain(api.objects.iter().flat_map(|o| &o.methods)) .chain(&api.functions) .filter(|f| f.home.krate == krate); let callbacks = (api.callbacks.iter()) .filter(|c| c.home.krate == krate) .flat_map(|c| &c.methods); for function in methods.chain(callbacks) { tys.extend(function.params.iter().map(|p| &p.ty)); tys.push(&function.ok); tys.extend(&function.err); } let rank = |k: &str| api.crates.iter().position(|c| c == k); let mut named = BTreeSet::new(); for ty in tys.into_iter().chain(&owners) { crate::ir::each(ty, &mut |ty| { let home = match ty { Type::Record(i) => &api.records[*i].home, Type::Enum(i) => &api.enums[*i].home, Type::Object(i) => &api.objects[*i].home, Type::Callback(i, _) => &api.callbacks[*i].home, _ => return, }; if home.krate != krate { named.insert(home.krate.clone()); } }); } for later in named.iter().filter(|k| rank(k) > rank(krate)) { self.errors.push(format!( "the crate {krate} names the types of {later}, a crate after it, which rust2-ffi should place with them" )); } named } /// Every exported function, with the C type of its owner if a method. fn functions(&self) -> Vec<(&'a Function, Option)> { let abi = self.abi; let api = abi.api; let mut functions = Vec::new(); for (i, record) in api.records.iter().enumerate() { let owner = Ty::Struct(abi.record(i)); functions.extend(record.methods.iter().map(|m| (m, Some(owner.clone())))); } for (i, e) in api.enums.iter().enumerate() { let owner = abi.ty(&Type::Enum(i)); functions.extend(e.methods.iter().map(|m| (m, Some(owner.clone())))); } for (i, object) in api.objects.iter().enumerate() { let owner = Ty::Handle { name: abi.object(i), constant: false, }; functions.extend(object.methods.iter().map(|m| (m, Some(owner.clone())))); } functions.extend(api.functions.iter().map(|f| (f, None))); functions } /// The member name of the C function `c` of the type named `owner` in C, kept apart from /// the class's name and its fields. fn member(&self, c: &str, owner: &str, taken: &[String]) -> String { let bare = match c.strip_prefix(owner).and_then(|rest| rest.strip_prefix('_')) { Some(rest) => escape(rest), None => self.name(c), }; match taken.contains(&bare) { true => format!("{bare}_"), false => bare, } } /// Check that no two members of `class`, the Rust type `rust`, share a name. fn distinct(&mut self, class: &str, rust: &str, members: &[String]) { let mut seen = BTreeSet::new(); for member in members { if !seen.insert(member) { self.errors.push(format!( "two members of `{rust}` are both `{}::{class}::{member}` in C++, which rust2-ffi should keep apart", self.ns )); } } } fn object(&mut self, i: usize) { let abi = self.abi; let object = &abi.api.objects[i]; let c = abi.object(i); let name = self.name(&c); let t = object.traits; let text = format!("{}\n\n{}", abi.api.rust(&object.path, &object.args), object.docs); let d = self.d(); // A failed check of a trait's borrow aborts with its message, as C++ throws nothing. let status = match abi.traits_status(i) { true => ", nullptr", false => "", }; // Copies share a handle only where no call tells that apart from a clone, but by an // `Arc`'s or `Rc`'s count, which counts one for every copy. let handle = match (object.shared, status.is_empty()) { (true, true) => format!("{d}::shared<::{c}, &::{c}_free, &::{c}_clone, &::{c}_borrowed>"), (true, false) => { self.line(format!( "namespace detail {{\n\ninline ::{c} *{c}_clone(const ::{c} *raw) noexcept {{\n\treturn ::{c}_clone(raw, nullptr);\n}}\n\n}} // namespace detail\n" )); format!("{d}::shared<::{c}, &::{c}_free, &{d}::{c}_clone, &::{c}_borrowed>") } (false, _) => format!("{d}::unique<::{c}, &::{c}_free>"), }; let mut body = vec![ format!("\t{handle} raw_;\n"), format!("\texplicit {name}(decltype(raw_) raw) noexcept : raw_(::std::move(raw)) {{}}\n"), format!("\tfriend struct {d}::access;\n"), "public:".to_string(), // A move leaves the source consumed, which Clang's `-Wconsumed` then refuses to call. format!("\tRUST2_FFI_UNCONSUMED {name}({name} &&other RUST2_FFI_MOVED_FROM) noexcept = default;"), format!("\t{name} &operator=({name} &&other) noexcept = default;"), ]; if object.shared { body.push(format!("\tRUST2_FFI_UNCONSUMED {name}(const {name} &other) = default;")); body.push(format!("\t{name} &operator=(const {name} &other) = default;")); } let mut members = Vec::new(); if t.clone && !object.shared { let clone = apart("clone", &name); body.push(format!( "\t/// Rust's `Clone`, a value of its own: copies sharing one value could be told apart\n\t/// from clones, so it does not copy.\n\tRUST2_FFI_CALLABLE {name} {clone}() const;" )); self.def(format!( "inline {name} {name}::{clone}() const {{\n\treturn {d}::access::wrap<{name}>(::{c}_clone(raw_.get(){status}));\n}}\n" )); members.push(clone); } if t.eq { let (a, b) = self.operands(); body.push(format!( "\tfriend bool operator==(const {name} &{a}, const {name} &{b}) {{\n\t\treturn ::{c}_eq({a}.raw_.get(), {b}.raw_.get(){status});\n\t}}\n\tfriend bool operator!=(const {name} &{a}, const {name} &{b}) {{\n\t\treturn !({a} == {b});\n\t}}" )); } if t.hash { let hash = apart("hash", &name); body.push(format!( "\t/// Rust's `Hash`, agreeing with `==`, as `std::hash` hashes it.\n\tRUST2_FFI_CALLABLE ::std::uint64_t {hash}() const;" )); self.def(format!( "inline ::std::uint64_t {name}::{hash}() const {{\n\treturn ::{c}_hash(raw_.get(){status});\n}}\n" )); members.push(hash.clone()); let q = format!("::{}::{name}", self.ns); self.hashes.push_str(&format!( "namespace std {{\ntemplate <>\nstruct hash<{q}> {{\n\tsize_t operator()(const {q} &value) const noexcept {{\n\t\treturn static_cast(value.{hash}());\n\t}}\n}};\n}} // namespace std\n\n" )); } self.traits(&name, &c, t, Ok(status), &mut body, &mut members); let owner = Ty::Handle { name: c.clone(), constant: false, }; let taken = vec![name.clone()]; for method in &object.methods { let (decl, member) = self.function(method, Some(&owner), Some((&taken, Owner::Member))); body.push(decl); members.push(member); } self.distinct(&name, &abi.api.rust(&object.path, &object.args), &members); self.line(format!( "{}class RUST2_FFI_CONSUMABLE {name} {{\n{}\n}};\n", docs(text.trim(), ""), body.join("\n") )); } /// The members a type's std traits export beyond its operators: an object's, which /// holds a handle and passes each call `Ok` of its status argument, or a record's, of /// type `Err`, which is lowered. fn traits( &mut self, name: &str, c: &str, t: Traits, of: Result<&str, &Type>, body: &mut Vec, members: &mut Vec, ) { let ns = self.ns.clone(); let d = self.d(); let (value, status) = match of { Ok(status) => (None, status), Err(ty) => (Some(ty), self.value_status(ty)), }; let object = value.is_none(); let callable = match object { true => "RUST2_FFI_CALLABLE ", false => "", }; let (this, lower) = match value { None => ("raw_.get()", String::new()), Some(ty) => ( "&c_self_", format!("{}\tauto c_self_ = {};\n", self.scope([ty]), self.lower(ty, "*this")), ), }; if t.display { let member = apart("to_string", name); body.push(format!("\t{callable}::{ns}::buf {member}() const;")); self.def(format!( "inline ::{ns}::buf {name}::{member}() const {{\n{lower}\treturn {d}::access::adopt(::{c}_to_string({this}{status}));\n}}\n" )); members.push(member); } if t.debug { let member = apart("debug", name); body.push(format!("\t{callable}::{ns}::buf {member}() const;")); self.def(format!( "inline ::{ns}::buf {name}::{member}() const {{\n{lower}\treturn {d}::access::adopt(::{c}_debug({this}{status}));\n}}\n" )); members.push(member); } if t.default { let member = apart("default_", name); body.push(format!("\tstatic {name} {member}();")); members.push(member.clone()); let make = match object { true => format!("{d}::access::wrap<{name}>(c_ret_)"), false => format!("{d}::lift(c_ret_)"), }; self.def(format!( "inline {name} {name}::{member}() {{\n\tauto c_ret_ = ::{c}_default();\n\treturn {make};\n}}\n" )); } } fn callback(&mut self, i: usize) { let abi = self.abi; let callback = &abi.api.callbacks[i]; let c = abi.callback(i); let name = self.name(&c); let text = format!( "{}: implemented in C++. Rust deletes it once it drops the implementation, and may\ncall its methods from any thread.\n\n{}", callback.path.join("::"), callback.docs ); let mut body = vec!["public:".to_string(), format!("\tvirtual ~{name}() = default;")]; let mut members = Vec::new(); let mut trampolines = vec![format!( "\t\tstatic void free(void *data) noexcept {{\n\t\t\tdelete static_cast<::{}::{name} *>(data);\n\t\t}}", self.ns )]; let mut table = vec!["&t::free".to_string()]; for (n, method) in callback.methods.iter().enumerate() { let mut member = escape(method.name()); if member == name { member.push('_'); } crate::lock::function(&mut self.locked, method, &member); members.push(member.clone()); let constant = match method.receiver { Some(Receiver::Mut) => "", _ => " const", }; let params: Vec = method .params .iter() .map(|p| declare(&self.lent(&p.ty), &escape(&p.name))) .collect(); body.push(format!( "{}\tvirtual {} {member}({}){constant} = 0;", docs(&method.docs, "\t"), self.owned(&method.ok), params.join(", ") )); let c_params: Vec = std::iter::once("void *data".to_string()) .chain( method .params .iter() .enumerate() .map(|(k, p)| decl(abi, &abi.ty(&p.ty), &format!("p{k}"))), ) .collect(); let args: Vec = method .params .iter() .enumerate() .map(|(k, p)| self.lift_lent(&p.ty, &format!("p{k}"))) .collect(); let call = format!( "static_cast<::{}::{name}{constant} *>(data)->{member}({})", self.ns, args.join(", ") ); let ret = match &method.ok { Type::Unit => format!("{call};"), ok => format!("return {};", self.lower(ok, &call)), }; trampolines.push(format!( "\t\tstatic {} m{n}({}) noexcept {{\n\t\t\t{ret}\n\t\t}}", decl(abi, &abi.ty(&method.ok), ""), c_params.join(", ") )); table.push(format!("&t::m{n}")); } self.distinct(&name, &callback.path.join("::"), &members); self.line(format!( "{}class {name} {{\n{}\n}};\n", docs(text.trim(), ""), body.join("\n") )); self.def(format!( "namespace detail {{\n\ninline ::{c} lower(::std::unique_ptr<::{ns}::{name}> impl) {{\n\tif (!impl) {{\n\t\tfail(\"{c}: a null implementation\");\n\t}}\n\tstruct t {{\n{}\n\t}};\n\tstatic const ::{c}_vtable vtable = {{{}}};\n\treturn ::{c}{{&vtable, impl.release()}};\n}}\n\n}} // namespace detail\n", trampolines.join("\n"), table.join(", "), ns = self.ns, )); } /// A record's struct or a data enum's payloads, after the values they hold. fn value(&mut self, ty: &Type) { let abi = self.abi; let c = match ty { Type::Record(i) => abi.record(*i), Type::Enum(i) if !abi.api.enums[*i].plain() => abi.enumeration(*i), Type::Option(inner) | Type::Box(inner) | Type::Ref(_, inner) | Type::List(_, inner) => { return self.value(inner); } Type::Tuple(elements) => { for element in elements { self.value(element); } return; } _ => return, }; // Another crate's, which its header defines. let home = match ty { Type::Record(i) => &abi.api.records[*i].home, Type::Enum(i) => &abi.api.enums[*i].home, _ => unreachable!(), }; if home.krate != self.krate || !self.defined.insert(c.clone()) { return; } match ty { Type::Record(i) => { let record = &abi.api.records[*i]; for field in &record.fields { self.value(&field.ty); } let name = self.name(&c); let fields: Vec = record.fields.iter().map(|f| escape(&f.name)).collect(); let mut body: Vec = record .fields .iter() .zip(&fields) .map(|(f, field)| format!("{}\t{} {field}{};", docs(&f.docs, "\t"), self.owned(&f.ty), init(&f.ty))) .collect(); body.push(String::new()); let mut members = fields.clone(); let t = record.traits; if t.eq { // Friends, whose arguments, unlike a member's, shadow no field of any name. let (a, b) = self.operands(); body.push(format!( "\tfriend bool operator==(const {name} &{a}, const {name} &{b});\n\tfriend bool operator!=(const {name} &{a}, const {name} &{b}) {{\n\t\treturn !({a} == {b});\n\t}}" )); self.def(format!( "inline bool operator==(const {name} &{a}, const {name} &{b}) {{\n{}\tauto c_a_ = {};\n\tauto c_b_ = {};\n\treturn ::{c}_eq(&c_a_, &c_b_{});\n}}\n", self.scope([ty]), self.lower(ty, &a), self.lower(ty, &b), self.value_status(ty), )); } self.traits(&name, &c, t, Err(ty), &mut body, &mut members); let owner = Ty::Struct(c.clone()); let mut taken = fields.clone(); taken.push(name.clone()); // An opaque value's bytes are its private member `c_`. if record.opaque.is_some() { taken.push("c_".to_string()); members.push("c_".to_string()); } for method in &record.methods { let (decl, member) = self.function(method, Some(&owner), Some((&taken, Owner::Member))); body.push(decl); members.push(member); } self.distinct(&name, &abi.api.rust(&record.path, &record.args), &members); while body.last().is_some_and(String::is_empty) { body.pop(); } match record.opaque { // Its bytes, which only Rust makes or reads: C++ copies them, but makes // none, as it has no public constructor. Some(_) => { let text = format!( "{}\n\nIts bytes, which only Rust makes or reads: copy it, but never make one.", record.docs ); self.line(format!( "{}class {name} {{\npublic:\n{}\n\nprivate:\n\tfriend struct {d}::access;\n\n\texplicit {name}(const ::{c} &c) noexcept : c_(c) {{}}\n\n\t::{c} c_;\n}};\n", docs(text.trim(), ""), body.join("\n"), d = self.d() )); } None => self.line(format!( "{}struct {name} {{\n{}\n}};\n", docs(&record.docs, ""), body.join("\n") )), } } Type::Enum(i) => { let e = &abi.api.enums[*i]; for variant in &e.variants { for field in &variant.fields { self.value(&field.ty); } } for variant in &e.variants { let payload = self.name(&abi::payload(&c, &variant.name)); let fields: Vec = variant .fields .iter() .map(|f| format!("\t{} {}{};", self.owned(&f.ty), escape(&f.name), init(&f.ty))) .collect(); self.line(format!("struct {payload} {{\n{}\n}};\n", fields.join("\n")).replace("{\n\n}", "{}")); } self.enumeration(*i); } _ => unreachable!(), } } /// An enum's methods and std traits, as free functions taking it first: C++ enums /// hold no members. fn enumeration(&mut self, i: usize) { let abi = self.abi; let e = &abi.api.enums[i]; let c = abi.enumeration(i); let name = self.name(&c); let ns = self.ns.clone(); let ty = Type::Enum(i); let param = self.param(&ty); let lifted = self.lift(&ty, "c_ret_"); let (a, b) = self.operands(); let lower = |e: &str| self.lower(&ty, e); let (lower_a, lower_b, this) = (lower(&a), lower(&b), lower("self")); let scope = self.scope([&ty]); let t = e.traits; let status = self.value_status(&ty); if t.eq { let (a_, b_) = (declare(¶m, &a), declare(¶m, &b)); self.def(format!( "inline bool operator==({a_}, {b_}) {{\n{scope}\tauto c_a_ = {lower_a};\n\tauto c_b_ = {lower_b};\n\treturn ::{c}_eq(&c_a_, &c_b_{status});\n}}\n\ninline bool operator!=({a_}, {b_}) {{\n\treturn !({a} == {b});\n}}\n" )); } for (on, trait_name) in [(t.display, "to_string"), (t.debug, "debug")] { if on { self.def(format!( "inline ::{ns}::buf {name}_{trait_name}({}) {{\n{scope}\tauto c_self_ = {this};\n\treturn {d}::access::adopt(::{c}_{trait_name}(&c_self_{status}));\n}}\n", declare(¶m, "self"), d = self.d() )); } } if t.default { self.def(format!( "inline {name} {name}_default() {{\n\tauto c_ret_ = ::{c}_default();\n\treturn {lifted};\n}}\n" )); } let owner = abi.ty(&ty); for method in &e.methods { self.function(method, Some(&owner), Some((&[], Owner::Free))); } } /// Each record's and data enum's conversions to and from C. fn conversions(&mut self) { let abi = self.abi; let api = abi.api; let ns = self.ns.clone(); let home = |h: &crate::ir::Home| h.krate == self.krate; let records: Vec = (0..api.records.len()).filter(|&i| home(&api.records[i].home)).collect(); let enums: Vec = (0..api.enums.len()) .filter(|&i| !api.enums[i].plain() && home(&api.enums[i].home)) .collect(); let callbacks: Vec = (0..api.callbacks.len()) .filter(|&i| home(&api.callbacks[i].home)) .collect(); if records.is_empty() && enums.is_empty() && callbacks.is_empty() { return; } self.line("namespace detail {\n"); for &i in &records { let c = abi.record(i); let name = self.name(&c); let arena = self.arena_param(&Type::Record(i)); self.line(format!("inline ::{c} lower(const ::{ns}::{name} &v{arena});")); self.line(format!("inline ::{ns}::{name} lift(const ::{c} &c);")); } for &i in &enums { let c = abi.enumeration(i); let name = self.name(&c); let arena = self.arena_param(&Type::Enum(i)); self.line(format!("inline ::{c} lower(const ::{ns}::{name} &v{arena});")); self.line(format!("inline ::{ns}::{name} lift(const ::{c} &c);")); } for &i in &callbacks { let c = abi.callback(i); let name = self.name(&c); self.line(format!("inline ::{c} lower(::std::unique_ptr<::{ns}::{name}> impl);")); } self.line(""); for &i in &records { let record = &api.records[i]; let c = abi.record(i); let name = self.name(&c); if record.opaque.is_some() { let d = self.d(); self.line(format!( "inline ::{c} lower(const ::{ns}::{name} &v) {{\n\treturn {d}::access::bits(v);\n}}\n" )); self.line(format!( "inline ::{ns}::{name} lift(const ::{c} &c) {{\n\treturn {d}::access::make<::{ns}::{name}>(c);\n}}\n" )); continue; } let lowered: Vec = record .fields .iter() .map(|f| self.lower(&f.ty, &format!("v.{}", escape(&f.name)))) .collect(); let lifted: Vec = record .fields .iter() .map(|f| self.lift(&f.ty, &format!("c.{}", abi::escape(&f.name)))) .collect(); let (v, cc) = match record.fields.is_empty() { true => ("", ""), false => (" &v", " &c"), }; let arena = self.arena_param(&Type::Record(i)); self.line(format!( "inline ::{c} lower(const ::{ns}::{name}{v}{arena}) {{\n\treturn ::{c}{{{}}};\n}}\n", lowered.join(", ") )); self.line(format!( "inline ::{ns}::{name} lift(const ::{c}{cc}) {{\n\treturn ::{ns}::{name}{{{}}};\n}}\n", lifted.join(", ") )); } for &i in &enums { let e = &api.enums[i]; let c = abi.enumeration(i); let name = self.name(&c); let upper = c.to_uppercase(); let mut lower = Vec::new(); let mut lift = Vec::new(); for (n, variant) in e.variants.iter().enumerate() { let tag = format!("{upper}_{}", abi::snake(&variant.name).to_uppercase()); let payload = self.name(&abi::payload(&c, &variant.name)); let member = abi::escape(&abi::snake(&variant.name)); let mut set = vec![format!("c.tag = {tag};")]; let mut fields = Vec::new(); for field in &variant.fields { set.push(format!( "c.{member}.{} = {};", abi::escape(&field.name), self.lower(&field.ty, &format!("p.{}", escape(&field.name))) )); fields.push(self.lift(&field.ty, &format!("c.{member}.{}", abi::escape(&field.name)))); } let bind = match variant.fields.is_empty() { true => String::new(), false => format!("const auto &p = *::std::get_if<{n}>(&v);\n\t\t"), }; lower.push(format!( "\tcase {n}: {{\n\t\t{bind}{}\n\t\tbreak;\n\t}}", set.join("\n\t\t") )); lift.push(format!( "\tcase {tag}:\n\t\treturn ::{ns}::{name}(::std::in_place_index<{n}>, ::{ns}::{payload}{{{}}});", fields.join(", ") )); } let arena = self.arena_param(&Type::Enum(i)); self.line(format!( "inline ::{c} lower(const ::{ns}::{name} &v{arena}) {{\n\t::{c} c{{}};\n\tswitch (v.index()) {{\n{}\n\t}}\n\treturn c;\n}}\n", lower.join("\n") )); self.line(format!( "inline ::{ns}::{name} lift(const ::{c} &c) {{\n\tswitch (c.tag) {{\n{}\n\t}}\n\tfail(\"{c}: an invalid tag\");\n}}\n", lift.join("\n") )); } self.line("} // namespace detail\n"); } /// The return type a C++ function or future gives for `function`'s result. fn output(&self, function: &Function) -> String { let ok = self.owned(&function.ok); match &function.err { Some(err) => format!("::{}::result<{ok}, {}>", self.ns, self.owned(err)), None => ok, } } /// Declarations of the out values a C call writes through `outs`, and the C++ value they /// make, ok then error, for a result `output`. fn outs(&self, function: &Function, outs: &[(String, Ty)], output: &str) -> (Vec, String, Option) { let abi = self.abi; let declared: Vec = outs .iter() .map(|(name, ty)| { let Ty::Out(inner) = ty else { unreachable!("an out parameter is a pointer") }; format!("{}{{}};", decl(abi, inner, &format!("c_{name}_"))) }) .collect(); let owned = strip_refs; let ok = match &function.ok { Type::Unit => String::new(), Type::Tuple(elements) => { let lifted: Vec = elements .iter() .enumerate() .map(|(n, e)| self.lift(&owned(e), &format!("c_out{n}_"))) .collect(); format!("{}({})", self.owned(&function.ok), lifted.join(", ")) } ok => self.lift(&owned(ok), "c_out_"), }; let ok = match function.err.is_some() { true => format!("{output}::ok({ok})"), false => ok, }; let err = function .err .as_ref() .map(|err| format!("{output}::err({})", self.lift(&owned(err), "c_err_"))); (declared, ok, err) } /// `function`'s declaration in its class, and its member name, with its definition /// among the definitions; or as a free function if it has no class. fn function( &mut self, function: &Function, owner: Option<&Ty>, class: Option<(&[String], Owner)>, ) -> (String, String) { let abi = self.abi; let export = abi.export(function, owner); let d = self.d(); let owner_c = match owner { Some(Ty::Struct(n) | Ty::Enum(n) | Ty::Handle { name: n, .. }) => Some(n.clone()), _ => None, }; let member = match (class, &owner_c) { (Some((taken, Owner::Member)), Some(owner)) => self.member(&export.call.name, owner, taken), _ => self.name(&export.call.name), }; crate::lock::function(&mut self.locked, function, &member); let free = !matches!(class, Some((_, Owner::Member))); let ret = match &export.future { Some(future) => self.q(&future.handle), None => self.output(function), }; let mut params: Vec = Vec::new(); let mut args: Vec = Vec::new(); let mut prelude = Vec::new(); // What the call lowers, which may need an arena. let mut lowered: Vec = function.params.iter().map(|p| p.ty.clone()).collect(); let receiver = function.receiver.filter(|_| owner.is_some()); let mut c_params = export.call.params.iter(); if receiver.is_some() { let (_, ty) = c_params.next().expect("a method has its receiver"); match (ty, free) { // Moved out of, as a handle taken by value is. (Ty::Handle { name, .. }, _) if receiver == Some(Receiver::Owned) && !copy(abi, name) => { args.push("raw_.own()".to_string()) } (Ty::Handle { .. }, _) => args.push("raw_.get()".to_string()), (_, false) => { let ty = record(abi, owner_c.as_deref().expect("a member method has its record")); prelude.push(format!("auto c_self_ = {};", self.lower(&ty, "*this"))); args.push("&c_self_".to_string()); lowered.push(ty); } (_, true) => { let ty = enumeration(abi, owner_c.as_deref().expect("a free method has its enum")); params.push(declare(&self.param(&ty), "self")); prelude.push(format!("auto c_self_ = {};", self.lower(&ty, "self"))); args.push("&c_self_".to_string()); lowered.push(ty); } } } if lowered.iter().any(|ty| self.arena(ty)) { prelude.insert(0, format!("{d}::arena a_;")); } let mut templates = Vec::new(); // A parameter named as a member or anything in the namespace would hide it. let members = match class { Some((taken, Owner::Member)) => taken, _ => &[], }; let mut names: Vec = Vec::new(); // Whether an argument takes Rust's bytes from its parameter, and the arguments that // may throw, by allocating. let mut taken = false; let mut throwing = Vec::new(); // The allocations among them that Rust takes (a kept closure, a future), each by its // argument, its type, its `new`, and what passes the pointer, which a hoisted one holds // in a `unique_ptr` until the call, so a later throw frees it. let mut owned: Vec<(usize, String, String, Option)> = Vec::new(); for param in &function.params { let (_, c_ty) = c_params.next().expect("each parameter has its C one"); let name = parameter(¶m.name, |name| { self.globals.contains(name) || members.iter().chain(&names).any(|n| n == name) }); names.push(name.clone()); // Any future of nothing, such as a binding's `future` of `void`, moved in. if let Type::Future = param.ty { let f = format!("F{}", templates.len()); params.push(format!("{f} {name}")); let new = format!("new {f}(::std::move({name}))"); let wrap = format!("{d}::foreign_future"); throwing.push(args.len()); args.push(format!("{wrap}({new})")); owned.push((args.len() - 1, f.clone(), new, Some(wrap))); templates.push(format!("class {f}")); continue; } // Any reader, lent for the call. if let Type::Ref(_, inner) = ¶m.ty && **inner == Type::Reader { let f = format!("F{}", templates.len()); params.push(format!("{f} &{name}")); args.push(format!("{d}::foreign_reader({name})")); templates.push(format!("class {f}")); continue; } if let (Type::Closure(closure_), Ty::Fn(c_lent, c_ret)) = (¶m.ty, c_ty) { c_params.next().expect("a closure has its data"); let f = format!("F{}", templates.len()); params.push(format!("{f} &&{name}")); // Named by its type, not its parameter, so no renamed parameter takes the name. let trampoline = format!("c_{}_", f.to_lowercase()); prelude.push(self.closure(&f, &trampoline, closure_, (c_lent, c_ret))); args.push(trampoline); match closure_.kept { // Moved or copied into a callable Rust owns, which it destroys through `free`. true => { c_params.next().expect("a kept closure has its free"); let ty = format!("::std::decay_t<{f}>"); let new = format!("new {ty}(::std::forward<{f}>({name}))"); throwing.push(args.len()); owned.push((args.len(), ty, new.clone(), None)); args.push(new); args.push(format!( "[](void *data_) noexcept {{ delete static_cast<::std::decay_t<{f}> *>(data_); }}" )); } false => args.push(format!( "const_cast(static_cast(::std::addressof({name})))" )), } templates.push(format!("class {f}")); continue; } params.push(declare(&self.param(¶m.ty), &name)); if Self::takes(¶m.ty) { taken = true; } else if self.arena(¶m.ty) { throwing.push(args.len()); } args.push(self.arg(¶m.ty, &name)); } // Arguments evaluate in no set order, so those that may throw run first, and the call // itself throws nothing: Rust's bytes are taken, and an allocation released to Rust, // only once nothing left before the call can throw and leak them. if taken || throwing.len() > 1 { for &i in &throwing { match owned.iter().find(|(k, ..)| *k == i) { Some((_, ty, new, wrap)) => { prelude.push(format!("::std::unique_ptr<{ty}> c_arg{i}_({new});")); args[i] = match wrap { Some(wrap) => format!("{wrap}(c_arg{i}_.release())"), None => format!("c_arg{i}_.release()"), }; } None => { prelude.push(format!("auto c_arg{i}_ = {};", args[i])); args[i] = format!("c_arg{i}_"); } } } } let outs: Vec<(String, Ty)> = c_params.filter(|(_, ty)| !abi::is_status(ty)).cloned().collect(); // Each value passed for `&mut` takes what Rust wrote back, on every path, as does a // value's own `&mut self`, which Rust wrote back in place. let mut writes: Vec = match export.call.params.first() { Some((_, Ty::InOut(_))) => { let ty = record(abi, owner_c.as_deref().expect("a member method has its record")); vec![format!("*this = {};", self.lift(&ty, "c_self_"))] } _ => Vec::new(), }; writes.extend( (function.params.iter().zip(&names)) .filter(|(param, _)| param.ty.written()) .map(|(param, name)| { let out = Abi::written(function, &abi::escape(¶m.name)); format!("{name} = {};", self.lift(param.ty.base(), &format!("c_{out}_"))) }), ); for (name, _) in &outs { args.push(format!("&c_{name}_")); } // A failed check aborts with its message, as C++ throws nothing. if export.call.status().is_some() { args.push("nullptr".to_string()); } let call = format!("::{}({})", export.call.name, args.join(", ")); let mut body = prelude; if let Some(abi::Future { handle, .. }) = &export.future { body.push(format!("return {d}::access::wrap<{}>({call});", self.q(handle))); } else { let (declared, ok, err) = self.outs(function, &outs, &ret); body.extend(declared); match (&function.err, &function.ok) { (Some(_), _) if !writes.is_empty() => { body.push(format!("bool c_ok_ = {call};")); body.extend(writes); body.push(format!("if (c_ok_) {{\n\t\treturn {ok};\n\t}}")); body.push(format!("return {};", err.expect("an error lifts"))); } (Some(_), _) => { body.push(format!("if ({call}) {{\n\t\treturn {ok};\n\t}}")); body.push(format!("return {};", err.expect("an error lifts"))); } (None, Type::Tuple(_)) => { body.push(format!("{call};")); body.extend(writes); body.push(format!("return {ok};")); } (None, Type::Unit) => { body.push(format!("{call};")); body.extend(writes); } (None, ok_ty) => { body.push(format!("auto c_out_ = {call};")); body.extend(writes); let lifted = self.lift(&strip_refs(ok_ty), "c_out_"); body.push(format!("return {lifted};")); } } } let qualifier = match (receiver, free) { (_, true) | (None, _) => String::new(), (Some(Receiver::Ref), _) => " const".to_string(), (Some(Receiver::Mut), _) => String::new(), (Some(Receiver::Owned), _) => match owner { Some(Ty::Handle { name, .. }) if !copy(abi, name) => " &&".to_string(), _ => " const".to_string(), }, }; let is_static = receiver.is_none() && !free; let class_name = owner_c.as_deref().map(|c| self.name(c)); let scope = match (&class_name, free) { (Some(class), false) => format!("{class}::"), _ => String::new(), }; let template = match templates.is_empty() { true => String::new(), false => format!("template <{}>\n", templates.join(", ")), }; // Defined in the header of the crate it belongs to, which may follow its class's. if function.home.krate == self.krate { self.def(format!( "{template}inline {ret} {scope}{member}({}){qualifier} {{\n\t{}\n}}\n", params.join(", "), body.join("\n\t") )); } let mut text = function.docs.clone(); for (param, name) in function.params.iter().zip(&names) { if let Type::Future = param.ty { text.push_str(&format!( "\n\nRust polls `{name}` from any thread until it is ready, and destroys it once done with it." )); } if let Type::Ref(_, inner) = ¶m.ty && **inner == Type::Reader { text.push_str(&format!( "\n\nRust reads `{name}` only during the call, from any thread, one call at a time, through `read(uint8_t *, size_t)`, returning a `result` of how many bytes it read, at most the size it was given and none only at its end, and `seek(int64_t, std::ios_base::seekdir)`, returning one of the position from the start, or, from the start past `INT64_MAX`, `seek_start(uint64_t)`, which a reader without it fails. A failure's error is anything a `view` takes, which Rust raises as an `io::Error` of that message." )); } if let Type::Closure(closure_) = ¶m.ty { let lent = &closure_.params; text.push_str(&match closure_.kept { true => format!( "\n\nRust keeps `{name}`, moved or copied, calls it from any thread, one call at a time, and destroys it once done with it, which may be before any call." ), false => format!("\n\nRust calls `{name}` only during the call, from any thread."), }); if closure_.err.is_some() { text.push_str(&format!( "\n`{name}` returns a `result`, or any type with its `operator bool`, `operator*`, and `error()`, such as `std::expected`, whose error is anything a `view` takes." )); } if lent.iter().any(|p| matches!(p.base(), Type::Object(_))) { text.push_str(&format!( "\nAn object it lends lives only for that call of `{name}`: move none out of it." )); } } } // An object's method is callable only before a move empties it, and one taking // `self` empties it. let prefix = match (is_static, free, owner) { (true, _, _) => "static ", (false, false, Some(Ty::Handle { .. })) if qualifier == " &&" => "RUST2_FFI_CONSUMES ", (false, false, Some(Ty::Handle { .. })) => "RUST2_FFI_CALLABLE ", _ => "", }; let declaration = format!( "{}\t{}{prefix}{ret} {member}({}){qualifier};", docs(text.trim(), "\t"), template.replace('\n', "\n\t"), params.join(", ") ); (declaration, member) } /// The trampoline C calls for a closure parameter of type `f`, as the local `local`, /// which C declares as taking `c_lent` and returning `c_ret`: it lends each object as /// its class, and gives Rust what the closure returns, an error through its out. fn closure(&self, f: &str, local: &str, closure: &Closure, (c_lent, c_ret): (&[Ty], &Ty)) -> String { let abi = self.abi; let d = self.d(); let c_params: Vec = std::iter::once("void *data_".to_string()) .chain( c_lent .iter() .enumerate() .map(|(k, ty)| decl(abi, ty, &format!("p{k}_"))), ) .collect(); // A kept closure is Rust's own copy, and one lent for the call the caller's. let data = match closure.kept { true => format!("::std::decay_t<{f}>"), false => format!("::std::remove_reference_t<{f}>"), }; let mut body = vec![format!("auto &f_ = *static_cast<{data} *>(data_);")]; let mut args = Vec::new(); for (k, (ty, c_ty)) in closure.params.iter().zip(c_lent).enumerate() { let p = format!("p{k}_"); match (ty, c_ty) { (Type::Ref(..) | Type::Object(_), Ty::Handle { name: c, constant }) => { let object = match ty { Type::Ref(_, object) => object, _ => ty, }; let constant = match constant { true => "const ", false => "", }; body.push(format!( "{d}::lent<{}, {constant}::{c}> l{k}_({p});", self.owned(object) )); args.push(match ty { Type::Ref(crate::ir::Mutability::Mut, _) => { format!("::{}::borrow<{}>(l{k}_.get())", self.ns, self.owned(object)) } // A `Copy` object Rust copied for the call, which its class reads in place. _ => format!("::std::as_const(l{k}_.get())"), }); } _ => args.push(self.lift_lent(ty, &p)), } } let call = format!("f_({})", args.join(", ")); match (&closure.err, &closure.ok) { (None, Type::Unit) => body.push(format!("{call};")), (None, ok) => { body.push(format!("auto r_ = {call};")); body.push(format!("return {};", self.returned(ok, "r_"))); } (Some(_), ok) => { let err = format!("p{}_", c_lent.len() - 1); body.push(format!("auto r_ = {call};")); body.push(format!( "if (!r_) {{\n\t\t\t*{err} = {d}::copy_bytes(r_.error());\n\t\t\treturn false;\n\t\t}}" )); if *ok != Type::Unit { body.push(format!("*p{}_ = {};", closure.params.len(), self.returned(ok, "(*r_)"))); } body.push("return true;".to_string()); } } format!( "auto {local} = []({}) noexcept -> {} {{\n\t\t{}\n\t}};", c_params.join(", "), decl(abi, c_ret, ""), body.join("\n\t\t") ) } /// The C value a closure returns Rust of the C++ value `e` of type `ty`, which Rust then /// owns: bytes as a buffer `_buf_copy` made. `e` is named, so it may be read more /// than once. fn returned(&self, ty: &Type, e: &str) -> String { let d = self.d(); match ty { ty if Abi::is_buf(ty) => format!("{d}::copy_bytes({e})"), Type::Option(inner) if Abi::is_buf(inner) => format!("({e} ? {d}::copy_bytes(*{e}) : {d}::none())"), ty => self.lower(ty, e), } } /// The operations a future's type polls with. fn future(&mut self, function: &Function, owner: Option<&Ty>) { let abi = self.abi; let export = abi.export(function, owner); let Some(abi::Future { handle, poll, free, .. }) = &export.future else { return; }; let name = self.name(handle); let output = self.output(function); let outs: Vec<(String, Ty)> = poll.params[2..] .iter() .filter(|(_, ty)| !abi::is_status(ty)) .cloned() .collect(); let (declared, ok, err) = self.outs(function, &outs, &output); let ok = match (&function.err, &function.ok) { (None, Type::Unit) => "out.emplace();".to_string(), _ => format!("out.emplace({ok});"), }; let mut args = vec!["f".to_string(), "w".to_string()]; args.extend(outs.iter().map(|(name, _)| format!("&c_{name}_"))); // A poll on another thread than a future's that is not `Send` aborts, as C++ throws // nothing. if poll.status().is_some() { args.push("nullptr".to_string()); } let upper = abi.prefix.to_uppercase(); let mut cases = vec![format!("\t\tcase {upper}_POLL_READY:\n\t\t\t{ok}\n\t\t\tbreak;")]; if let Some(err) = err { cases.push(format!( "\t\tcase {upper}_POLL_ERROR:\n\t\t\tout.emplace({err});\n\t\t\tbreak;" )); } cases.push("\t\tdefault:\n\t\t\tbreak;".to_string()); let declared: String = declared.iter().map(|d| format!("\t\t{d}\n")).collect(); self.line(format!( "namespace detail {{\n\nstruct {name}_op {{\n\tusing raw = ::{handle};\n\tusing output = {output};\n\n\tstatic void free(raw *f) noexcept {{\n\t\t::{}(f);\n\t}}\n\n\tstatic void poll(raw *f, c_waker w, slot &out) {{\n{declared}\t\tswitch (::{}({})) {{\n{}\n\t\t}}\n\t}}\n}};\n\n}} // namespace detail\n", free.name, poll.name, args.join(", "), cases.join("\n") )); } } /// The names the runtime declares in the namespace, outside its `detail`, and `detail`. fn runtime_names() -> impl Iterator { let mut detail = false; let lines = RUNTIME.lines().filter(move |line| { match *line { "namespace detail {" => detail = true, "} // namespace detail" => detail = false, _ => {} } !detail }); let names = lines.filter_map(|line| { let rest = ["class ", "struct ", "using "] .iter() .find_map(|kw| line.strip_prefix(kw))?; rest.split(|c: char| !(c.is_ascii_alphanumeric() || c == '_')).next() }); std::iter::once("detail").chain(names) } /// The member `bare` a type's trait exports, in the class `class`, with `_` appended where /// it is the class's name, which C++ would read as a constructor. fn apart(bare: &str, class: &str) -> String { match bare == class { true => format!("{bare}_"), false => bare.to_string(), } } /// The C++ name of the parameter `rust`, with `_` appended while `taken` holds it or it is /// a name the header gives its own locals and members. fn parameter(rust: &str, taken: impl Fn(&str) -> bool) -> String { let mut name = escape(rust); while taken(&name) || generated(&name) { name.push('_'); } name } /// Whether the header names its own locals and members `name`: the arena `a_`, a handle's /// `raw_`, a C value or a closure's trampoline `c_…_`, and a trampoline's or lambda's `f_`, /// `data_`, `p0_`, `l0_`, `x0_`, or `c0_`. fn generated(name: &str) -> bool { let Some(stem) = name.strip_suffix('_') else { return false; }; let numbered = |prefix: char| { stem.strip_prefix(prefix) .is_some_and(|n| !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit())) }; let c_value = stem.starts_with("c_") && !stem.ends_with('_'); matches!(stem, "a" | "raw" | "f" | "data") || c_value || "xcpl".chars().any(numbered) } /// How many lists `ty` nests, which names the element of each list's lambda apart from /// those of the lambdas around it. fn lists(ty: &Type) -> usize { match ty { Type::List(_, inner) => 1 + lists(inner), Type::Option(inner) | Type::Box(inner) | Type::Ref(_, inner) => lists(inner), Type::Tuple(elements) => elements.iter().map(lists).max().unwrap_or(0), _ => 0, } } /// The enum named `c` in C. fn enumeration(abi: &Abi<'_>, c: &str) -> Type { let i = (0..abi.api.enums.len()).find(|&i| abi.enumeration(i) == c); Type::Enum(i.expect("a free method's owner is an enum")) } /// The record named `c` in C. fn record(abi: &Abi<'_>, c: &str) -> Type { let i = (0..abi.api.records.len()).find(|&i| abi.record(i) == c); Type::Record(i.expect("a member method's value is a record")) } /// Whether passing `ty` moves a handle out of a `Vec`, `Option`, or tuple, as a handle /// taken by value is. fn moves(abi: &Abi<'_>, ty: &Type) -> bool { match ty { Type::Object(i) => !abi.api.objects[*i].copy, Type::Option(inner) | Type::Box(inner) | Type::List(_, inner) => moves(abi, inner), Type::Tuple(elements) => elements.iter().any(|e| moves(abi, e)), _ => false, } } /// Whether the object named `c` in C is `Copy`. fn copy(abi: &Abi<'_>, c: &str) -> bool { (0..abi.api.objects.len()).any(|i| abi.api.objects[i].copy && abi.object(i) == c) } /// `ty` returned: a borrow is returned as a clone, so owned. fn strip_refs(ty: &Type) -> Type { match ty { Type::Ref(_, inner) => strip_refs(inner), Type::Option(inner) => Type::Option(Box::new(strip_refs(inner))), Type::Box(inner) => Type::Box(Box::new(strip_refs(inner))), ty => ty.clone(), } } /// A parameter of C++ type `ty` named `name`. fn declare(ty: &str, name: &str) -> String { match ty.ends_with('&') || ty.ends_with('*') { true => format!("{ty}{name}"), false => format!("{ty} {name}"), } } /// A field's initializer, so a default-constructed struct holds no garbage: none for a /// type with no default constructor. fn init(ty: &Type) -> &'static str { match ty { Type::Object(_) | Type::Enum(_) | Type::Record(_) => "", Type::Box(inner) => init(inner), Type::Tuple(elements) if elements.iter().any(|e| init(e).is_empty()) => "", _ => "{}", } } /// C++ comments holding `docs`, each line indented by `indent`, or nothing for none. fn docs(docs: &str, indent: &str) -> String { docs.lines() .map(|line| match line.is_empty() { true => format!("{indent}///\n"), false => format!("{indent}/// {line}\n"), }) .collect() } fn cpp_int(int: Int) -> &'static str { match int { Int::U8 => "::std::uint8_t", Int::U16 => "::std::uint16_t", Int::U32 => "::std::uint32_t", Int::U64 => "::std::uint64_t", Int::Usize => "::std::size_t", Int::I8 => "::std::int8_t", Int::I16 => "::std::int16_t", Int::I32 => "::std::int32_t", Int::I64 => "::std::int64_t", Int::Isize => "::std::ptrdiff_t", } } /// A name C++ would read as a keyword with `_` appended, and one starting with a digit /// with `_` prepended, as C's are. pub(crate) fn escape(name: &str) -> String { const KEYWORDS: &[&str] = &[ "alignas", "alignof", "and", "and_eq", "asm", "auto", "bitand", "bitor", "bool", "break", "case", "catch", "char", "char8_t", "char16_t", "char32_t", "class", "compl", "concept", "const", "consteval", "constexpr", "constinit", "const_cast", "continue", "co_await", "co_return", "co_yield", "decltype", "default", "delete", "do", "double", "dynamic_cast", "else", "enum", "explicit", "export", "extern", "false", "float", "for", "friend", "goto", "if", "inline", "int", "long", "mutable", "namespace", "new", "noexcept", "not", "not_eq", "nullptr", "operator", "or", "or_eq", "private", "protected", "public", "register", "reinterpret_cast", "requires", "restrict", "return", "short", "signed", "sizeof", "static", "static_assert", "static_cast", "struct", "switch", "template", "this", "thread_local", "throw", "true", "try", "typedef", "typeid", "typename", "union", "unsigned", "using", "virtual", "void", "volatile", "wchar_t", "while", "xor", "xor_eq", // What the generated code names unqualified. "std", "self", ]; match name.chars().next() { Some(c) if c.is_ascii_digit() => format!("_{name}"), _ if KEYWORDS.contains(&name) => format!("{name}_"), _ => name.to_string(), } } #[cfg(test)] mod tests { use super::parameter; #[test] fn parameters_keep_apart_from_what_they_would_hide() { let taken = |name: &str| ["a", "size", "size_"].contains(&name); // Past a namespace name, and past the arena `a_` the rename would reach. assert_eq!(parameter("a", taken), "a__"); // Past a name already taken by the first rename. assert_eq!(parameter("size", taken), "size__"); // A keyword escapes as before; a name like a generated one moves out of its way. assert_eq!(parameter("new", taken), "new_"); assert_eq!(parameter("raw_", taken), "raw__"); assert_eq!(parameter("c_out_", taken), "c_out__"); assert_eq!(parameter("x1_", taken), "x1__"); assert_eq!(parameter("x_", taken), "x_"); } }