---
type: slide
slideOptions:
center: false
---

<style>
.reveal {
font-size: 2.5rem;
}
.reveal a code {
color: var(--r-link-color);
}
</style>

# Rust FFI

<br><br>
Philipp Oppermann & Xavier Tao
June 7, 2022

Maintainers of [dora-rs](https://github.com/dora-rs/dora/)

---

## Why does Rust has FFI?

Use and be used by program not written in Rust.
- This can for exemple be for:
- binding legacy software
- using other language functionalities.
- distributing Rust code on a large scale.
- ...

---

## Application Binary Interface (ABI)

- The ABI defines the details of functions calls and other types of control transfers
- argument passing, e.g. in specific CPU registers or on the stack
- stack layout
- memory layout of data types
- etc.
- To call functions across compilation units, they must agree on an ABI
- Either use the exact same compiler for all compilation units
- Or use a standardized ABI, e.g. the C ABI

---

## Rust ⇄ C

Rust has native support for the C ABI and can be linked directly with C code

- Call C function from Rust:

  // the standard library provides support for C primitives
  use core::ffi::{c_uint, c_double};

  // link against a set of functions from a `c_library`
  #[link(name = "c_library")] 
  extern "C" {
      fn foo(value: c_uint) -> c_double;
  }

  // create a safe wrapper function for convenience (the  compiler
  // will optimize this away)
  fn foo_wrapper(value: u32) -> f64 {
      // the external funciton is unsafe to call because it might
      // violate memory safety
      unsafe { foo(value) }
  }

- Make Rust callable from C:

  // don't mangle the name of this function so that the
  // C code and linker can find it
  #[no_mangle]
  // use the C calling convention instead of
  // Rust's unstable calling convention
  pub extern "C" fn bar(ptr: *const core::ffi::c_char) -> bool {
      ptr.is_null()    
  }

- More details at: https://doc.rust-lang.org/nomicon/ffi.html

---

## Rust ⇄ C — Datatypes

- Working with strings:

  use core::ffi::{c_char, c_uint, CStr};

  #[no_mangle]
  pub extern "C" fn get_len(string: *const c_char) -> c_uint {
      let s = unsafe { CStr::from_ptr(my_string()) };
      s.to_bytes().len() as c_uint
  }

- Create C-compatible structs and enums using `repr(C)`:

  // the `repr(C)` attribute keeps the specified field order and
  // adds padding in the same way as a C compiler would
  #[repr(C)]
  struct Foo {
      field_1: u32,
      field_2: [u8; 17],
      field_3: u64, // there will be some padding before this field
  }

See the [`really_tagged_unions` RFC](https://github.com/rust-lang/rfcs/blob/master/text/2195-really-tagged-unions.md) for details on `repr(C)` enums.

---

## Rust ⇄ C — Autogenerate

- Create bindings automatically
- Use [`bindgen`](https://rust-lang.github.io/rust-bindgen/introduction.html) to create Rust bindings for C header files
- Use [`cbindgen`](https://github.com/eqrion/cbindgen/blob/master/docs.md) to create C header files from Rust code
- There are also frameworks such as [`safer-ffi`](https://getditto.github.io/safer_ffi/) with support for higher-level types such as `Box`, `Vec`, and closures
- Use Rust [build scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html) and builder library such as [`cc`](https://docs.rs/cc/latest/cc/) to compile C dependencies automatically
- Example: [build script of `curl-sys` crate](https://github.com/alexcrichton/curl-rust/blob/main/curl-sys/build.rs), which creates bindings to [`curl`](https://curl.se/) library written in C

---

## Rust ⇄ Rust

- The default Rust ABI is not stable
- The ABI might change between Rust releases
- Linking Rust code built with different compilers might result in undefined behavior
- Advantage: New releases can optimize ABI, e.g. by reordering struct fields to eliminate alignment padding
- To safely link independently compiled Rust libraries, they need to go through the C ABI
- This can be limiting since many of Rust's high-level concepts are not compatible with the C ABI (e.g. lifetimes, generics, trait objects)
- Crates like [`safer-ffi`](https://docs.rs/safer-ffi/0.0.10/safer_ffi/) or [`abi-stable`](https://docs.rs/abi_stable/0.10.4/abi_stable/) try to make this approach easier
- There are various proposals for creating an optional "stable-rust" ABI
- For example the [`
#[repr(Interoperable_2024)]`](https://internals.rust-lang.org/t/repr-interoperable-2024/16763) proposal

---

## Rust ⇄ C++

- Both Rust and C++ support the C ABI
- The [`cxx`](https://cxx.rs/) project provides a safe, high-level bridge
- For binding to large existing C++ projects, use [`autocxx`](https://google.github.io/autocxx/)
- builds on top of `cxx`
- autogenerates bindings based on C++ header files
- Limitations
- closures are not supported (see [dtolnay/cxx#104](https://github.com/dtolnay/cxx/issues/114))
- lifetime parameters are not supported (see [dtolnay/cxx#122](https://github.com/dtolnay/cxx/issues/122))
- [bridging async functions](https://cxx.rs/async.html) is not implemented yet

---

## Rust ⇄ Python

Python can not use Rust code by default. 😢

Python can however use compiled shared libraries (e.g. a .so file on Linux, .pyd on Windows) [1].

And Rust can be compiled as a C-shared libraries through its C-FFI binding.

In a similar way, Rust can run Python through its shared library `libpython*.so`

We can therefore bind the two together using the shared libraries. ☺️

[1]: https://docs.python.org/3/extending/building.html

---

## Rust ⇄ Python  — PyO3

The [`PyO3`](https://pyo3.rs/v0.17.1/) project makes this binding process easier by automatically generating bindings from existing Rust Code.

It will take care of things like:
- Type conversions
- lifetimes
- Global interpreter lock (GIL)
- Error handling

---

## Pyo3 Examples

- Making a Rust function usable in Python

use pyo3::prelude::*;

/// Formats the sum of two numbers as string.
#[pyfunction]
fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
    Ok((a + b).to_string())
}

/// A Python module implemented in Rust.
#[pymodule]
fn string_sum(py: Python<'_>, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;

    Ok(())
}

- Calling Python from Rust:

use pyo3::prelude::*;

fn main() -> PyResult<()> {
    Python::with_gil(|py| {
        let sys = py.import("sys")?;
        let version: String = sys.getattr("version")?.extract()?;

        println!("Hello, I'm Python {}", version);
        Ok(())
    })
}

More info here: https://docs.rs/pyo3/0.17.1/pyo3/

---

## Performance gain from using Rust instead of Python

Performance gain is one of the most common reason to use Rust within Pyhon.

On a simple benchmark of word counting. Rust can be significantly faster sequentially and in parallel.

-------------------------------------------------------------------------------------------------- benchmark: 4 tests -------------------------------------------------------------------------------------------------
Name (time in ms)                                          Min                Max               Mean            StdDev             Median               IQR            Outliers       OPS            Rounds  Iterations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
word_count_rust_parallel                           1.7315 (1.0)       4.6495 (1.0)       1.9972 (1.0)      0.4299 (1.0)       1.8142 (1.0)      0.2049 (1.0)         40;46  500.6943 (1.0)         375           1
word_count_rust_sequential                         7.3348 (4.24)     10.3556 (2.23)      8.0035 (4.01)     0.7785 (1.81)      7.5597 (4.17)     0.8641 (4.22)         26;5  124.9457 (0.25)        121           1
word_count_python_sequential                      27.3985 (15.82)    45.4527 (9.78)     28.9604 (14.50)    4.1449 (9.64)     27.5781 (15.20)    0.4638 (2.26)          3;5   34.5299 (0.07)         35           1
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

More info here: https://pyo3.rs/v0.17.1/parallelism.html

---

## FFI binding in DORA

- In the case of `dora`, FFI bindings generates API bindings for Python and C. This makes it easy for developpers to use `dora` with their favorite language.

- For python, we aim at distributing `dora` API as python packages, installable via `pip` python package manager.
- For C, we generate a header file and a shared library, that developpers can use to build their application.

- The integration of `dora` becomes seemless as it blends with their known ecosystem.

---

## FFI limitations

- Although Rust FFI has a lot of tractions and much has been done, their is still limitations.

---

## Asynchronous FFI limitation

Asynchronous code lets you manage concurrent task using futures.

Unfortunately, there is not always a way to translate a futures from one language to another.

You will often need two async loop to be able to communicate asynchronous tasks from one language to another.

Schematically:

Python Future -> Python Asyncio Runtime -> Rust Future -> Rust Tokio Runtime 

This can be detrimental in a high concurrency situation.

More info here: https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/

---

## Type conversion and memory cost

There isn't a generic types for all languages. Therefore, FFI needs to convert types when passing values.

Type conversion through FFI will usually require a cost. This cost is going to be small on simple primitive type (e.g. int, float, pointers) and big for complex type
(e.g. Python Object). This cost can be performance or memory redundancy.


See: https://hacks.mozilla.org/2019/08/webassembly-interface-types/
And: https://pyo3.rs/v0.11.1/conversions.html

---

Discussions:
-