Crate foreign

A comprehensive library providing safe abstractions for Foreign Function Interface (FFI) operations. The foreign crate offers traits to safely convert between Rust types and their C representations, providing clarity about which operations allocate memory and therefore the performance characteristics.

Overview

When working with C libraries from Rust, different Rust types may have different naming and conventions for converting to their C representation and back. Even if you try to keep a common convention for your own enums and structs, they still wouldn’t apply to standard library structs such as String/str and CString/CStr.

This library provides a comprehensive set of traits and wrapper types that abstract the lifetime of the resulting pointers and that make these operations ergonomic.

The conversion traits themselves follow intuitive naming patterns that clearly indicate their behavior and ownership implications. Rust terms like clone or clone_from are used to show clearly where allocations happen. FromForeign and its dual IntoNative convert C data to Rust, and there are a variety of traits for different scenarios of C → Rust conversion: CloneToForeign is the most generic but performs a deep copy; IntoForeign consumes the Rust object; BorrowForeign and BorrowForeignMut borrow the contents of the Rust object and perform no allocation. The performance characteristics of each conversion are fixed: methods other than clone_to_foreign() are only available if they can operate with no copying.

Usage examples

Rust → C Conversion

Copying:

let foreign = rust_value.clone_to_foreign();
call_c_function(foreign.as_ptr());
// Value freed automatically

Giving ownership to C:

let foreign_ptr = rust_value.clone_to_foreign_ptr();
call_c_function(foreign_ptr);

Consuming:

// rust_value is typically heap-allocated, e.g. a Box, String or Vec
let foreign = rust_value.into_foreign();
call_c_function(foreign.as_ptr());
// Value freed automatically

Borrowing for temporary use:

let rust_data = get_some_data();
let borrowed = rust_data.borrow_foreign();
call_c_function(borrowed.as_ptr());

C → Rust Conversion

Copying:

let rust_value = unsafe { RustType::cloned_from_foreign(c_ptr) };

Copying and freeing the C version:

let rust_value = unsafe { RustType::from_foreign(c_ptr) };

let rust_value: RustType = unsafe { c_ptr.into_native() };

Comparison to glib-rs

glib-rs provides a similar set of traits. A rough comparison is as follows:

glib-rs	foreign-rs
from_glib_full()	from_foreign()
from_glib_none()	cloned_from_foreign()
to_glib_full()	clone_to_foreign_ptr()
to_glib_none()	clone_to_foreign()

Modules

prelude

Re-export commonly used traits from this crate

Structs

BorrowedMutPointer

A pointer whose contents were borrowed from a Rust object, and therefore whose lifetime is limited to the lifetime of the underlying Rust object. The Rust object is borrowed from an exclusive reference, and therefore the pointer is mutable.

BorrowedPointer

A pointer whose contents were borrowed from a Rust object, and therefore whose lifetime is limited to the lifetime of the underlying Rust object. The Rust object was borrowed from a shared reference, and therefore the pointer is not mutable.

OwnedPointer

A RAII pointer that is automatically freed when it goes out of scope.

Traits

BorrowForeign

A type for which a C representation can be borrowed without cloning.

BorrowForeignMut

A type for which a C representation can be borrowed mutably without cloning.

CloneToForeign

A type for which a representation as a C datum can be produced.

FixedAlloc

A type which is stored in a fixed amount of memory given by mem::size_of::<Self::Foreign>().

FreeForeign

A type for which there is a canonical representation as a C datum.

FromForeign

A type which can be constructed from a canonical representation as a C datum.

IntoForeign

A type for which a C representation can be created by consuming the Rust representation, hopefully without cloning much of the internal data.

IntoNative

A type for C data that can be converted to native Rust object, taking ownership of the C datum. You should not need to implement this trait as long as the Rust types implement FromForeign.