Safe interop between Rust and C++.zip

CXX &mdash; safe FFI between Rust and C++ ========================================= [<img alt="github" src="https://img.shields.io/badge/github-dtolnay/cxx-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/cxx) [<img alt="crates.io" src="https://img.shields.io/crates/v/cxx.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/cxx) [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-cxx-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/cxx) [<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/cxx/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/cxx/actions?query=branch%3Amaster) This library provides a **safe** mechanism for calling C++ code from Rust and Rust code from C++, not subject to the many ways that things can go wrong when using bindgen or cbindgen to generate unsafe C-style bindings. This doesn't change the fact that 100% of C++ code is unsafe. When auditing a project, you would be on the hook for auditing all the unsafe Rust code and *all* the C++ code. The core safety claim under this new model is that auditing just the C++ side would be sufficient to catch all problems, i.e. the Rust side can be 100% safe. ```toml [dependencies] cxx = "1.0" [build-dependencies] cxx-build = "1.0" ``` *Compiler support: requires rustc 1.60+ and c++11 or newer*<br> *[Release notes](https://github.com/dtolnay/cxx/releases)* <br> ## Guide Please see **<https://cxx.rs>** for a tutorial, reference material, and example code. <br> ## Overview The idea is that we define the signatures of both sides of our FFI boundary embedded together in one Rust module (the next section shows an example). From this, CXX receives a complete picture of the boundary to perform static analyses against the types and function signatures to uphold both Rust's and C++'s invariants and requirements. If everything checks out statically, then CXX uses a pair of code generators to emit the relevant `extern "C"` signatures on both sides together with any necessary static assertions for later in the build process to verify correctness. On the Rust side this code generator is simply an attribute procedural macro. On the C++ side it can be a small Cargo build script if your build is managed by Cargo, or for other build systems like Bazel or Buck we provide a command line tool which generates the header and source file and should be easy to integrate. The resulting FFI bridge operates at zero or negligible overhead, i.e. no copying, no serialization, no memory allocation, no runtime checks needed. The FFI signatures are able to use native types from whichever side they please, such as Rust's `String` or C++'s `std::string`, Rust's `Box` or C++'s `std::unique_ptr`, Rust's `Vec` or C++'s `std::vector`, etc in any combination. CXX guarantees an ABI-compatible signature that both sides understand, based on builtin bindings for key standard library types to expose an idiomatic API on those types to the other language. For example when manipulating a C++ string from Rust, its `len()` method becomes a call of the `size()` member function defined by C++; when manipulating a Rust string from C++, its `size()` member function calls Rust's `len()`. <br> ## Example In this example we are writing a Rust application that wishes to take advantage of an existing C++ client for a large-file blobstore service. The blobstore supports a `put` operation for a discontiguous buffer upload. For example we might be uploading snapshots of a circular buffer which would tend to consist of 2 chunks, or fragments of a file spread across memory for some other reason. A runnable version of this example is provided under the *demo* directory of this repo. To try it out, run `cargo run` from that directory. ```rust #[cxx::bridge] mod ffi { // Any shared structs, whose fields will be visible to both languages. struct BlobMetadata { size: usize, tags: Vec<String>, } extern "Rust" { // Zero or more opaque types which both languages can pass around but // only Rust can see the fields. type MultiBuf; // Functions implemented in Rust. fn next_chunk(buf: &mut MultiBuf) -> &[u8]; } unsafe extern "C++" { // One or more headers with the matching C++ declarations. Our code // generators don't read it but it gets #include'd and used in static // assertions to ensure our picture of the FFI boundary is accurate. include!("demo/include/blobstore.h"); // Zero or more opaque types which both languages can pass around but // only C++ can see the fields. type BlobstoreClient; // Functions implemented in C++. fn new_blobstore_client() -> UniquePtr<BlobstoreClient>; fn put(&self, parts: &mut MultiBuf) -> u64; fn tag(&self, blobid: u64, tag: &str); fn metadata(&self, blobid: u64) -> BlobMetadata; } } ``` Now we simply provide Rust definitions of all the things in the `extern "Rust"` block and C++ definitions of all the things in the `extern "C++"` block, and get to call back and forth safely. Here are links to the complete set of source files involved in the demo: - [demo/src/main.rs](demo/src/main.rs) - [demo/build.rs](demo/build.rs) - [demo/include/blobstore.h](demo/include/blobstore.h) - [demo/src/blobstore.cc](demo/src/blobstore.cc) To look at the code generated in both languages for the example by the CXX code generators: ```console # run Rust code generator and print to stdout # (requires https://github.com/dtolnay/cargo-expand) $ cargo expand --manifest-path demo/Cargo.toml # run C++ code generator and print to stdout $ cargo run --manifest-path gen/cmd/Cargo.toml -- demo/src/main.rs ``` <br> ## Details As seen in the example, the language of the FFI boundary involves 3 kinds of items: - **Shared structs** &mdash; their fields are made visible to both languages. The definition written within cxx::bridge is the single source of truth. - **Opaque types** &mdash; their fields are secret from the other language. These cannot be passed across the FFI by value but only behind an indirection, such as a reference `&`, a Rust `Box`, or a `UniquePtr`. Can be a type alias for an arbitrarily complicated generic language-specific type depending on your use case. - **Functions** &mdash; implemented in either language, callable from the other language. Within the `extern "Rust"` part of the CXX bridge we list the types and functions for which Rust is the source of truth. These all implicitly refer to the `super` module, the parent module of the CXX bridge. You can think of the two items listed in the example above as being like `use super::MultiBuf` and `use super::next_chunk` except re-exported to C++. The parent module will either contain the definitions directly for simple things, or contain the relevant `use` statements to bring them into scope from elsewhere. Within the `extern "C++"` part, we list types and functions for which C++ is the source of truth, as well as the header(s) that declare those APIs. In the future it's possible that this section could be generated bindgen-style from the headers but for now we need the signatures written out; static assertions will verify that they are accurate. Your function implementations themselves, whether in C++ or Rust, *do not* need to be defined as `extern "C"` ABI or no\_mangle. CXX will put in the right shims where necessary to make it all work. <br> ## Comparison vs bindgen and cbindgen Notice that with CXX there is repetition of all the function signatures: they are typed out once where the implementation is defined (in C++ or Rust) and again inside the cxx::bridge module, though compile-time assertions guarantee these are kept in sync. This is different from [bi