Skip to main content

Engine

Struct Engine 

Source
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>

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub const fn reports(&self) -> bool

Whether the engine keeps what the observation report needs.

Source

pub fn unknown_system_calls(&self) -> Result<Vec<UnknownCalls>, LockError>

The runs of the build that made system calls that the tracer does not know, in the order they ended, each with whether its result was cached.

§Errors

A LockError when the runs stay locked.

Source

pub fn connections(&self) -> Result<Vec<StepConnections>, LockError>

The runs of the build that connected to IPv4 or IPv6 addresses or to Unix sockets, in the order they ended, each with its connections and whether its result was cached. A cache hit is no run, so it adds nothing.

§Errors

A LockError when the runs stay locked.

Source

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.

Source

pub const fn fails_unchecked(&self) -> bool

Whether a task run that leaves a step unchecked fails.

Source

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.

Source

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.

Source

pub const fn build(&self) -> BuildId

The identity of the build.

Source

pub fn is_cancelled(&self) -> bool

Whether cancellation was requested, so the build starts nothing new.

Source

pub fn warnings(&self) -> Result<Vec<RepeatedWarning>, LockError>

The warnings for steps that re-ran in consecutive builds for the same self-inflicted reason, in the order they ran, one per step.

§Errors

A LockError when the warnings stay locked.

Source

pub fn files_hashed(&self) -> u64

The number of files whose content this engine has hashed, to record steps and to check the cache.

Source

pub const fn file_states(&self) -> &FileStates

The file states and hashes of the build.

Source

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.

Source

pub fn not_cached(&self) -> Result<Vec<(StepKey, NotCachedReason)>, LockError>

The steps of the build whose last result was not cached, with why, sorted by step key.

§Errors

A LockError when the results stay locked.

Source

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.

Source

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.

Source

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§

Source§

impl Debug for Engine<'_>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

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§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T> AsTypeStaticRegistered for T

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> HasTyVTable for T
where T: ?Sized,

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> StarlarkAnyBound for T
where T: Debug + Send + Sync + 'static,

§

impl<T> ToAst for T

§

fn ast(self, begin: usize, end: usize) -> Spanned<Self>

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more