Trait spirit::fragment::driver::Driver

pub trait Driver<F: Fragment> {
    type SubFragment: Fragment;
    fn instructions<T, I>(
        &mut self, 
        fragment: &F, 
        transform: &mut T, 
        name: &'static str
    ) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>>
    where
        T: Transformation<<Self::SubFragment as Fragment>::Resource, I, Self::SubFragment>;
    fn confirm(&mut self, name: &'static str);
    fn abort(&mut self, name: &'static str);
    fn maybe_cached(&self, frament: &F, name: &'static str) -> bool;
}

The Driver of a Pipeline.

The driver is the part of the Pipeline that decides when a cached/old version of a resource is good enough to keep or when a new one needs to be created and the old one removed, and if it should be recreated from scratch or the seed can be reused. It also can split the Fragment into smaller Fragments and drive the resources separately.

Any kind of caching (of either the old Fragment, the Seed, the Resource or of anything else) is fully in the control of the Driver itself.

Each time the configuration is reloaded, the Driver is fed with the new version of the fragment. The driver can either return error (or multiple ones) or Instructions how to transition from the old state to the new one.

The Pipeline then either follows these Instructions and calls confirm, or drops the instructions (for example if some other Pipeline failed) and calls abort. Exactly one of these will be called after call of instructions.

If abort is called, the Driver shall act in the same way as if the last instructions has never been called ‒ eg. it should return to the old state and keep caching the old data. If confirm is called, it can discard the old state and keep just the new one.

The F generic parameter is the Fragment this driver will be provided. In contrast, the SubFragment is the smaller fragment into which the Driver cuts the original F. It may or may not be the same type.

If it cuts F into smaller ones, one resource for each SubFragment is to be created and transformed.

The whole anatomy of how Pipelines and Drivers work is described in the fragment module.

Associated Types

type SubFragment: Fragment

The smaller Fragment the driver cuts F into.

This may be the same as F or it may be something smaller (eg. it may be the elements of Vec<T>.

Loading content...

Required methods

fn instructions<T, I>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<<Self::SubFragment as Fragment>::Resource, I, Self::SubFragment>, 

Issues the instructions how to transition to the new fragment.

The driver needs to issue some valid sequence of instructions (see the Instruction for details what is valid) to make sure the Resource for the new Fragment is active.

Note that the instructions are not automatically followed. The call of instructions will be followed by either a call to confirm or abort, depending on if the whole new configuration is accepted or not. The Driver needs to take this into account when caching.

Part of creation of the Resource is applying the Transformation.

In case there are no changes needed, empty sequence of instructions may be legally returned. The abort or confirm is called even in such case.

If it is not possible to create the resource or resources (the driver is allowed to produce multiple), an error or errors shall be returned instead. In such case the internal cache must stay the same.

fn confirm(&mut self, name: &'static str)

Call to this method informs the Driver that the instructions returned by the last call to instructions were followed and the changes have taken place.

Therefore, the Driver should preserve the new state in its cache (if it does any caching).

Alternatively, the abort may be called instead to inform of not applying the instructions.

fn abort(&mut self, name: &'static str)

Call to this method informs the Driver that the instructions returned by the last call to instructions were not followed and were dropped.

Therefore, the Driver should return its caches to the state before the call to instructions (if it does any caching at all).

fn maybe_cached(&self, frament: &F, name: &'static str) -> bool

Informs if there's a chance the new fragment will use something in the Driver's cache if applied.

The driver shall return true if by using this instance of Driver (with the current state of caches) would somehow use its cache to create the resource from the provided fragment ‒ either by reusing it completely or by using the Seed.

This is used by higher-level drivers (for example the SeqDriver) to decide which slave driver should take care of which their SubFragment.

Loading content...

Implementors

impl<'a, F: Fragment, Inner: Driver<F>> Driver<&'a F> for RefDriver<Inner>

type SubFragment = Inner::SubFragment

fn instructions<T, I>(
    &mut self,
    fragment: &&F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<<Self::SubFragment as Fragment>::Resource, I, Self::SubFragment>, 

fn confirm(&mut self, name: &'static str)

fn abort(&mut self, name: &'static str)

fn maybe_cached(&self, fragment: &&F, name: &'static str) -> bool

impl<F> Driver<F> for CacheEq<F> where
    F: Debug + Fragment + ToOwned + PartialEq<<F as ToOwned>::Owned>, 

type SubFragment = F

fn instructions<T, I>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<F::Resource, I, F>, 

fn abort(&mut self, name: &'static str)

fn confirm(&mut self, name: &'static str)

fn maybe_cached(&self, fragment: &F, _name: &'static str) -> bool

impl<F> Driver<F> for CacheSimilar<F> where
    F: Debug + Fragment + ToOwned + Comparable<<F as ToOwned>::Owned>, 

type SubFragment = F

fn instructions<T, I>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<F::Resource, I, F>, 

fn abort(&mut self, name: &'static str)

fn confirm(&mut self, name: &'static str)

fn maybe_cached(&self, fragment: &F, _name: &'static str) -> bool

impl<F> Driver<F> for OnceDriver<F> where
    F: Fragment + PartialEq<<F as ToOwned>::Owned> + ToOwned + 'static, 

type SubFragment = F

fn instructions<T, I>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<<Self::SubFragment as Fragment>::Resource, I, Self::SubFragment>, 

fn confirm(&mut self, _name: &'static str)

fn abort(&mut self, _name: &'static str)

fn maybe_cached(&self, fragment: &F, _name: &'static str) -> bool

impl<F, I, SlaveDriver> Driver<F> for SeqDriver<I, SlaveDriver> where
    F: Fragment,
    I: Fragment,
    &'a F: IntoIterator<Item = &'a I>,
    SlaveDriver: Driver<I> + Default, 

type SubFragment = SlaveDriver::SubFragment

fn instructions<T, Ins>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<<Self::SubFragment as Fragment>::Resource, Ins, Self::SubFragment>, 

fn confirm(&mut self, name: &'static str)

fn abort(&mut self, name: &'static str)

fn maybe_cached(&self, fragment: &F, name: &'static str) -> bool

impl<F: Fragment> Driver<F> for Trivial

type SubFragment = F

fn instructions<T, I>(
    &mut self,
    fragment: &F,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<F::Resource, I, F>, 

fn confirm(&mut self, _name: &'static str)

fn abort(&mut self, _name: &'static str)

fn maybe_cached(&self, _: &F, _name: &'static str) -> bool

Loading content...