Attribute Macro abi_stable::export_root_module

source · 
#[export_root_module]
Expand description

This attribute is used for functions which export a module in an implementation crate.

This is applied to functions like this:


use abi_stable::prefix_type::PrefixTypeTrait;

#[abi_stable::export_root_module]
pub fn get_hello_world_mod() -> TextOperationsMod_Ref {
    TextOperationsMod { reverse_string }.leak_into_prefix()
}

Return Type

The return type of the annotated function can be one of:

  • Any type that implements abi_stable::library::RootModule

  • Result<M, RBoxError>, where M is any type that implements abi_stable::library::RootModule

  • RResult<M, RBoxError>, where M is any type that implements abi_stable::library::RootModule

All those types are supported through the IntoRootModuleResult trait, which you can implement if you want to return some other type.

Generated code

Exporting the root module creates a static THE_NAME_USED_FOR_ALL_ROOT_MODULES: LibHeader = ... ; with these things:

  • The version of abi_stable used.

  • A #[no_mangle] function that wraps the annotated root-module constructor function, converting the return value to RootModuleResult.

  • The type layout of the root module, for checking that the types are compatible with whatever loads that library.

  • The version number of the library.

  • A LateStaticRef of the root module.

The name used for generated static is the value of abi_stable::library::ROOT_MODULE_LOADER_NAME.

Remove type layout constant

One can avoid generating the type layout constant for the exported root module by using the #[unsafe_no_layout_constant] attribute, with the downside that if the layout changes(in an incompatible way) it could be Undefined Behavior.

This attribute is useful if one wants to minimize the size of the dynamic library when doing a public release.

This attribute should not be used unconditionally, it should be disabled in Continuous Integration so that the binary compatibility of a dynamic library is checked at some point before releasing it.

More examples

For a more detailed example look in the README in the repository for this crate.