Trait ModuleAPI

pub trait ModuleAPI<'interface> {
    // Required methods
    fn register_loader<'loader, LT, L>(
        &mut self,
        loader: &'loader LT,
        mod_type: &impl AsRef<str>,
    ) -> Result<Loader<'interface, Owned>, Error>
       where L: ModuleLoaderAPI<'static>,
             ModuleLoader<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<ModuleLoader<L, O>, Error>
       where O: ImmutableAccessIdentifier,
             L: ModuleLoaderAPI<'loader> + ModuleLoaderABICompat;
    fn get_loader_handle_from_type(
        &self,
        mod_type: &impl AsRef<str>,
    ) -> Result<Loader<'interface, BorrowMutable<'_>>, Error>;
    fn get_loader_handle_from_module<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<Loader<'module, BorrowMutable<'_>>, Error>
       where O: ImmutableAccessIdentifier;
    fn get_num_modules(&self) -> usize;
    fn get_num_loaders(&self) -> usize;
    fn get_num_exported_interfaces(&self) -> usize;
    fn module_exists<'module, O>(&self, module: &Module<'module, O>) -> bool
       where O: ImmutableAccessIdentifier;
    fn type_exists(&self, mod_type: &impl AsRef<str>) -> Result<bool, Error>;
    fn exported_interface_exists(&self, interface: &InterfaceDescriptor) -> bool;
    fn get_modules(
        &self,
        buffer: &mut impl AsMut<[ModuleInfo]>,
    ) -> Result<usize, Error>;
    fn get_module_types(
        &self,
        buffer: &mut impl AsMut<[ModuleType]>,
    ) -> Result<usize, Error>;
    fn get_exported_interfaces(
        &self,
        buffer: &mut impl AsMut<[InterfaceDescriptor]>,
    ) -> Result<usize, Error>;
    fn get_exported_interface_handle(
        &self,
        interface: &InterfaceDescriptor,
    ) -> Result<Module<'interface, BorrowImmutable<'_>>, Error>;
    unsafe fn create_module_handle(&mut self) -> Module<'interface, Owned>;
    unsafe fn remove_module_handle(
        &mut self,
        module: Module<'_, Owned>,
    ) -> Result<(), Error>;
    unsafe fn link_module<'module, 'loader, O, LO, IO>(
        &mut self,
        module: &Module<'module, O>,
        loader: &Loader<'loader, LO>,
        internal: &InternalModule<IO>,
    ) -> Result<(), Error>
       where O: MutableAccessIdentifier,
             LO: ImmutableAccessIdentifier,
             IO: ImmutableAccessIdentifier,
             'loader: 'module;
    fn get_internal_module_handle<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<InternalModule<O>, Error>
       where O: ImmutableAccessIdentifier;
    fn add_module<O>(
        &mut self,
        loader: &Loader<'interface, O>,
        path: &impl AsRef<Path>,
    ) -> Result<Module<'interface, Owned>, Error>
       where O: MutableAccessIdentifier;
    fn remove_module(&mut self, module: Module<'_, Owned>) -> Result<(), Error>;
    fn load<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn unload<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn initialize<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn terminate<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn add_dependency<O>(
        &mut self,
        module: &mut Module<'_, O>,
        interface: &InterfaceDescriptor,
    ) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn remove_dependency<O>(
        &mut self,
        module: &mut Module<'_, O>,
        interface: &InterfaceDescriptor,
    ) -> Result<(), Error>
       where O: MutableAccessIdentifier;
    fn export_interface<O>(
        &mut self,
        module: &Module<'_, O>,
        interface: &InterfaceDescriptor,
    ) -> Result<(), Error>
       where O: ImmutableAccessIdentifier;
    fn get_load_dependencies<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<&'module [InterfaceDescriptor], Error>
       where O: ImmutableAccessIdentifier;
    fn get_runtime_dependencies<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<&'module [InterfaceDescriptor], Error>
       where O: ImmutableAccessIdentifier;
    fn get_exportable_interfaces<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<&'module [InterfaceDescriptor], Error>
       where O: ImmutableAccessIdentifier;
    fn fetch_status<O>(
        &self,
        module: &Module<'_, O>,
    ) -> Result<ModuleStatus, Error>
       where O: ImmutableAccessIdentifier;
    fn get_module_path<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<&'module [OSPathChar], Error>
       where O: ImmutableAccessIdentifier;
    fn get_module_info<'module, O>(
        &self,
        module: &Module<'module, O>,
    ) -> Result<&'module ModuleInfo, Error>
       where O: ImmutableAccessIdentifier;
    fn get_interface<'module, O, T>(
        &self,
        module: &'module Module<'_, O>,
        interface: &InterfaceDescriptor,
        caster: impl FnOnce(Interface) -> T,
    ) -> Result<Interface<'module, T>, Error>
       where O: ImmutableAccessIdentifier;
}

Idiomatic module api.

Required Methods

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

where L: ModuleLoaderAPI<'static>, ModuleLoader<L, Owned>: From<&'loader LT>,

Registers a new module loader.

Module types starting with __ are reserved for future use.

Failure

The function fails if mod_type already exists.

Return

Handle on success, error otherwise.

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

Unregisters an existing module loader.

Unregistering a module loader also unloads the modules it loaded.

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<ModuleLoader<L, O>, Error>

where O: ImmutableAccessIdentifier, L: ModuleLoaderAPI<'loader> + ModuleLoaderABICompat,

Fetches the interface of a module loader.

Failure

The function fails if loader is invalid.

Return

Interface on success, error otherwise.

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

Fetches the handle of the loader associated with a module type.

Failure

The function fails if mod_type does not exist.

Return

Handle on success, error otherwise.

fn get_loader_handle_from_module<'module, O>( &self, module: &Module<'module, O>, ) -> Result<Loader<'module, BorrowMutable<'_>>, Error>

where O: ImmutableAccessIdentifier,

Fetches the handle of the loader linked with the module handle.

Failure

The function fails if module is invalid.

Return

Handle on success, error otherwise.

fn get_num_modules(&self) -> usize

Fetches the number of loaded modules.

Return

Number of modules.

fn get_num_loaders(&self) -> usize

Fetches the number of loaders.

Return

Number of module loaders.

fn get_num_exported_interfaces(&self) -> usize

Fetches the number of exported interfaces.

Return

Number of exported interfaces.

fn module_exists<'module, O>(&self, module: &Module<'module, O>) -> bool

where O: ImmutableAccessIdentifier,

Checks if a module exists.

Return

true if it exists, false otherwise.

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

Checks if a module type exists.

Return

true if it exists, false otherwise.

fn exported_interface_exists(&self, interface: &InterfaceDescriptor) -> bool

Checks whether an exported interface exists.

Return

true if it exists, false otherwise.

fn get_modules( &self, buffer: &mut impl AsMut<[ModuleInfo]>, ) -> Result<usize, Error>

Copies the available module info into a buffer.

Failure

Fails if buffer.as_ref().len() < get_num_modules().

Return

Number if written module info on success, error otherwise.

fn get_module_types( &self, buffer: &mut impl AsMut<[ModuleType]>, ) -> Result<usize, Error>

Copies the available module types into a buffer.

Failure

Fails if buffer.as_ref().len() < get_num_loaders().

Return

Number if written module types on success, error otherwise.

fn get_exported_interfaces( &self, buffer: &mut impl AsMut<[InterfaceDescriptor]>, ) -> Result<usize, Error>

Copies the descriptors of the exported interfaces into a buffer.

Failure

Fails if buffer.as_ref().len() < get_num_exported_interfaces().

Return

Number if written descriptors on success, error otherwise.

fn get_exported_interface_handle( &self, interface: &InterfaceDescriptor, ) -> Result<Module<'interface, BorrowImmutable<'_>>, Error>

Fetches the module handle of the exported interface.

Failure

Fails if interface does not exist.

Return

Module handle on success, error otherwise.

unsafe fn create_module_handle(&mut self) -> Module<'interface, Owned>

Creates a new unlinked module handle.

Return

Module handle.

Safety

The handle remains invalid until it’s linked with ModuleAPI::link_module.

unsafe fn remove_module_handle( &mut self, module: Module<'_, Owned>, ) -> Result<(), Error>

Links a module handle to an internal module handle.

Failure

Fails if module orloader are invalid.

Return

Error on failure.

Safety

Removing the handle does not unload the module.

unsafe fn link_module<'module, 'loader, O, LO, IO>( &mut self, module: &Module<'module, O>, loader: &Loader<'loader, LO>, internal: &InternalModule<IO>, ) -> Result<(), Error>

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

Links a module handle to an internal module handle.

Failure

Fails if module orloader are invalid.

Return

Error on failure.

Safety

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

fn get_internal_module_handle<'module, O>( &self, module: &Module<'module, O>, ) -> Result<InternalModule<O>, Error>

where O: ImmutableAccessIdentifier,

Fetches the internal handle linked with the module handle.

Failure

Fails if module is invalid.

Return

Internal handle on success, error otherwise.

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

where O: MutableAccessIdentifier,

Adds a new module.

Failure

Fails if loader or path is invalid or the type of the module can not be loaded with the loader.

Return

Module handle on success, error otherwise.

fn remove_module(&mut self, module: Module<'_, Owned>) -> Result<(), Error>

Removes a module.

Failure

Fails if module is invalid or the module is not in an unloaded state.

Return

Error on failure.

fn load<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>

where O: MutableAccessIdentifier,

Loads a module.

Failure

Fails if module is invalid, the load dependencies of the module are not exported or the module is not in an unloaded state.

Return

Error on failure.

fn unload<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>

where O: MutableAccessIdentifier,

Unloads a module.

Failure

Fails if module is invalid or the module is in an unloaded or ready state.

Return

Error on failure.

fn initialize<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>

where O: MutableAccessIdentifier,

Initializes a module.

Failure

Fails if module is invalid, the runtime dependencies of the module are not exported or the module is not in a loaded state.

Return

Error on failure.

fn terminate<O>(&mut self, module: &mut Module<'_, O>) -> Result<(), Error>

where O: MutableAccessIdentifier,

Terminates a module.

Terminating a module also removes the interfaces it exported. The modules that depend on the module are terminated. If they list the module as a load dependency, they are also unloaded.

Failure

Fails if module is invalid or the module is not in a ready state.

Return

Error on failure.

fn add_dependency<O>( &mut self, module: &mut Module<'_, O>, interface: &InterfaceDescriptor, ) -> Result<(), Error>

where O: MutableAccessIdentifier,

Registers a new runtime dependency of the module.

Failure

Fails if module is invalid.

Return

Error on failure.

fn remove_dependency<O>( &mut self, module: &mut Module<'_, O>, interface: &InterfaceDescriptor, ) -> Result<(), Error>

where O: MutableAccessIdentifier,

Removes an existing runtime dependency from the module.

Failure

Fails if module is invalid.

Return

Error on failure.

fn export_interface<O>( &mut self, module: &Module<'_, O>, interface: &InterfaceDescriptor, ) -> Result<(), Error>

where O: ImmutableAccessIdentifier,

Exports an interface of a module.

Failure

Fails if module is invalid, interface is already exported, interface is not contained in the module or the module is not yet initialized.

Return

Error on failure.

fn get_load_dependencies<'module, O>( &self, module: &Module<'module, O>, ) -> Result<&'module [InterfaceDescriptor], Error>

where O: ImmutableAccessIdentifier,

Fetches the load dependencies of a module.

Failure

Fails if module is invalid.

Return

Load dependencies on success, error otherwise.

fn get_runtime_dependencies<'module, O>( &self, module: &Module<'module, O>, ) -> Result<&'module [InterfaceDescriptor], Error>

where O: ImmutableAccessIdentifier,

Fetches the runtime dependencies of a module.

Failure

Fails if module is invalid or the module is not yet loaded.

Return

Runtime dependencies on success, error otherwise.

fn get_exportable_interfaces<'module, O>( &self, module: &Module<'module, O>, ) -> Result<&'module [InterfaceDescriptor], Error>

where O: ImmutableAccessIdentifier,

Fetches the exportable interfaces of a module.

Failure

Fails if module is invalid or the module is not yet loaded.

Return

Exportable interfaces on success, error otherwise.

fn fetch_status<O>(&self, module: &Module<'_, O>) -> Result<ModuleStatus, Error>

where O: ImmutableAccessIdentifier,

Fetches the load status of a module.

Failure

Fails if module is invalid.

Return

Module status on success, error otherwise.

fn get_module_path<'module, O>( &self, module: &Module<'module, O>, ) -> Result<&'module [OSPathChar], Error>

where O: ImmutableAccessIdentifier,

Fetches the path a module was loaded from.

Failure

Fails if module is invalid or the module is not yet loaded.

Return

Module path on success, error otherwise.

fn get_module_info<'module, O>( &self, module: &Module<'module, O>, ) -> Result<&'module ModuleInfo, Error>

where O: ImmutableAccessIdentifier,

Fetches the module info from a module.

Failure

Fails if module is invalid or the module is not yet loaded.

Return

Module info on success, error otherwise.

fn get_interface<'module, O, T>( &self, module: &'module Module<'_, O>, interface: &InterfaceDescriptor, caster: impl FnOnce(Interface) -> T, ) -> Result<Interface<'module, T>, Error>

where O: ImmutableAccessIdentifier,

Fetches an interface from a module.

Failure

Fails if module is invalid, the module is not in a ready state or the interface is not contained in the module.

Return

Interface 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> ModuleAPI<'interface> for T

where T: ModuleBinding,