Trait spirit::fragment::Fragment[][src]

pub trait Fragment: Sized {
    type Driver: Driver<Self> + Default;
    type Installer: Default;
    type Seed;
    type Resource;

    const RUN_BEFORE_CONFIG: bool;

    fn make_seed(&self, name: &'static str) -> Result<Self::Seed, AnyError>;
fn make_resource(
        &self,
        seed: &mut Self::Seed,
        name: &'static str
    ) -> Result<Self::Resource, AnyError>; fn create(&self, name: &'static str) -> Result<Self::Resource, AnyError> { ... }
fn init<B: Extensible<Ok = B>>(
        builder: B,
        _: &'static str
    ) -> Result<B, AnyError>
    where
        B::Config: DeserializeOwned + Send + Sync + 'static,
        B::Opts: StructOpt + Send + Sync + 'static
, { ... } }
Expand description

A fragment of configuration.

The fragment is the part of configuration Pipelines work with. It usually comes directly from the configuration, but it also may be constructed by the Extractor (maybe by combining parts of the configuration, or combining data from configuration and command line options).

See the details of how pipelines work.

Note that fragments as described by this trait create their resources in two stages ‒ first a Seed is created, then turned into Resource. The Driver controls this. Note that one Seed may be used to create multiple instances of the Resource (depending on the driver either in parallel or sequentially, replacing the previous ones). However, if fragment doesn’t want to have this two-phase creation, it can set the Seed to ().

Associated Types

The default driver to be used by the fragment.

If a pipeline is created with this fragment, this is the driver that will be used by default, unless the user overrides it. There’s a list of drivers to pick from if you don’t want to write your own (the most common caching and creation needs should be covered).

The default installer to be used unless a transformation or the user doesn’t provide one.

This is the type the pipeline will use for installation of resources created by this fragment. Note that some fragments don’t have a default installer (because they either need to be put into a user-provided storage or need to be transformed first). They can have the Installer set to () ‒ but the pipeline will not be usable unless an installer is provided by some means later on.

The intermediate product if the fragment supports two-stage creation of Resources. If not, it can be set to ().

The actual product this Fragment creates.

Associated Constants

Configuration if the pipeline should be run once even before the config is loaded.

If this is set to true, the pipeline will be run once immediately after loading the command line options, even before the initial configuration is ready (therefore the fragment will come from within the default configuration).

This does not stop the pipeline to run again once the configuration is loaded, but it may be used to provide some early intermediate setup.

This is used with for example logging, as it:

  • Initializes very basic logging directly from the Installer::init method.
  • Initializes logging based on the command line only once that becomes available.
  • Switches to logging based on the configuration once that is available.

However, most „normal“ fragments don’t need to worry about this and can wait for real configuration to become available.

Required methods

Runs the first stage of creation.

This creates the Seed. If the two-stage creation is not needed for this fragment, this should simply return Ok(()).

This method should be provided by an implementation, but wouldn’t usually be called directly by the user. This is used either by the Pipeline or internally by the higher-level create method.

Runs the second stage of creation.

This turns the seed into the actual resource. If the two-stage configuration is not supported by this fragment, the real work should happen in this method.

This method needs to be provided by the implementation, but it wouldn’t usually be called directly by the user. It is used internally by Pipeline and the create method.

Provided methods

Runs both stages of creation at once.

This runs both make_seed and make_resource. It should not be overridden by an implementation.

This is meant to be used by the user if the user wishes to use the fragment directly, without the support of Pipeline.

An initialization routine.

This will be called once by a Pipeline before the first use of the fragment. This allows the fragment to configure the Builder or Spirit the pipeline will be used in.

The implementation may leave it at the default (empty) implementation in case no special setup is needed.

Implementations on Foreign Types

Implementors