Crate ffi_support

Expand description

§FFI Support

This crate implements a support library to simplify implementing the patterns that the mozilla/application-services repository uses for it’s “Rust Component” FFI libraries.

It is strongly encouraged that anybody writing FFI code in this repository read this documentation before doing so, as it is a subtle, difficult, and error prone process.

§Terminology

For each library, there are currently three parts we’re concerned with. There’s no clear correct name for these, so this documentation will attempt to use the following terminology:

Rust Component: A Rust crate which does not expose an FFI directly, but may be may be wrapped by one that does. These have a crate-type in their Cargo.toml (see https://doc.rust-lang.org/reference/linkage.html) of lib, and not staticlib or cdylib (Note that lib is the default if crate-type is not specified). Examples include the fxa-client, and logins crates.
FFI Component: A wrapper crate that takes a Rust component, and exposes an FFI from it. These typically have ffi in the name, and have crate-type = ["lib", "staticlib", "cdylib"] in their Cargo.toml. For example, the fxa-client/ffi and logins/ffi crates (note: paths are subject to change). When built, these produce a native library that is consumed by the “FFI Consumer”.
FFI Consumer: This is a low level library, typically implemented in Kotlin (for Android) or Swift (for iOS), that exposes a memory-safe wrapper around the memory-unsafe C API produced by the FFI component. It’s expected that the maintainers of the FFI Component and FFI Consumer be the same (or at least, the author of the consumer should be completely comfortable with the API exposed by, and code in the FFI component), since the code in these is extremely tightly coupled, and very easy to get wrong.

Note that while there are three parts, there may be more than three libraries relevant here, for example there may be more than one FFI consumer (one for Android, one for iOS).

§Usage

This library will typically be used in both the Rust component, and the FFI component, however it frequently will be an optional dependency in the Rust component that’s only available when a feature flag (which the FFI component will always require) is used.

The reason it’s required inside the Rust component (and not solely in the FFI component, which would be nice), is so that types provided by that crate may implement the traits provided by this crate (this is because Rust does not allow crate C to implement a trait defined in crate A for a type defined in crate B).

In general, examples should be provided for the most important types and functions (call_with_result, IntoFfi, ExternError, etc), but you should also look at the code of consumers of this library.

§Usage in the Rust Component

Inside the Rust component, you will implement:

IntoFfi for all types defined in that crate that you want to return over the FFI. For most common cases, the implement_into_ffi_by_json! and implement_into_ffi_by_protobuf! macros will do the job here, however you can see that trait’s documentation for discussion and examples of implementing it manually.
Conversion to ExternError for the error type(s) exposed by that rust component, that is, impl From<MyError> for ExternError.

§Usage in the FFI Component

Inside the FFI component, you will use this library in a few ways:

Destructors will be exposed for each types that had implement_into_ffi_by_pointer! called on it (using define_box_destructor!), and a destructor for strings should be exposed as well, using define_string_destructor
The body of every / nearly every FFI function will be wrapped in either a call_with_result or call_with_output.

This is required because if we panic! (e.g. from an assert!, unwrap(), expect(), from indexing past the end of an array, etc) across the FFI boundary, the behavior is undefined and in practice very weird things tend to happen (we aren’t caught by the caller, since they don’t have the same exception behavior as us).

If you don’t think your program (or possibly just certain calls) can handle panics, you may also use the versions of these functions in the abort_on_panic module, which do as their name suggest.

Additionally, c strings that are passed in as arguments may be represented using FfiStr, which contains several helpful inherent methods for extracting their data.

Re-exports§

pub use crate::handle_map::ConcurrentHandleMap;
pub use crate::handle_map::Handle;
pub use crate::handle_map::HandleError;
pub use crate::handle_map::HandleMap;

Modules§

abort_on_panic: This module exists just to expose a variant of call_with_result and call_with_output that aborts, instead of unwinding, on panic.
handle_map: This module provides a Handle type, which you can think of something like a dynamically checked, type erased reference/pointer type. Depending on the usage pattern a handle can behave as either a borrowed reference, or an owned pointer.

Macros§

define_box_destructor: Define a (public) destructor for a type that was allocated by Box::into_raw(Box::new(value)) (e.g. a pointer which is probably opaque).
define_bytebuffer_destructor: Define a (public) destructor for the ByteBuffer type.
define_handle_map_deleter: Define a (public) destructor for a type that lives inside a lazy_static ConcurrentHandleMap.
define_string_destructor: For a number of reasons (name collisions are a big one, but, it also wouldn’t work on all platforms), we cannot export extern "C" functions from this library. However, it’s pretty common to want to free strings allocated by rust, so many libraries will need this, so we provide it as a macro.
implement_into_ffi_by_delegation: Implement InfoFfi for a type by converting through another type.
implement_into_ffi_by_json: Implements IntoFfi for the provided types (more than one may be passed in) by converting to the type to a JSON string.
implement_into_ffi_by_pointer: Implements IntoFfi for the provided types (more than one may be passed in) by allocating $T on the heap as an opaque pointer.
implement_into_ffi_by_protobuf: Implements IntoFfi for the provided types (more than one may be passed in) implementing prost::Message (protobuf auto-generated type) by converting to the type to a ByteBuffer. This ByteBuffer should later be passed by value.
static_assert: Force a compile error if the condition is not met. Requires a unique name for the assertion for… reasons. This is included mainly because it’s a common desire for FFI code, but not for other sorts of code.

Structs§

ByteBuffer: ByteBuffer is a struct that represents an array of bytes to be sent over the FFI boundaries. There are several cases when you might want to use this, but the primary one for us is for returning protobuf-encoded data to Swift and Java. The type is currently rather limited (implementing almost no functionality), however in the future it may be more expanded.
ErrorCode: A wrapper around error codes, which is represented identically to an i32 on the other side of the FFI. Essentially exists to check that we don’t accidentally reuse success/panic codes for other things.
ExternError: Represents an error that occured within rust, storing both an error code, and additional data that may be used by the caller.
FfiStr: FfiStr<'a> is a safe (#[repr(transparent)]) wrapper around a nul-terminated *const c_char (e.g. a C string). Conceptually, it is similar to std::ffi::CStr, except that it may be used in the signatures of extern “C” functions.

Traits§

IntoFfi: This trait is used to return types over the FFI. It essentially is a mapping between a type and version of that type we can pass back to C (IntoFfi::Value).

Functions§

call_with_output: Call a callback that returns a T while:
call_with_result: Call a callback that returns a Result<T, E> while:
destroy_c_string^⚠: Free the memory of a string created by rust_string_to_c on the rust heap. If c_string is null, this is a no-op.
ensure_panic_hook_is_setup: Initialize our panic handling hook to optionally log panics
opt_rust_str_from_c^⚠Deprecated: Same as rust_string_from_c, but returns None if c_string is null instead of asserting.
opt_rust_string_from_c^⚠Deprecated: Same as rust_string_from_c, but returns None if c_string is null instead of asserting.
opt_rust_string_to_c: Variant of rust_string_to_c which takes an Option, and returns null for None.
rust_str_from_c^⚠Deprecated: Convert a null-terminated C string to a rust str. This does not take ownership of the string, and you should be careful about the lifetime of the resulting string. Note that strings containing invalid UTF-8 are replaced with the empty string (for many cases, you will want to use rust_string_from_c instead, which will do a lossy conversion).
rust_string_from_c^⚠Deprecated: Convert a null-terminated C into an owned rust string, replacing invalid UTF-8 with the unicode replacement character.
rust_string_to_c: Convert a rust string into a NUL-terminated utf-8 string suitable for passing to C, or to things ABI-compatible with C.