[][src]Attribute Macro ffishim_derive::ffishim_function

#[ffishim_function]

Mark a function for use across the ffi boundary.

This procedural macro will generate a stub called ffi_my_function. This function features the same arguments as my_function, which it wraps. It will convert any arguments from the FFIMyStruct version passed by the caller to the native MyStruct version. If there is any return value, it will convert it from its native version back into the ffi one.

You should never have to call or manipulate ffi_my_function from the rust side. It will systematically return our C-ABI equivalent of a Result, even if the original my_function does not return Result itself. This is because the ffi->native type translation can fail, and we need an elegant way to report that (panicking in such a setup is often inacceptable.)

Take a look at which basic/built-in types you can use here. You can also use any structure which derive the FFIShim procedural macro.

C ABI Violation: passing structs by value

Any structure passed by value in my_function will instead be hidden behind a pointer. This is because Dart's alpha ffi does not support passing structures by value, and this project was originally written to work with it.

Performance implications

By "type conversions", we mean calling the given structures' from and try_into implementations. For scalar types for example, that's a simple mov. For Strings, it most likely means a malloc and a memcpy. For complex structures, it is a recursive conversion of all types and sub-types.

These conversions can quickly become non-trivial, which is why we encourage the user to try to reduce amount of calls and data passed through those calls to the minimum required. If you don't really need a field across the ffi barrier, consider making it opaque.