Trait abi_stable::library::RootModule

pub trait RootModule:
    Sized
    + StableAbi
    + PrefixRefTrait
    + 'static {
    const BASE_NAME: &'static str;
    const NAME: &'static str;
    const VERSION_STRINGS: VersionStrings;
    const CONSTANTS: RootModuleConsts = _;
    const CONSTANTS_NO_ABI_INFO: RootModuleConsts = _;

    // Required method
    fn root_module_statics() -> &'static RootModuleStatics<Self>;

    // Provided methods
    fn get_module() -> Option<Self> { ... }
    fn get_raw_library() -> Option<&'static RawLibrary> { ... }
    fn get_library_path(directory: &Path) -> PathBuf { ... }
    fn load_module_with<F, E>(f: F) -> Result<Self, E>
       where F: FnOnce() -> Result<Self, E> { ... }
    fn load_from(where_: LibraryPath<'_>) -> Result<Self, LibraryError> { ... }
    fn load_from_directory(where_: &Path) -> Result<Self, LibraryError> { ... }
    fn load_from_file(path_: &Path) -> Result<Self, LibraryError> { ... }
    fn initialization(self) -> Result<Self, LibraryError> { ... }
}

The root module of a dynamic library, which may contain other modules,function pointers,and static references.

Examples

For a more in-context example of a type implementing this trait you can look at either the example in the readme for this crate, or the example/example_*_interface crates in this crates’ repository .

Basic

use abi_stable::{library::RootModule, sabi_types::VersionStrings, StableAbi};

#[repr(C)]
#[derive(StableAbi)]
#[sabi(kind(Prefix(prefix_ref = Module_Ref, prefix_fields = Module_Prefix)))]
pub struct Module {
    pub first: u8,
    // The `#[sabi(last_prefix_field)]` attribute here means that this is
    // the last field in this module that was defined in the
    // first compatible version of the library,
    #[sabi(last_prefix_field)]
    pub second: u16,
    pub third: u32,
}
impl RootModule for Module_Ref {
    abi_stable::declare_root_module_statics! {Module_Ref}
    const BASE_NAME: &'static str = "example_root_module";
    const NAME: &'static str = "example_root_module";
    const VERSION_STRINGS: VersionStrings = abi_stable::package_version_strings!();
}

Required Associated Constants

const BASE_NAME: &'static str

The name of the dynamic library,which is the same on all platforms. This is generally the name of the implementation crate.

const NAME: &'static str

The name of the library used in error messages.

const VERSION_STRINGS: VersionStrings

The version number of the library that this is a root module of.

Initialize this with package_version_strings!()

Provided Associated Constants

const CONSTANTS: RootModuleConsts = _

All the constants of this trait and supertraits.

It can safely be used as a proxy for the associated constants of this trait.

const CONSTANTS_NO_ABI_INFO: RootModuleConsts = _

Like Self::CONSTANTS, except without including the type layout constant for the root module.

Required Methods

fn root_module_statics() -> &'static RootModuleStatics<Self>

Gets the statics for Self.

To define this associated function use: abi_stable::declare_root_module_statics!{TypeOfSelf} . Passing Self instead of TypeOfSelf won’t work.

Provided Methods

fn get_module() -> Option<Self>

Gets the root module,returning None if the module is not yet loaded.

fn get_raw_library() -> Option<&'static RawLibrary>

Gets the RawLibrary of the module, returning None if the dynamic library failed to load (it doesn’t exist or layout checking failed).

Note that if the root module is initialized using Self::load_module_with, this will return None even though Self::get_module does not.

fn get_library_path(directory: &Path) -> PathBuf

Returns the path the library would be loaded from,given a directory(folder).

fn load_module_with<F, E>(f: F) -> Result<Self, E>

where F: FnOnce() -> Result<Self, E>,

Loads the root module,with a closure which either returns the root module or an error.

If the root module was already loaded, this will return the already loaded root module, without calling the closure.

fn load_from(where_: LibraryPath<'_>) -> Result<Self, LibraryError>

Loads this module from the path specified by where_, first loading the dynamic library if it wasn’t already loaded.

Once the root module is loaded, this will return the already loaded root module.

Warning

If this function is called within a dynamic library, it must be called either within the root module loader function or after that function has been called.

DO NOT call this in the static initializer of a dynamic library, since this library relies on setting up its global state before calling the root module loader.

Errors

This will return these errors:

• LibraryError::OpenError: If the dynamic library itself could not be loaded.

• LibraryError::GetSymbolError: If the root module was not exported.

• LibraryError::InvalidAbiHeader: If the abi_stable version used by the library is not compatible.

• LibraryError::ParseVersionError: If the version strings in the library can’t be parsed as version numbers, this can only happen if the version strings are manually constructed.

• LibraryError::IncompatibleVersionNumber: If the version number of the library is incompatible.

• LibraryError::AbiInstability: If the layout of the root module is not the expected one.

• LibraryError::RootModule : If the root module initializer returned an error or panicked.

fn load_from_directory(where_: &Path) -> Result<Self, LibraryError>

Loads this module from the directory specified by where_, first loading the dynamic library if it wasn’t already loaded.

Once the root module is loaded, this will return the already loaded root module.

Warnings and Errors are detailed in load_from,

fn load_from_file(path_: &Path) -> Result<Self, LibraryError>

Loads this module from the file at path_, first loading the dynamic library if it wasn’t already loaded.

Once the root module is loaded, this will return the already loaded root module.

Warnings and Errors are detailed in load_from,

fn initialization(self) -> Result<Self, LibraryError>

Defines behavior that happens once the module is loaded.

This is ran in the RootModule::load* associated functions after the root module has succesfully been loaded.

The default implementation does nothing.

Object Safety

This trait is not object safe.

Implementors

impl RootModule for Module_Ref

const BASE_NAME: &'static str = "example_root_module"

const NAME: &'static str = "example_root_module"

const VERSION_STRINGS: VersionStrings = _