Struct abi_stable::library::LibHeader

#[repr(C)]
pub struct LibHeader { /* private fields */ }

Used to check the layout of modules returned by module-loading functions exported by dynamic libraries.

Module-loading functions are declared with the export_root_module attribute.

Implementations

impl LibHeader

pub const unsafe fn from_constructor<M>( constructor: extern "C" fn() -> RootModuleResult, check_layout: CheckTypeLayout, ) -> Self

where M: RootModule,

Constructs a LibHeader from the root module loader.

Safety

The PrefixRef<ErasedPrefix> returned by the constructor function must have been transmuted from a PrefixRef<M>.

pub fn from_module<M>(value: M) -> Self

where M: RootModule,

Constructs a LibHeader from the module.

pub const fn root_mod_consts(&self) -> &RootModuleConsts

All the important constants of a RootModule for some erased type.

pub const fn version_strings(&self) -> VersionStrings

The version string of the library the module is being loaded from.

pub const fn layout(&self) -> Option<&'static TypeLayout>

Gets the layout of the root module.

This returns a None if the root module layout is not included because the #[unsafe_no_layout_constant] helper attribute was used on the function exporting the root module.

pub fn init_root_module<M>(&self) -> Result<M, LibraryError>

where M: RootModule,

Checks that the library is compatible, returning the root module on success.

It checks that these are compatible:

• The version number of the library

• The layout of the root module.

Warning

If this function is called within a dynamic library, it must be called at or after the function that exports its root module is 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 returns these errors:

• 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.

pub unsafe fn init_root_module_with_unchecked_layout<M>( &self, ) -> Result<M, LibraryError>

where M: RootModule,

Checks that the version number of the library is compatible, returning the root module on success.

This function transmutes the root module type, without checking that the layout is compatible first.

Warning

If this function is called within a dynamic library, it must be called at or after the function that exports its root module is 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.

Safety

The caller must ensure that M has the expected layout.

Errors

This returns these errors:

• 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::RootModule : If the root module initializer returned an error or panicked.

pub fn ensure_layout<M>(&self) -> Result<(), LibraryError>

where M: RootModule,

Checks that the layout of the M root module from the dynamic library is compatible with the expected layout.

Errors

This returns these errors:

• 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.

pub fn check_layout<M>(&self) -> Result<M, LibraryError>

where M: RootModule,

Gets the root module,first checking that the layout of the M from the dynamic library is compatible with the expected layout.

Errors

This returns these errors:

• 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.

pub unsafe fn unchecked_layout<M>(&self) -> Result<M, RootModuleError>

where M: PrefixRefTrait,

Gets the root module without checking that the layout of M is the expected one. This is effectively a transmute.

This is useful if a user keeps a cache of which dynamic libraries have been checked for layout compatibility.

Safety

The caller must ensure that M has the expected layout.

Errors

This function can return a RootModuleError because the root module failed to initialize.

Trait Implementations

impl GetStaticEquivalent_ for LibHeader

type StaticEquivalent = _static_LibHeader

The 'static equivalent of Self

impl StableAbi for LibHeader

type IsNonZeroType = False

Whether this type has a single invalid bit-pattern.

const LAYOUT: &'static TypeLayout = _

The layout of the type provided by implementors.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.