[−][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 String
s, 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.