A collection of utilities (functions, traits, data structures, etc ...) to ease conversion between Rust and C-compatible data structures.

Through two conversion traits, CReprOf and AsRust, this crate provides a framework to convert idiomatic Rust structs to C-compatible structs that can pass through an FFI boundary, and conversely. They ensure that the developper uses best practices when performing the conversion in both directions (ownership-wise).

The crate also provides a collection of useful utility functions to perform conversions of types. It goes hand in hand with the ffi-convert-derive crate as it provides an automatic derivation of the CReprOf and AsRust trait.

Usage

When dealing with an FFI frontier, the general philosophy of the crate is :

When receiving pointers to structs created by C code, the struct is immediately converted to an owned, idiomatic Rust struct through the use of the AsRust trait.
To send an idiomatic, owned Rust struct to C code, the struct is converted to C-compatible representation using the CReprOf trait.

Example

We want to be able to convert a Pizza Rust struct that has an idiomatic representation to a CPizza Rust struct that has a C-compatible representation in memory. We start by definining the fields of the Pizza struct :

# struct Topping {};
# struct Sauce {};
pub struct Pizza {
pub name: String,
pub toppings: Vec<Topping>,
pub base: Option<Sauce>,
pub weight: f32,
}

We then create the C-compatible struct by mapping idiomatic Rust types to C-compatible types :

# use ffi_convert::CArray;
# struct CTopping {};
# struct CSauce {};
#[repr(C)]
pub struct CPizza {
pub name: *const libc::c_char,
pub toppings: *const CArray<CTopping>,
pub base: *const CSauce,
pub weight: libc::c_float,
}

This crate provides two traits that are useful for converting between Pizza to CPizza and conversely.

CPizza::c_repr_of(pizza)
<=================|

CPizza                   Pizza

|=================>
cpizza.as_rust()

Instead of manually writing the body of the conversion traits, we can derive them :

# use ffi_convert::{CReprOf, AsRust, CDrop};
# use ffi_convert::CArray;
# use ffi_convert::RawBorrow;
# struct Sauce {};
# #[derive(CReprOf, AsRust, CDrop)]
# #[target_type(Sauce)]
# struct CSauce {};
# struct Topping {};
# #[derive(CReprOf, AsRust, CDrop)]
# #[target_type(Topping)]
# struct CTopping {};
#
# struct Pizza {
#     name: String,
#     toppings: Vec<Topping>,
#     base: Sauce,
#     weight: f32
# };
use libc::{c_char, c_float};

#[repr(C)]
#[derive(CReprOf, AsRust, CDrop)]
#[target_type(Pizza)]
pub struct CPizza {
pub name: *const c_char,
pub toppings: *const CArray<CTopping>,
pub base: *const CSauce,
pub weight: c_float,
}

You may have noticed that you have to derive the CDrop trait. The CDrop trait needs to be implemented on every C-compatible struct that require manual resource management. The release of those resources should be done in the drop method of the CDrop trait.

You can now pass the CPizza struct through your FFI boundary !

Types representations mapping

typedef struct {
const T *values; // Pointer to the value of the list
int32_t size; // Number of T values in the list
} CArrayT;

The CReprOf trait

The CReprOf trait allows to create a C-compatible representation of the reciprocal idiomatic Rust struct by consuming the latter.

# use ffi_convert::{Error, CDrop};
pub trait CReprOf<T>: Sized + CDrop {
fn c_repr_of(input: T) -> Result<Self, Error>;
}

This shows that the struct implementing it is a repr(C) compatible view of the parametrized type and can be created from an object of this type.

The AsRust trait

When trying to convert a repr(C) struct that originated from C, the philosophy is to immediately convert the struct to an owned idiomatic representation of the struct via the AsRust trait. The AsRust trait allows to create an idiomatic Rust struct from a C-compatible struct :

# use ffi_convert::{Error, CDrop};
pub trait AsRust<T> {
fn as_rust(&self) -> Result<T, Error>;
}

This shows that the struct implementing it is a repr(C) compatible view of the parametrized type and that an instance of the parametrized type can be created form this struct.

The CDrop trait

A Trait showing that the repr(C) compatible view implementing it can free up its part of memory that are not managed by Rust drop mechanism.