Crate ffi_convert

Expand description

A collection of utilities (traits, data structures, conversion functions, 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 developer uses best practices when performing the conversion in both directions (ownership-wise).

The crate also provides a collection of useful utility functions and traits 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 (via a copy), 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 defining the fields of the Pizza struct :

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 :

#[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 libc::{c_char, c_float};

struct Sauce {};
#[derive(CReprOf, AsRust, CDrop, RawPointerConverter)]
#[target_type(Sauce)]
struct CSauce {};

#[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 two traits : the CDrop trait and the RawPointerConverter 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.

The RawPointerConverter trait is implemented to perform the conversion of a C-like struct to a raw-pointer to this C-like structure (and conversely). Here, it is used behind the scene to convert a CSauce struct to a pointer to a raw pointer to CSause struct : *const CSauce (needed behind the scenes when the CReprOf trait is derived for CPizza).

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

Types representations mapping

T : CReprOf<U> + AsRust<U>

C type	Rust type	C-compatible Rust type
`const char*`	`String`	`*const libc::c_char`
`const T*`	`U`	`*const T`
`T*`	`U`	`*mut T`
`T`	`U`	`T`
`const T*`	`Option<U>`	`*const T` (with `#[nullable]` field annotation)
`CArrayT`	`Vec<U>`	`CArray<T>`
`CStringArray`	`Vec<String>`	`CStringArray`
`CRangeT`	`Range<U>`	`CRange<T>`

The CReprOf trait

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

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

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 :

pub trait AsRust<T> {
    fn as_rust(&self) -> Result<T, AsRustError>;
}

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 from this struct.

CArray
A utility type to represent arrays of the parametrized type. Note that the parametrized type should have a C-compatible representation.
CRange
A utility type to represent range. Note that the parametrized type T should have have CReprOf and AsRust trait implementated.
CStringArray
A utility type to represent arrays of string
UnexpectedNullPointerError

Enums

Traits

AsRust
Trait showing 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
CDrop
Trait showing that the C-like struct implementing it can free up its part of memory that are not managed by Rust.
CReprOf
Trait showing that the struct implementing it is a repr(C) compatible view of the parametrized type that can be created from an value of this type.
RawBorrow
Trait to create borrowed references to type T, from a raw pointer to a T. Note that this is implemented for all types.
RawBorrowMut
Trait to create mutable borrowed references to type T, from a raw pointer to a T. Note that this is implemented for all types.
RawPointerConverter
Trait representing the creation of a raw pointer from a struct and the recovery of said pointer.

Crate ffi_convert

Usage

Example

Types representations mapping

The CReprOf trait

The AsRust trait

The CDrop trait

The RawPointerConverter trait

Structs

Enums

Traits

Derive Macros