Storing C callbacks in Rust

help
6

Although Rust is a great language for FFI, it is a very unsafe thing to do, leading very easily to UB.

When doing so, I always use the following

FFI safety belt

  • any pointer from the C world becomes Option<NonNull<_>>, (or Option<unsafe extern "C" fn (...) -> ... > for function pointers);

    • this tackles C code being able to feed NULLs at will, forcing the Rust code to handle them;

  • use ::libc::c_void to represent C's void. Thus void * becomes Option<NonNull<::libc::c_void>>;

  • even though panic = "abort" is a setting that can be added to Cargo.toml compilation profile, I prefer to have such a guard within the exported code;

  • structs and enums should be #[repr(C)] (or #[repr(transparent)] for newtypes)

  • if receiving an enum from C / FFI, it should be of integer type. If it isn't, it should be instantly transmuted into an integer and then matched against integer values to get a Rust enum back.

    • this includes booleans:
      let rust_bool: bool = mem::transmute<_, i32>(c_bool) != 0;

  • do not use static muts, not even for FFI; you should use

    • lazy_static! with RwLocks when in doubt,

    • thread_local!s with RefCells for single-threaded programs,

    • or, if you really wanna go down the unsafe path, a static UnsafeSyncCell<_>:

      #[repr(transparent)]
pub
struct UnsafeSyncCell<T> (pub UnsafeCell<T>);

unsafe impl<T> Sync for UnsafeSyncCell<T> {}

static MY_STATIC_MUT: UnsafeSyncCell< u8 > = UnsafeSyncCell(UnsafeCell::new(0));

// above is still better than:
static mut MY_STATIC_MUT: u8 = 0; // DO NOT DO THIS

Example: registering callbacks in a single-threaded context

Rust FFI library (crate-type = ["cdylib"] or crate-type = ["staticlib"])

use ::std::{*,
    cell::RefCell,
    ptr::NonNull,
};
use ::libc::c_void; // libc = "0.2.51"

macro_rules! ffi_panic_boundary {($($tt:tt)*) => (
    // /* or */ { ::scopeguard::defer_on_unwind(process::abort()); $($tt)* }
    match ::std::panic::catch_unwind!(|| {$($tt)*}) {//
        | Ok(ret) => ret,
        | Err(_) => {
            // /* or */ return RUST_ERR_PANICKED;
            eprintln!("Rust panicked; aborting process");
            ::std::process::abort() 
        },
    }
)}

type Arg = NonNull<c_void>;

type Callback = unsafe extern "C" fn (mb_arg: Option<Arg>);

thread_local! {
    static CALLBACKS: RefCell<
        Vec< (Callback, Option<Arg>) >
    > = RefCell::new(Vec::new());
}
// or lazy_static! with a RwLock

#[allow(non_camel_case_types)]
#[repr(C)]
pub
enum e_rust_status {
    RUST_OK = 0,
    RUST_ERR_NULL_POINTER,
    // RUST_ERR_PANICKED,
}
use self::e_rust_status::*;

macro_rules! unwrap_pointer {($pointer:expr) => (
    match $pointer {//
        | Some(non_null_pointer) => non_null_pointer,
        | None => return RUST_ERR_NULL_POINTER,
    }
)}

#[no_mangle] pub extern "C"
fn register_cb (
    cb: Option<Callback>,
    arg: Option<Arg>,
) -> e_rust_status
{
    ffi_panic_boundary! {
        let cb = unwrap_pointer!(cb);
        CALLBACKS.with(|slf| { slf
            .borrow_mut()
            .push((cb, arg))
        });
        RUST_OK
    }
}

#[no_mangle] pub unsafe extern "C"
fn call_cbs () -> e_rust_status
{
    ffi_panic_boundary! {
        CALLBACKS.with(|slf| { slf
            .borrow_mut()
            .iter_mut()
            .for_each(|&mut (cb, arg): &mut (Callback, Option<Arg>)| {
                cb(arg);
            })
        });
        RUST_OK
    }
}

#[no_mangle] pub extern "C"
fn clear_cbs () -> e_rust_status
{
    ffi_panic_boundary! {
        CALLBACKS.with(|slf| {
            let mut cbs = slf.borrow_mut();
            cbs.clear();
            cbs.shrink_to_fit();
        });
        RUST_OK
    }
}

Rust FFI library header

#ifndef __RUST_LIB_H__
#define __RUST_LIB_H__

typedef enum rust_status {
    RUST_OK = 0,
    RUST_ERR_NULL_POINTER,
} e_rust_status;

typedef void (*cb_t) (void *);

extern e_rust_status register_cb (cb_t cb, void * arg);

extern e_rust_status call_cbs (void);

extern e_rust_status clear_cbs (void);

#endif //__RUST_LIB_H__

(you can use cbindgen for this step, although it does not like Options (rightfully so: Rust non-C enums layout is undefined))

User of the library: example C code

#include <stdio.h>
#include <stdlib.h>
#include "rust_lib.h"

void rust_try (e_rust_status rust_status)
{
    switch (rust_status) {
        case RUST_OK:
            return;
        case RUST_ERR_NULL_POINTER:
            fprintf(stderr, "Rust call failed: got NULL pointer\n");
            break;
        default:
            fprintf(stderr, "Rust call returned an unknown value\n");
            break;
    }
    exit(EXIT_FAILURE);
}

void inc (int * counter)
{
    ++(*counter);
}

int main (int argc, char const * const argv[])
{
    int counter = 0;
    {
        rust_try(register_cb((cb_t) inc, &counter));
        rust_try(register_cb((cb_t) inc, &counter));
        rust_try(register_cb((cb_t) inc, &counter));
        printf("%d\n", counter);
        rust_try(call_cbs());
        printf("%d\n", counter);
        rust_try(clear_cbs());
    }
    return EXIT_SUCCESS;
}
10 Likes