docs/writing-rust-code/ffi.md

   1 # Rust/C++ interop
   2
   3 This document describes how to use FFI in Firefox to get Rust code and C++ code to interoperate.
   4
   5 ## Transferable types
   6
   7 Generally speaking, the more complicated is the data you want to transfer, the
   8 harder it'll be to transfer across the FFI boundary.
   9
  10 Booleans, integers, and pointers cause little trouble.
  11 - C++ `bool` matches Rust `bool`
  12 - C++ `uint8_t` matches Rust `u8`, `int32_t` matches Rust `i32`, etc.
  13 - C++ `const T*` matches Rust `*const T`, `T*` matches Rust `*mut T`.
  14
  15 Lists are handled by C++ `nsTArray` and Rust `ThinVec`.
  16
  17 For strings, it is best to use the `nsstring` helper crate. Using a raw pointer
  18 plus length is also possible for strings, but more error-prone.
  19
  20 If you need a hashmap, you'll likely want to decompose it into two lists (keys
  21 and values) and transfer them separately.
  22
  23 Other types can be handled with tools that generate bindings, as the following
  24 sections describe.
  25
  26 ## Accessing C++ code and data from Rust
  27
  28 To call a C++ function from Rust requires adding a function declaration to Rust.
  29 For example, for this C++ function:
  30
  31 ```
  32 extern "C" {
  33 bool UniquelyNamedFunction(const nsCString* aInput, nsCString* aRetVal) {
  34   return true;
  35 }
  36 }
  37 ```
  38 add this declaration to the Rust code:
  39 ```rust
  40 extern "C" {
  41     pub fn UniquelyNamedFunction(input: &nsCString, ret_val: &mut nsCString) -> bool;
  42 }
  43 ```
  44
  45 Rust code can now call `UniquelyNamedFunction()` within an `unsafe` block. Note
  46 that if the declarations do not match (e.g. because the C++ function signature
  47 changes without the Rust declaration being updated) crashes are likely. (Hence
  48 the `unsafe` block.)
  49
  50 Because of this unsafety, for non-trivial interfaces (in particular when C++
  51 structs and classes must be accessed from Rust code) it's common to use
  52 [rust-bindgen](https://github.com/rust-lang/rust-bindgen), which generates Rust
  53 bindings. The documentation is
  54 [here](https://rust-lang.github.io/rust-bindgen/).
  55
  56 ## Accessing Rust code and data from C++
  57
  58 A common option for accessing Rust code and data from C++ is to use
  59 [cbindgen](https://github.com/eqrion/cbindgen), which generates C++ header
  60 files. for Rust crates that expose a public C API. cbindgen is a very powerful
  61 tool, and this section only covers some basic uses of it.
  62
  63 ### Basics
  64
  65 First, add suitable definitions to your Rust. `#[no_mangle]` and `extern "C"`
  66 are required.
  67
  68 ```rust
  69 #[no_mangle]
  70 pub unsafe extern "C" fn unic_langid_canonicalize(
  71     langid: &nsCString,
  72     ret_val: &mut nsCString
  73 ) -> bool {
  74     ret_val.assign("new value");
  75     true
  76 }
  77 ```
  78
  79 Then, add a `cbindgen.toml` file in the root of your crate. It may look like this:
  80
  81 ```toml
  82 header = """/* This Source Code Form is subject to the terms of the Mozilla Public
  83  * License, v. 2.0. If a copy of the MPL was not distributed with this
  84  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */"""
  85 autogen_warning = """/* DO NOT MODIFY THIS MANUALLY! This file was generated using cbindgen. See RunCbindgen.py */
  86 #ifndef mozilla_intl_locale_MozLocaleBindings_h
  87 #error "Don't include this file directly, instead include MozLocaleBindings.h"
  88 #endif
  89 """
  90 include_version = true
  91 braces = "SameLine"
  92 line_length = 100
  93 tab_width = 2
  94 language = "C++"
  95 # Put FFI calls in the `mozilla::intl::ffi` namespace.
  96 namespaces = ["mozilla", "intl", "ffi"]
  97
  98 # Export `ThinVec` references as `nsTArray`.
  99 [export.rename]
 100 "ThinVec" = "nsTArray"
 101 ```
 102
 103 Next, extend the relevant `moz.build` file to invoke cbindgen.
 104
 105 ```python
 106 if CONFIG['COMPILE_ENVIRONMENT']:
 107     CbindgenHeader('unic_langid_ffi_generated.h',
 108                    inputs=['/intl/locale/rust/unic-langid-ffi'])
 109
 110     EXPORTS.mozilla.intl += [
 111         '!unic_langid_ffi_generated.h',
 112     ]
 113 ```
 114
 115 This tells the build system to run cbindgen on
 116 `intl/locale/rust/unic-langid-ffi` to generate `unic_langid_ffi_generated.h`,
 117 which will be placed in `$OBJDIR/dist/include/mozilla/intl/`.
 118
 119 Finally, include the generated header into a C++ file and call the function.
 120
 121 ```c++
 122 #include "mozilla/intl/unic_langid_ffi_generated.h"
 123
 124 using namespace mozilla::intl::ffi;
 125
 126 void Locale::MyFunction(nsCString& aInput) const {
 127   nsCString result;
 128   unic_langid_canonicalize(aInput, &result);
 129 }
 130 ```
 131
 132 ### Complex types
 133
 134 Many complex Rust types can be exposed to C++, and cbindgen will generate
 135 appropriate bindings for all `pub` types. For example:
 136
 137 ```rust
 138 #[repr(C)]
 139 pub enum FluentPlatform {
 140     Linux,
 141     Windows,
 142     Macos,
 143     Android,
 144     Other,
 145 }
 146
 147 extern "C" {
 148     pub fn FluentBuiltInGetPlatform() -> FluentPlatform;
 149 }
 150 ```
 151
 152 ```c++
 153 ffi::FluentPlatform FluentBuiltInGetPlatform() {
 154   return ffi::FluentPlatform::Linux;
 155 }
 156 ```
 157
 158 For an example using cbindgen to expose much more complex Rust types to C++,
 159 see [this blog post].
 160
 161 [this blog post]: https://crisal.io/words/2020/02/28/C++-rust-ffi-patterns-1-complex-data-structures.html
 162
 163 ### Instances
 164
 165 If you need to create and destroy a Rust struct from C++ code, the following
 166 example may be helpful.
 167
 168 First, define constructor, destructor and getter functions in Rust. (C++
 169 declarations for these will be generated by cbindgen.)
 170
 171 ```rust
 172 #[no_mangle]
 173 pub unsafe extern "C" fn unic_langid_new() -> *mut LanguageIdentifier {
 174     let langid = LanguageIdentifier::default();
 175     Box::into_raw(Box::new(langid))
 176 }
 177
 178 #[no_mangle]
 179 pub unsafe extern "C" fn unic_langid_destroy(langid: *mut LanguageIdentifier) {
 180     drop(Box::from_raw(langid));
 181 }
 182
 183 #[no_mangle]
 184 pub unsafe extern "C" fn unic_langid_as_string(
 185     langid: &mut LanguageIdentifier,
 186     ret_val: &mut nsACString,
 187 ) {
 188     ret_val.assign(&langid.to_string());
 189 }
 190 ```
 191
 192 Next, in a C++ header define a destructor via `DefaultDelete`.
 193
 194 ```c++
 195 #include "mozilla/intl/unic_langid_ffi_generated.h"
 196 #include "mozilla/UniquePtr.h"
 197
 198 namespace mozilla {
 199
 200 template <>
 201 class DefaultDelete<intl::ffi::LanguageIdentifier> {
 202  public:
 203   void operator()(intl::ffi::LanguageIdentifier* aPtr) const {
 204     unic_langid_destroy(aPtr);
 205   }
 206 };
 207
 208 }  // namespace mozilla
 209 ```
 210
 211 (This definition must be visible any place where
 212 `UniquePtr<intl::ffi::LanguageIdentifier>` is used, otherwise C++ will try to
 213 free the code, which might lead to strange behaviour!)
 214
 215 Finally, implement the class.
 216
 217 ```c++
 218 class Locale {
 219 public:
 220   explicit Locale(const nsACString& aLocale)
 221     : mRaw(unic_langid_new()) {}
 222
 223   const nsCString Locale::AsString() const {
 224     nsCString tag;
 225     unic_langid_as_string(mRaw.get(), &tag);
 226     return tag;
 227   }
 228
 229 private:
 230   UniquePtr<ffi::LanguageIdentifier> mRaw;
 231 }
 232 ```
 233
 234 This makes it possible to instantiate a `Locale` object and call `AsString()`,
 235 all from C++ code.
 236
 237 ## Other examples
 238
 239 For a detailed explanation of an interface in Firefox that doesn't use cbindgen
 240 or rust-bindgen, see [this blog post](https://hsivonen.fi/modern-cpp-in-rust/).