A crate to make working with FFI code easier.
This is the open-source version of a utility crate we use at work. The original purpose was to make it easier for Rust modules (DLLs) to integrate with our main GUI application. We found it to be particularly elegant and robust to use, so thought it'd be a nice thing to share with the world.
This tries to give you a set of abstractions upon which safe APIs can be built. It tries to deal with several issues commonly encountered when writing FFI code.
Error handling is done via a private thread-local
LAST_ERROR variable which
lets you indicate a error using a similar mechanism to
The idea is if a Rust function returns a
Result::Err(_), it'll pass that
LAST_ERROR and then return an obviously wrong value (e.g.
0). The caller then checks for this return and can inspect
for more information.
A macro is provided to let you inspect
LAST_ERROR from C.
null_pointer_check!() macro will check whether some nullable thing is
null, if so it'll bail with an erroneous return value (
null for functions
returning pointers or
0 for integers) and set the
LAST_ERROR to indicate
a null pointer was encountered.
We use a
Nullable trait to represent anything which has some sort of
"obviously invalid" value (e.g.
null_pointer_check!() then lets you check whether a particular thing is
invalid, setting the
LAST_ERROR, and returning early from the current function
In practice, this turns out to make handling the possibility of invalid input quite ergonomic.
unsafe extern "C"
Exception safety becomes a concern when a bit of Rust code panics and tries to unwind across the FFI barrier. At the moment this will abort the program and, while no longer straight up Undefined Behaviour, this is still a massive pain to work around.
There is a
catch_panic() function that lets you execute some code and will
catch any unwinding, updating the
LAST_ERROR appropriately. The
catch_panic!() macro makes this a little easier and works with the
trait so you can bail out of a function, returning an error (
Splitting a Closure Into Data and Code
It's quite common for FFI functions that work with callbacks to accept an
void *user_data argument pointing to any extra state the user
may want to use. It doesn't allow the programmer to use
split_closure() function can be used to "split" a pointer to a closure
into a pointer to its data and an
unsafe extern "C" fn() which can be used
as a callback.
Rust closures are implemented by generating a custom type to contain any
captured state, and an impl for
function works by casting the closure pointer to
void * (this is our data)
and defining a trampoline function which will cast the data back and invoke
It's essentially a generalisation of this:
The Task API helps handle the tricky concurrency issues you encounter when running a job on a background thread and then trying to expose this to C, while maintaining memory- and thread-safety.
Task trait itself is quite simple:
You then generate the bindings via the
export_task!() macro. This will declare
extern "C" functions for spawning the
Task on a background thread,
periodically checking whether it's done, allowing you to cancel the task, then
retrieve the result and clean everything up properly afterwards.
This is probably the crate's killer feature as it lets you to painlessly run Rust tasks in the background, allowing you to integrate it into a larger application/GUI.
It is highly recommended to visit the
task module's docs for a more detailed