FFI2 is a procedural macro. It will run at compile time and transform your program's source code.

Adding `ffi2` macro(s) as a dependency

Run this command in a terminal, in your project's directory:

cargo add ffi2

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

ffi2 = "0.1.0"

You may need to import the macro(s) with use ffi2::*.

Read the ffi2 documentation.

Back to the crate overview.

Readme

FFI2

Note: fork of unmaintained ffi crate

This crate helps expose Rust code via FFI to other languages, particularly C, by providing an attribute #[ffi] which automatically implements call forwarding from C-compatible function pointers to Rust impl methods.

This is particularly helpful when writing a shared libary in Rust which may be dlopen-ed by a C program like QEMU.

Example

In this example, imagine run_callback is in a C library you don't own. However, you want to use the common userdata parameter of callback-registering functions to call through to your struct instance. ffi allows you to export your impl's methods as C FFI compatible functions so you can easily call back and forth between languages.

ffi makes no assumptions about the parameter ordering of the callback types the C code calling your Rust code expects, so it makes it easy to customize the generation for your needs. It also provides utilities for automatically deriving conversions from raw pointers like From<*mut T> for &mut Foo.

use ffi::ffi;

extern "C" fn run_callback(
    callback: extern "C" fn(*mut std::ffi::c_void, i32, i32, i32) -> i32,
    data: *mut std::ffi::c_void,
) -> i32 {
    callback(data, 1, 2, 3)
}

extern "C" fn run_callback_reverse(
    callback: extern "C" fn(i32, i32, i32, *mut std::ffi::c_void) -> i32,
    data: *mut std::ffi::c_void,
) -> i32 {
    callback(1, 2, 3, data)
}


#[derive(Debug, Clone, PartialEq, Eq)]
struct Vec3 {
    x: i32,
    y: i32,
    z: i32,
}

#[ffi(from_ptr, self_ty = "*mut std::ffi::c_void")]
impl Vec3 {
    #[ffi(arg(self), arg(rest))]
    fn add(&mut self, x: i32, y: i32, z: i32) -> i32 {
        self.x += x;
        self.y += y;
        self.z += z;
        self.x + self.y + self.z
    }

    #[ffi(arg(rest), arg(self))]
    fn add_reverse_args(&mut self, x: i32, y: i32, z: i32) -> i32 {
        self.add(x, y, z)
    }
}

fn main() {
    let mut v = Vec3 { x: 1, y: 2, z: 3 };

    run_callback(vec3::add, &mut v as *mut Vec3 as *mut _);

    assert_eq!(v, Vec3 { x: 2, y: 4, z: 6 })

    run_callback_reverse(vec3::add_reverse_args, &mut v as *mut Vec3 as *mut _);

    assert_eq!(v, Vec3 { x: 3, y: 6, z: 9});
}

Adding ffi2 macro(s) as a dependency

Adding `ffi2` macro(s) as a dependency