Trait LibraryAPI

pub trait LibraryAPI<'interface> {
    // Required methods
    fn register_loader<'loader, LT, L>(
        &mut self,
        loader: &'loader LT,
        lib_type: &impl AsRef<str>,
    ) -> Result<Loader<'interface, Owned>, Error>
       where L: LibraryLoaderAPI<'static>,
             LibraryLoader<L, Owned>: From<&'loader LT>;
    fn unregister_loader(
        &mut self,
        loader: Loader<'_, Owned>,
    ) -> Result<(), Error>;
    fn get_loader_interface<'loader, O, L>(
        &mut self,
        loader: &Loader<'loader, O>,
    ) -> Result<LibraryLoader<L, O>, Error>
       where O: ImmutableAccessIdentifier,
             L: LibraryLoaderAPI<'loader> + LibraryLoaderABICompat;
    fn get_loader_handle_from_type(
        &self,
        lib_type: &impl AsRef<str>,
    ) -> Result<Loader<'interface, BorrowMutable<'_>>, Error>;
    fn get_loader_handle_from_library<'library, O>(
        &self,
        library: &Library<'library, O>,
    ) -> Result<Loader<'library, BorrowMutable<'_>>, Error>
       where O: ImmutableAccessIdentifier;
    fn get_num_loaders(&self) -> usize;
    fn library_exists<'library, O>(
        &self,
        library: &Library<'library, O>,
    ) -> bool
       where O: ImmutableAccessIdentifier;
    fn type_exists(&self, lib_type: &impl AsRef<str>) -> Result<bool, Error>;
    fn get_library_types(
        &self,
        buffer: impl AsMut<[LibraryType]>,
    ) -> Result<usize, Error>;
    unsafe fn create_library_handle(&mut self) -> Library<'interface, Owned>;
    unsafe fn remove_library_handle(
        &mut self,
        library: Library<'_, Owned>,
    ) -> Result<(), Error>;
    unsafe fn link_library<'library, 'loader, O, LO, IO>(
        &mut self,
        library: &Library<'library, O>,
        loader: &Loader<'loader, LO>,
        internal: &InternalLibrary<IO>,
    ) -> Result<(), Error>
       where O: MutableAccessIdentifier,
             LO: ImmutableAccessIdentifier,
             IO: ImmutableAccessIdentifier,
             'loader: 'library;
    fn get_internal_library_handle<'library, O>(
        &self,
        library: &Library<'library, O>,
    ) -> Result<InternalLibrary<O>, Error>
       where O: ImmutableAccessIdentifier;
    fn load<O>(
        &mut self,
        loader: &Loader<'interface, O>,
        path: &impl AsRef<Path>,
    ) -> Result<Library<'interface, Owned>, Error>
       where O: MutableAccessIdentifier;
    fn unload(&mut self, library: Library<'_, Owned>) -> Result<(), Error>;
    fn get_data_symbol<'library, 'handle, O, U>(
        &self,
        library: &'handle Library<'library, O>,
        symbol: &impl AsRef<CStr>,
        caster: impl FnOnce(NonNullConst<c_void>) -> &'library U,
    ) -> Result<Symbol<'handle, &'library U>, Error>
       where O: ImmutableAccessIdentifier;
    fn get_function_symbol<'library, 'handle, O, U>(
        &self,
        library: &'handle Library<'library, O>,
        symbol: &impl AsRef<CStr>,
        caster: impl FnOnce(CBaseFn) -> U,
    ) -> Result<Symbol<'handle, U>, Error>
       where O: ImmutableAccessIdentifier;
}

Idiomatic library api.

Required Methods

fn register_loader<'loader, LT, L>( &mut self, loader: &'loader LT, lib_type: &impl AsRef<str>, ) -> Result<Loader<'interface, Owned>, Error>

where L: LibraryLoaderAPI<'static>, LibraryLoader<L, Owned>: From<&'loader LT>,

Registers a new loader.

The loader can load libraries of the type lib_type. The loader must outlive the binding to the interface.

Failure

The function fails if the library type already exists.

Return

Handle on success, error otherwise.

fn unregister_loader(&mut self, loader: Loader<'_, Owned>) -> Result<(), Error>

Unregisters an existing loader.

Failure

The function fails if loader is invalid.

Return

Error on failure.

fn get_loader_interface<'loader, O, L>( &mut self, loader: &Loader<'loader, O>, ) -> Result<LibraryLoader<L, O>, Error>

where O: ImmutableAccessIdentifier, L: LibraryLoaderAPI<'loader> + LibraryLoaderABICompat,

Fetches the interface of a library loader.

Failure

The function fails if loader is invalid.

Return

Interface on success, error otherwise.

fn get_loader_handle_from_type( &self, lib_type: &impl AsRef<str>, ) -> Result<Loader<'interface, BorrowMutable<'_>>, Error>

Fetches the loader handle associated with the library type.

Failure

The function fails if lib_type is not registered.

Return

Handle on success, error otherwise.

fn get_loader_handle_from_library<'library, O>( &self, library: &Library<'library, O>, ) -> Result<Loader<'library, BorrowMutable<'_>>, Error>

where O: ImmutableAccessIdentifier,

Fetches the loader handle linked with the library handle.

Failure

The function fails if library is invalid.

Return

Handle on success, error otherwise.

fn get_num_loaders(&self) -> usize

Fetches the number of registered loaders.

Return

Number of registered loaders.

fn library_exists<'library, O>(&self, library: &Library<'library, O>) -> bool

where O: ImmutableAccessIdentifier,

Checks if a the library handle is valid.

Return

true if the handle is valid, false otherwise.

fn type_exists(&self, lib_type: &impl AsRef<str>) -> Result<bool, Error>

Checks if a library type exists.

Return

true if the type exists, false otherwise.

fn get_library_types( &self, buffer: impl AsMut<[LibraryType]>, ) -> Result<usize, Error>

Copies the strings of the registered library types into a buffer.

Failure

The function fails if buffer.as_ref().len() < get_num_loaders().

Return

Number of written types on success, error otherwise.

unsafe fn create_library_handle(&mut self) -> Library<'interface, Owned>

Creates a new unlinked library handle.

Return

Library handle.

Safety

The handle must be linked before use.

unsafe fn remove_library_handle( &mut self, library: Library<'_, Owned>, ) -> Result<(), Error>

Removes an existing library handle.

Failure

The function fails if library is invalid.

Return

Error on failure.

Safety

Removing the handle does not unload the library.

unsafe fn link_library<'library, 'loader, O, LO, IO>( &mut self, library: &Library<'library, O>, loader: &Loader<'loader, LO>, internal: &InternalLibrary<IO>, ) -> Result<(), Error>

where O: MutableAccessIdentifier, LO: ImmutableAccessIdentifier, IO: ImmutableAccessIdentifier, 'loader: 'library,

Links a library handle to an internal library handle.

Overrides the internal link of the library handle by setting it to the new library loader and internal handle.

Failure

The function fails if library or loader are invalid.

Return

Error on failure.

Safety

Incorrect usage can lead to dangling handles or use-after-free errors.

fn get_internal_library_handle<'library, O>( &self, library: &Library<'library, O>, ) -> Result<InternalLibrary<O>, Error>

where O: ImmutableAccessIdentifier,

Fetches the internal handle linked with the library handle.

Failure

The function fails if handle is invalid.

Return

Handle on success, error otherwise.

fn load<O>( &mut self, loader: &Loader<'interface, O>, path: &impl AsRef<Path>, ) -> Result<Library<'interface, Owned>, Error>

where O: MutableAccessIdentifier,

Loads a library. The resulting handle is unique.

Failure

The function fails if loader or path is invalid or the type of the library can not be loaded with the loader.

Return

Handle on success, error otherwise.

fn unload(&mut self, library: Library<'_, Owned>) -> Result<(), Error>

Unloads a library.

Failure

The function fails if library is invalid.

Return

Error on failure.

fn get_data_symbol<'library, 'handle, O, U>( &self, library: &'handle Library<'library, O>, symbol: &impl AsRef<CStr>, caster: impl FnOnce(NonNullConst<c_void>) -> &'library U, ) -> Result<Symbol<'handle, &'library U>, Error>

where O: ImmutableAccessIdentifier,

Fetches a data symbol from a library.

Failure

The function fails if library is invalid or library does not contain symbol.

Note

Some platforms may differentiate between a function-pointer and a data-pointer. See LibraryAPI::get_function_symbol() for fetching a function.

Return

Symbol on success, error otherwise.

fn get_function_symbol<'library, 'handle, O, U>( &self, library: &'handle Library<'library, O>, symbol: &impl AsRef<CStr>, caster: impl FnOnce(CBaseFn) -> U, ) -> Result<Symbol<'handle, U>, Error>

where O: ImmutableAccessIdentifier,

Fetches a function symbol from a library.

Failure

The function fails if library is invalid or library does not contain symbol.

Note

Some platforms may differentiate between a function-pointer and a data-pointer. See LibraryAPI::get_data_symbol() for fetching some data.

Return

Symbol on success, error otherwise.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'interface, T> LibraryAPI<'interface> for T

where T: LibraryBinding,