Macro ffi_support::define_string_destructor

macro_rules! define_string_destructor {
    ($mylib_destroy_string:ident) => { ... };
}

For a number of reasons (name collisions are a big one, but, it also wouldn’t work on all platforms), we cannot export extern "C" functions from this library. However, it’s pretty common to want to free strings allocated by rust, so many libraries will need this, so we provide it as a macro.

It simply expands to a #[no_mangle] pub unsafe extern "C" fn which wraps this crate’s [destroy_c_string] function.

Caveats

If you’re using multiple separately compiled rust libraries in your application, it’s critical that you are careful to only ever free strings allocated by a Rust library using the same rust library. Passing them to a different Rust library’s string destructor will cause you to corrupt multiple heaps.

Additionally, be sure that all strings you pass to this were actually allocated by rust. It’s a common issue for JNA code to transparently convert Pointers to things to Strings behind the scenes, which is quite risky here. (To avoid this in JNA, only use String for passing read-only strings into Rust, e.g. it’s for passing *const c_char. All other uses should use Pointer and getString()).

Finally, to avoid name collisions, it is strongly recommended that you provide an name for this function unique to your library.

Example

define_string_destructor!(mylib_destroy_string);