pub trait Builder<ArtCan, BCan>: Debug + 'staticwhere
BCan: CanStrong,{
type Artifact: Debug + 'static;
type DynState: Debug + 'static;
type Err: Debug + 'static;
// Required methods
fn build(
&self,
cache: &mut Resolver<'_, ArtCan, BCan, Self::DynState>,
) -> Result<ArtCan::Bin, Self::Err>
where ArtCan: Can<Self::Artifact>;
fn init_dyn_state(&self) -> Self::DynState;
}Expand description
Represents a Builder for an Artifact.
The Builder is the central trait of this crate. It defines the
Builders (the structs implementing this trait) which are referred to
throughout this crate, as well as the Artifacts, which are the values
build by a Builder, and defined via the Artifact associate type.
To be usable within this crate, a Builder has to be wrapped in a
Blueprint. Then it can be used to with a Cache to build and get
its Artifact.
When Blueprint (containing a Builder) is resolved at a Cache, the
Cache will call the build method of that Builder as needed (i.e.
whenever there is no cached Artifact available),
providing it with a Resolver, which allows to resolve its depending
Builders to their Artifacts.
An important concept is that a Builder may depend on other Builders (i.e.
it may use their Artifacts to construct its own Artifact). Thus constituting
existential dependencies between Artifacts.
The depending Builders are supposed to be stored in the Builder struct
which is then accessible from the build method to resolve them.
§Advanced Features
Unlike various SimpleBuilders this Builder offers additionally more
advanced features than described above. These are explained in the
following.
§Dynamic State
Each Builder may define a dynamic state, default is the unit type ().
That is a value that will be stored in a Box in the Cache, which will
be accessible even mutably for anyone from the Cache, as opposed to the
Builder itself, which will become inaccessible once wrapped in a
Blueprint.
If a Builder is encountered by a Cache for the first time, the Cache
will use the Builder’s init_dyn_state method to initialize the stored
dynamic state. It can then be accessed by the Builder itself from its
build method thought Resolver::my_state of the provided Resolver.
The dynamic state might be used for various purposes, the simples is as a
kind of variable configuration of the respective Builder. Notice that the
Artifact conceptional depends on the dynamic state, thus altering the
dynamic state (i.e. if access thought Cache::dyn_state_mut)
will invalidate the Artifact of the respective Builder.
Another use-case of the dynamic state is to keep some state between builds.
An extreme example of this is the RedeemingBuilder, which will replay
entire Artifacts of its inner Builder, when it fails to produce a new one.
§Failure
Builders are generally allowed to fail. Thus returning a Result
with the defined Err type,
which can be returned by the build method.
The infallible SimpleBuilders use the Never-type (a stable variation
of the yet unstable !, the official never-type) as Err, because that
Never type allows simple unpacking of the Results returned by the
Cache.
Thus if a Builder can always produce an Artifact, its Err type should be
that Never type.
Required Associated Types§
Required Methods§
Sourcefn build(
&self,
cache: &mut Resolver<'_, ArtCan, BCan, Self::DynState>,
) -> Result<ArtCan::Bin, Self::Err>
fn build( &self, cache: &mut Resolver<'_, ArtCan, BCan, Self::DynState>, ) -> Result<ArtCan::Bin, Self::Err>
Produces an artifact using the given Resolver for resolving
dependencies.
Sourcefn init_dyn_state(&self) -> Self::DynState
fn init_dyn_state(&self) -> Self::DynState
Return an initial dynamic state for this builder.
When a builder is first seen by a Cache the cache will use this method
to obtain an initial value for the dynamic state of this builder.