Trait spirit::fragment::Installer

pub trait Installer<Resource, O, C> {
    type UninstallHandle: Send + 'static;
    fn install(
        &mut self, 
        resource: Resource, 
        name: &'static str
    ) -> Self::UninstallHandle;

    fn init<B: Extensible<Opts = O, Config = C, Ok = B>>(
        &mut self, 
        builder: B, 
        _name: &'static str
    ) -> Result<B, AnyError>
    where
        B::Config: DeserializeOwned + Send + Sync + 'static,
        B::Opts: StructOpt + Send + Sync + 'static,
    { ... }
}

An entity that is able to install a resource.

At the end of a Pipeline there’s an installer. It takes the (transformed) resource and somehow makes it active in the program.

An installer can be even a storage provided by a user where the resource is stored ‒ eg. a proxy object to the resource where it can be switched.

Note that installation of the resource must not fail.

Associated Types

type UninstallHandle: Send + 'static

A handle representing lifetime of the resource.

Some resources or installers are for a single instance. In that case a new resource simply replaces the old one and the UninstallHandle serves no role and can be set to ().

In other cases it is possible to have multiple instances of the Resource active at the same time (eg. futures in the tokio runtime). Then the installer returns a handle for each resource installed. The Pipeline uses the handle as a proxy to the installed resource. When the time comes for the resource to go away, the Pipeline drops the respective handle and that should take care of removing the resource.

See also

The Stackable marker trait describes if it makes sense to have multiple instances of the resource, therefore if using collections of the Fragment in the configuration makes sense and is allowed.

Required methods

fn install(
    &mut self,
    resource: Resource,
    name: &'static str
) -> Self::UninstallHandle

Installs another instance of the resource.

This is the main method of the trait.

The installation must not fail. Depending on the resource semantics, this should either replace the previous instance or return relevant UninstallHandle.

Provided methods

fn init<B: Extensible<Opts = O, Config = C, Ok = B>>(
    &mut self,
    builder: B,
    _name: &'static str
) -> Result<B, AnyError> where
    B::Config: DeserializeOwned + Send + Sync + 'static,
    B::Opts: StructOpt + Send + Sync + 'static, 

Initialize the installer.

The pipeline will run this method exactly once, upon being inserted into a Builder or Spirit. This happens before any resources are installed.

The installer may set up the Extensible in a suitable way.

It is not mandatory to implement this method. The default installation does nothing (as many installers simply don’t need any special setup).

Implementors

impl<Resource, O, C, Slave> Installer<Resource, O, C> for SeqInstaller<Slave> where
    Resource: IntoIterator,
    Slave: Installer<Resource::Item, O, C>,