Trait spirit::fragment::driver::Driver [−][src]
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;
}
Expand description
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 Fragment
s 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 Instruction
s how to
transition from the old state to the new one.
The Pipeline
then either follows these Instruction
s 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 Pipeline
s and Driver
s work is described in the
fragment
module.
Associated Types
type SubFragment: Fragment
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>
.
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>,
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.
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.
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
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
.