pub struct Engine<'a> { /* private fields */ }Expand description
What every task of a build shares to run, check, and record its steps.
Implementations§
Source§impl<'a> Engine<'a>
impl<'a> Engine<'a>
Sourcepub fn new(
tracer: &'a dyn Tracer,
store: &'a Store,
echo: &'a dyn EchoSink,
cancel: Cancellation,
home: Option<AbsolutePath>,
pool: &WorkerPool,
) -> Self
pub fn new( tracer: &'a dyn Tracer, store: &'a Store, echo: &'a dyn EchoSink, cancel: Cancellation, home: Option<AbsolutePath>, pool: &WorkerPool, ) -> Self
An engine for one build that runs commands with tracer, echoes live output
to echo, stops commands when cancel is set, stores records in store,
expands ~/ in patterns to home, the caller’s home directory, and runs its
parallel work, hashing included, on pool.
Sourcepub const fn with_lock_patience(self, patience: Duration) -> Self
pub const fn with_lock_patience(self, patience: Duration) -> Self
The engine, whose readers and steps wait at most patience for its shared
state while another holder keeps it locked, and then fail with a
LockError or a step error, instead of LOCK_PATIENCE. Tests use a
short patience to reach those errors without waiting for the default.
Sourcepub fn hold_warnings(&self) -> Result<impl Sized + '_, LockError>
pub fn hold_warnings(&self) -> Result<impl Sized + '_, LockError>
Hold the build’s warnings for repeated reasons locked until the returned guard is dropped, so a test of a caller can reach what a reader does when the engine’s state stays locked; only builds with debug assertions, such as tests, have it.
§Errors
A LockError when the warnings stay locked for the engine’s patience.
Sourcepub const fn with_cache_unknown_system_calls(self, cache: bool) -> Self
pub const fn with_cache_unknown_system_calls(self, cache: bool) -> Self
The engine, which caches the result of a run that made system calls that
the tracer does not know, as if it had made none, when cache is set, as
kizz build --cache-unknown-syscalls asks. Without it, such a result is not
cached unless no other reason applies. The option is in no step key or
record.
Sourcepub const fn caches_unknown_system_calls(&self) -> bool
pub const fn caches_unknown_system_calls(&self) -> bool
Whether the engine caches the results of runs that made system calls that the tracer does not know.
Sourcepub const fn with_no_cache(self, no_cache: bool) -> Self
pub const fn with_no_cache(self, no_cache: bool) -> Self
The engine, which runs every step as if it were marked always when
no_cache is set, as kizz run --no-cache asks: no cache check decides
whether a step runs, every result is still recorded as usual, and the reason
of a step that has a record names the option, unless the step is marked
always or its task cache=never. Nothing makes a step cached that would
run without it. The option is in no step key or record.
Sourcepub const fn with_echo_every_step(self, echo: bool) -> Self
pub const fn with_echo_every_step(self, echo: bool) -> Self
The engine, which echoes every command’s output live when echo is set, as
if every run() had stream = True, as kizz run asks. Without it, only
the output of a run() with stream = True is echoed. The option is in no
step key or record.
Sourcepub const fn with_report(self, report: bool) -> Self
pub const fn with_report(self, report: bool) -> Self
The engine, which asks the tracer for the process tree of every command and
keeps the commands of each task run for the observation report when report
is set, as kizz run --output asks (see TaskSteps::commands). Without
it, no request asks for the tree and nothing more is kept. The option is in
no step key or record.
Sourcepub const fn reports(&self) -> bool
pub const fn reports(&self) -> bool
Whether the engine keeps what the observation report needs.
Sourcepub fn unknown_system_calls(&self) -> Result<Vec<UnknownCalls>, LockError>
pub fn unknown_system_calls(&self) -> Result<Vec<UnknownCalls>, LockError>
Sourcepub fn connections(&self) -> Result<Vec<StepConnections>, LockError>
pub fn connections(&self) -> Result<Vec<StepConnections>, LockError>
Sourcepub const fn with_fail_unchecked(self, fail: bool) -> Self
pub const fn with_fail_unchecked(self, fail: bool) -> Self
The engine, which makes a task run that leaves a step unchecked fail when
its program ends, when fail is set, as kizz build --fail-unchecked asks.
Without it, an unchecked step only warns. The option is in no step key or
record.
Sourcepub const fn fails_unchecked(&self) -> bool
pub const fn fails_unchecked(&self) -> bool
Whether a task run that leaves a step unchecked fails.
Sourcepub const fn with_command_name(self, name: &'static str) -> Self
pub const fn with_command_name(self, name: &'static str) -> Self
The engine, whose messages name the command that runs it as name, such as
kizz run, with the option they mention, as in the failure of a task that
--fail-unchecked fails. Without it, they name kizz build. The name is in
no step key or record.
Sourcepub const fn command_name(&self) -> &'static str
pub const fn command_name(&self) -> &'static str
The command that runs the engine, as messages name it: kizz build unless
Engine::with_command_name set another.
Sourcepub fn is_cancelled(&self) -> bool
pub fn is_cancelled(&self) -> bool
Whether cancellation was requested, so the build starts nothing new.
Sourcepub fn files_hashed(&self) -> u64
pub fn files_hashed(&self) -> u64
The number of files whose content this engine has hashed, to record steps and to check the cache.
Sourcepub const fn file_states(&self) -> &FileStates
pub const fn file_states(&self) -> &FileStates
The file states and hashes of the build.
Sourcepub fn program_wrote(
&self,
task: &TaskId,
changes: &FileChanges,
) -> Result<(), StoreError>
pub fn program_wrote( &self, task: &TaskId, changes: &FileChanges, ) -> Result<(), StoreError>
Store the program of the task task as the last writer of each file in
changes, the files it changed through fs.write and fs.write_json in this
build, with the time of each change, and drop their cached hashes. A file
whose last writer wrote it later, such as a step that the program ran after
its write, keeps that writer.
§Errors
A StoreError when a record cannot be read or written.
Sourcepub fn not_cached(&self) -> Result<Vec<(StepKey, NotCachedReason)>, LockError>
pub fn not_cached(&self) -> Result<Vec<(StepKey, NotCachedReason)>, LockError>
Sourcepub fn was_untraced(&self, key: &StepKey) -> Result<bool, LockError>
pub fn was_untraced(&self, key: &StepKey) -> Result<bool, LockError>
Whether a result was explicitly untraced, so it needs no incomplete-trace warning.
§Errors
Returns a lock error when the build’s results stay locked.
Sourcepub fn task(
&self,
program: ProgramHash,
task_dir: AbsolutePath,
) -> TaskSteps<'_>
pub fn task( &self, program: ProgramHash, task_dir: AbsolutePath, ) -> TaskSteps<'_>
The step executor of one run of a task program whose hash is program and
whose directory is task_dir, without a task identity: its steps are checked,
run, recorded, and explained, but no step position, last writer, or task
record is stored for them, and no task becomes an owner of their records,
whose other owners are kept. Builds use Engine::task_for.
Sourcepub fn task_for(&self, identity: TaskIdentity) -> TaskSteps<'_>
pub fn task_for(&self, identity: TaskIdentity) -> TaskSteps<'_>
The step executor of one run of the task identity, which stores the step
positions and last writers of its steps, makes the task an owner of the
record of every step it runs or finds cached, and stores its task record when
the run ends with TaskSteps::finish.
Trait Implementations§
Auto Trait Implementations§
impl<'a> !Freeze for Engine<'a>
impl<'a> !RefUnwindSafe for Engine<'a>
impl<'a> !UnwindSafe for Engine<'a>
impl<'a> Send for Engine<'a>
impl<'a> Sync for Engine<'a>
impl<'a> Unpin for Engine<'a>
impl<'a> UnsafeUnpin for Engine<'a>
Blanket Implementations§
impl<T> AsTypeStaticRegistered for T
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
impl<T> HasTyVTable for Twhere
T: ?Sized,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more