entelechy-kernelGenerated

Layer: core · Lines of code: 2,986 · Integration test files: 2

Brief

Entelechy Kernel Runtime: prepare, publish, execute, and atomically replace Kernel versions

Description

Kernel Runtime (L4).

The runtime owns the Host, the backend it is given, and the registry of published Kernel versions. It takes validated IR; every backend implements the Backend contract from entelechy-rules. A published version is immutable. Runtime::prepare_module builds a Candidate outside the registry; Runtime::publish swaps it in atomically when the caller’s expected generation still holds. A failed preparation leaves the running Kernel untouched, and holders of an Arc<KernelVersion> keep executing the version they pinned.

Runtime::prepare_later hands preparation to a worker and returns a Ticket; Runtime::poll collects the Candidate. Without a worker the same calls prepare inline, deterministically.


Internal dependencies	`entelechy-abi`, `entelechy-ir`, `entelechy-rules`
External dependencies	—
Source	`crates/core/kernel`

Modules

Name	Brief
`clock`	The machine’s clock: `entelechy_rules::clock`, which every layer times by.
`progress`	What preparing Kernels is doing, readable from any thread while it runs: each Kernel of the work at hand, from expected to compiled (`prepare`) to built on its device (`finish`), and how long its current step has taken and each step it ended took; and the scene’s nodes, each with its Kernel, and which feed which. An interface draws it while a scene loads.

Structs

Name	Brief
`progress::Seed`	One Kernel of the work at hand.
`progress::Preparing`	The work at hand, the Kernels in the order they were first expected.
`progress::Progress`	The shared record; cloned handles see the same work.
`Generation`	Monotonic counter identifying one published version, unique across all Kernels in a runtime.
`KernelVersion`	An immutable published Kernel version.
`Candidate`	A compiled, validated, backend-prepared Kernel not yet published.
`StaleCandidate`	The registry did not match the publisher’s expectation.
`Ticket`	A preparation handed to the worker; redeemed with `Runtime::poll`.
`Preparer`	A runtime’s backends and grants, to prepare modules on many threads at once (`Runtime::preparer`); a candidate it makes is the one the runtime would make.
`Runtime`	The Kernel Runtime.
`Placement`	Where a version executes: the backend’s name, and why it is not the main backend when it is not.
`Routed`	Why a run left the main backend, read as text. The text is written the first time it is read: a run records its reason, a report reads it.
`Moved`	Bytes carried between Host memory and a device.

Enumerations

Name	Brief
`progress::Stage`	Where one Kernel is in its preparation.
`PrepareError`	Why a candidate could not be prepared.
`Expect`	What the publisher believes the registry currently holds for the id.
`LoadError`	Errors from the combined prepare-and-publish path.
`Fetch`	A Field’s words on their way: `Runtime::fetch`.

Constants

Name	Type	Value	Brief
`DEFAULT_SMALL`	`u64`	`400_000`	The operations a run may take, by its elements times its Kernel’s typical work, and go to the ordered backend when the main one is a device: about what a device’s dispatch costs in time, spent on the processor instead.
`FEW_ELEMENTS`	`u64`	`64`	The elements a run may have and go to the ordered backend however much each takes: fewer than one of a device’s groups holds, which the device runs a thread each.
`FEW_FRESH_BYTES`	`u64`	`_`	The most a run of `FEW_ELEMENTS` may read of what the device made in the same evaluation and still go to the ordered backend, which waits for it and brings it down.
`FEW_LONG_WORK`	`u64`	`100_000`	The operations past which a run of `FEW_ELEMENTS` that reads what the device made in the same evaluation still goes to the ordered backend: run a thread at a time on a device they take longer (two thirds of a millisecond, at the 6.6 ns an operation measured) than waiting for the device costs; fewer stay, the device’s work kept whole.

Re-exports

Moment, give, now, since, wall, pad, ABI_VERSION, Capabilities, Capability, Census, Context, Domain, Encoding, FieldBytes, FieldData, Handle, Host, HostError, Image, InputState, Invocation, Number, Pixel, Scalar, Schema, Scope, Shape, Value, DEFAULT_WORK, MAX_WORK, TYPED, encoding, KernelId, Manifest, Validated, Backend, Check, ClockedFrame, Downloading, ExecutionError, Extent, NativeOp, Prepared, check_domain_shape, check_input_types, extent, input_type_fault, Run, Preparing, Progress, Seed, Stage

progress::Seed

crates/core/kernel/src/progress.rs#L32

One Kernel of the work at hand.

Properties

Name	Type	Description
`id`	`KernelId`	The Kernel.
`stage`	`Stage`	Where it is.
`took`	`Duration`	How long its current step has run, while it runs; how long its last step took, after.
`compiling`	`Duration`	How long its last compiling took, once one has ended.
`building`	`Duration`	How long its last building took, once one has ended.

Implemented traits: Clone, Debug

progress::Preparing

crates/core/kernel/src/progress.rs#L48

The work at hand, the Kernels in the order they were first expected.

Properties

Name	Type	Description
`seeds`	`Vec<Seed>`	Each Kernel of it.
`nodes`	`Vec<KernelId>`	The scene’s nodes, each by its Kernel, once the scene is read.
`links`	`Vec<(usize, usize)>`	Nodes that feed each other, by their place in `nodes`, each pair once, the lower first.

Methods

Function	Description
`fn built(&self) -> usize`	The Kernels ready to run.
`fn busy(&self) -> bool`	Whether any Kernel is still being worked on or waits.
`fn longest(&self) -> Option<&Seed>`	The Kernel whose current step has run longest, while one runs.

Implemented traits: Clone, Debug, Default

progress::Progress

crates/core/kernel/src/progress.rs#L113

The shared record; cloned handles see the same work.

Methods

Function	Description
`fn now(&self) -> Preparing`	The work at hand now.
`fn shape(&self, nodes: Vec<KernelId>, links: impl IntoIterator<Item = (usize, usize)>)`	Says the scene’s nodes now, each by its Kernel, and which feed which, by their place in `nodes`; what was said before goes.

Implemented traits: Clone, Debug, Default

Generation

crates/core/kernel/src/lib.rs#L122

Monotonic counter identifying one published version, unique across all Kernels in a runtime.

Properties

Name	Type	Description
`0`	`u64`

Implemented traits: Clone, Copy, Debug, Display, Eq, Hash, Ord, PartialEq, PartialOrd, StructuralPartialEq

KernelVersion

crates/core/kernel/src/lib.rs#L162

An immutable published Kernel version.

Methods

Function	Description
`fn id(&self) -> &KernelId`	The Kernel id.
`fn generation(&self) -> Generation`	The generation this version was published as.
`fn manifest(&self) -> &Manifest`	The manifest.
`fn module(&self) -> Option<&Validated>`	The validated IR, or `None` for a native operation.
`fn native(&self) -> Option<NativeOp>`	The native operation this version stands for, if it is one.
`fn source(&self) -> &str`	The source this version was compiled from.

Implemented traits: Debug

Candidate

crates/core/kernel/src/lib.rs#L284

A compiled, validated, backend-prepared Kernel not yet published.

Methods

Function	Description
`fn id(&self) -> &KernelId`	The id the candidate will publish as.
`fn manifest(&self) -> &Manifest`	The manifest.
`fn module(&self) -> &Validated`	The validated IR.

Implemented traits: Debug

StaleCandidate

crates/core/kernel/src/lib.rs#L403

The registry did not match the publisher’s expectation.

Properties

Name	Type	Description
`id`	`KernelId`	The Kernel id.
`expected`	`Expect`	What the publisher expected.
`actual`	`Option<Generation>`	What the registry holds.

Implemented traits: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

Ticket

crates/core/kernel/src/lib.rs#L465

A preparation handed to the worker; redeemed with Runtime::poll.

Implemented traits: Clone, Copy, Debug, Display, Eq, Hash, Ord, PartialEq, PartialOrd, StructuralPartialEq

Preparer

crates/core/kernel/src/lib.rs#L497

A runtime’s backends and grants, to prepare modules on many threads at once (Runtime::preparer); a candidate it makes is the one the runtime would make.

Methods

Function	Description
`fn finish(&self, version: &KernelVersion)`	Finishes `version` on the main backend (`Backend::finish`), where it was prepared there, so its first run there waits for nothing; where that backend could not build it after all, its runs go to the ordered backend from now on. A panic in the backend leaves it for that run to report.
`fn expect<'a>(&self, ids: impl IntoIterator<Item = &'a KernelId>)`	Says the Kernels `ids` are about to be prepared or finished here, so what is watched (`Runtime::progress`) counts them before they begin.
`fn prepare_replacing(&self, module: Validated, source: &str, running: &KernelVersion) -> Result<Candidate, PrepareError>`	Prepares `module` to replace `running` as `Runtime::prepare_later` does: made ready where `running` ran.
`fn prepare(&self, module: Validated, source: &str) -> Result<Candidate, PrepareError>`	Prepares `module` as `Runtime::prepare_module` does.

Implemented traits: Clone

Runtime

crates/core/kernel/src/lib.rs#L706

The Kernel Runtime.

Methods

Function	Description
`fn execute_later(&mut self, version: &Arc<KernelVersion>, invocation: &Invocation) -> Result<Run, ExecutionError>`	Starts executing a pinned version on its own thread and returns at once. Inputs are copied first, so the caller may release or overwrite them. A native operation is device work and runs now; its run is redeemed like any other.
`fn poll_run(&mut self, run: Run) -> Option<Result<Vec<Handle>, ExecutionError>>`	Takes a landed run’s outputs as Fields of this Host, or `None` while it is still going. A run is redeemed once.
`fn wait_run(&mut self, run: Run) -> Result<Vec<Handle>, ExecutionError>`	Blocks until `run` lands and takes its outputs; other runs that land meanwhile wait for their own poll.
`fn discard_run(&mut self, run: Run)`	Forgets a run whose outputs are unwanted; what it lands is dropped.
`fn runs_in_flight(&mut self) -> usize`	How many runs are still going.
`fn with_backend(budget_words: usize, backend: Box<dyn Backend>) -> Self`	Creates a runtime over the given backend.
`fn with_backends(budget_words: usize, backend: Box<dyn Backend>, ordered: Option<Box<dyn Backend>>) -> Self`	Creates a runtime over `backend`, with `ordered` running the scans when given; see `Runtime::executes_on`.
`fn set_background(&mut self, enabled: bool)`	Starts or stops the preparation worker. With a worker, `Runtime::prepare_later` returns before the backend builds; without one (or where no thread can start) it prepares inline. Stopping waits for jobs in flight and keeps their results for `Runtime::poll`.
`fn background(&self) -> bool`	Whether a preparation worker is running.
`fn prepare_turn(&mut self, most: usize) -> usize`	Where no thread can start, prepares at most `most` of the queued modules; elsewhere the workers do and this does nothing. The modules still waiting.
`fn prepare_in_turns(&mut self)`	Prepares in turns (`Runtime::prepare_turn`) instead of on workers, as where no thread can start: what a page does, for a test.
`fn prepares_in_turns(&self) -> bool`	Whether it prepares in turns (`Runtime::prepare_turn`): where no thread can start, a new Kernel too waits its turn rather than holding the sync that found it.
`fn prepare_queued(&self) -> usize`	The modules waiting their turn (`Runtime::prepare_turn`).
`fn prepare_later(&mut self, module: Validated, source: String) -> Ticket`	Hands a validated module to the worker, or prepares it now when there is none. `source` is kept for inspection. A replacement is made ready where the version it replaces ran: finished on the main backend (`Backend::finish`), prepared on the ordered one for runs the size sends there; so the runs after it takes that version’s place do not wait for it.
`fn prepare_later_beside(&mut self, module: Validated, source: String, beside: &KernelVersion) -> Ticket`	Prepares `module` as `Runtime::prepare_later` does, to run in `beside`’s place (a fused group in its consumer’s): made ready on the main backend where `beside` ran there or was built there, so its first run waits for no compiler; on the ordered one where `beside` ran there.
`fn poll(&mut self, ticket: Ticket) -> Option<Result<Candidate, PrepareError>>`	Takes a finished preparation, or `None` while it runs. A ticket is redeemed once.
`fn uncollected(&self) -> usize`	Uncollected preparations, finished or forgotten. Each holds a module and its prepared backend state; a session that publishes and evaluates in step leaves none.
`fn discard(&mut self, ticket: Ticket)`	Forgets a preparation whose result is unwanted.
`fn detach(&mut self, candidate: Candidate, id: KernelId) -> Arc<KernelVersion>`	Turns a candidate into an unregistered version under the given id, executable like any pinned version.
`fn backend_name(&self) -> &'static str`	Name of the backend executing Kernels.
`fn settle_device(&self)`	Waits for the backend’s device to finish what it was given. See `Backend::settle_device`.
`fn device_waited(&self) -> Duration`	How long callers have been blocked on the main backend’s device in all (`Backend::waited`).
`fn submitted(&self) -> Option<Box<dyn Check>>`	A mark of every run submitted so far (`Backend::submitted`).
`fn set_clocked(&self, on: bool)`	Whether frames are clocked on the device (`Backend::set_clocked`).
`fn clock_mark(&self) -> usize`	How many runs the open clocked frame has been given (`Backend::clock_mark`).
`fn end_frame(&self) -> Option<u64>`	Ends a clocked frame, answering its number (`Backend::end_frame`).
`fn clocked_frame(&self) -> Option<ClockedFrame>`	The latest clocked frame the device has done (`Backend::clocked_frame`).
`fn backend_memory(&self) -> Vec<(String, u64)>`	What the backends hold of their own between runs (`Backend::memory`): each part named after its backend, in bytes.
`fn frame_device_time(&self) -> Option<Duration>`	The device’s busy time for the latest clocked frame it has done.
`fn has_device(&self) -> bool`	Whether the backend’s device work is done only when `Runtime::settle_device` returns, not when `execute` does.
`fn backend(&self) -> &dyn Backend`	The backend executing Kernels.
`fn host(&self) -> &Host`	The Host, for interfaces that import and export resources.
`fn materialize(&mut self, handle: Handle) -> Result<(), ExecutionError>`	Brings a resident Field back into Host memory through its owning backend; a Field in memory stays as it is.
`fn upload(&mut self, handle: Handle) -> Result<bool, ExecutionError>`	Gives a Field a copy on the main backend’s device ahead of the runs that read it (`Backend::upload`); answers whether it is there.
`fn join(&mut self, parts: &[(Handle, Range<usize>)], schema: &Schema) -> Result<Handle, ExecutionError>`	A new Field of the elements of `parts`, each a Field’s range of elements kept as `schema` keeps them, one part’s after another’s, as `Rows`: joined on the main backend’s device where it has one and an element is whole words (`Backend::join`), else in Host memory, each part brought home.
`fn same_words(&self, a: Handle, b: Handle) -> bool`	Whether two Fields hold the same words: compared in Host memory when both are there, on the device when both are resident on it. Fields of different extents or layouts, or apart, are not.
`fn fetch(&self, handle: Handle) -> Result<Fetch, ExecutionError>`	A Field’s words taken later (`Fetch::take`): from Host memory now, or from the device once the work submitted before this call has run, not waiting for what is submitted since. The Field may be released meanwhile.
`fn image(&mut self, handle: Handle) -> Result<Image, ExecutionError>`	The image view of a Field of pixels, materialized if resident: an observation boundary, where device work is waited for.
`fn host_mut(&mut self) -> &mut Host`	Mutable Host access, for interfaces that import and release resources.
`fn prepare_module(&self, module: Validated, source: &str) -> Result<Candidate, PrepareError>`	Backend-prepares a compiled, validated module; `source` is kept for inspection.

… and 28 more; see the source.

Placement

crates/core/kernel/src/lib.rs#L1933

Where a version executes: the backend’s name, and why it is not the main backend when it is not.

Properties

Name	Type	Description
`backend`	`&'static str`	The backend that runs it.
`routed`	`Option<Routed>`	Why the main backend does not run it, when it does not.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Routed

crates/core/kernel/src/lib.rs#L1943

Why a run left the main backend, read as text. The text is written the first time it is read: a run records its reason, a report reads it.

Implemented traits: Clone, Debug, Deref, Display, Eq, PartialEq

Moved

crates/core/kernel/src/lib.rs#L2007

Bytes carried between Host memory and a device.

Properties

Name	Type	Description
`uploaded`	`u64`	Brought to a device from Host memory.
`downloaded`	`u64`	Brought back to Host memory from a device, for a backend that reads there.

Implemented traits: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

progress::Stage

crates/core/kernel/src/progress.rs#L17

Where one Kernel is in its preparation.

Variants

Name	Description
`Waiting`	Expected; nothing begun.
`Compiling`	Being compiled and prepared on its backend.
`Compiled`	Prepared; its device has not built it yet, or has nothing to build.
`Building`	Being built on its device (a GPU’s pipelines).
`Built`	Ready to run.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

PrepareError

crates/core/kernel/src/lib.rs#L352

Why a candidate could not be prepared.

Variants

Name	Description
`Backend(String)`	The backend rejected the module; the message is backend-specific.
`Accounting(String)`	Accounting the module’s work made it invalid: a runtime fault, reported.
`Panicked(String)`	The backend panicked preparing the module; caught, so the running Kernel and the worker live on.
`NotGranted { id: KernelId, missing: Capabilities }`	The Kernel requires capabilities the runtime does not grant.

Implemented traits: Debug, Display, Error

Expect

crates/core/kernel/src/lib.rs#L392

What the publisher believes the registry currently holds for the id.

Variants

Name	Description
`Absent`	No version is published yet.
`Generation(Generation)`	Exactly this generation is current.
`Any`	Publish regardless of the current state.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

LoadError

crates/core/kernel/src/lib.rs#L445

Errors from the combined prepare-and-publish path.

Variants

Name	Description
`Prepare(PrepareError)`	The candidate could not be prepared.
`Stale(StaleCandidate)`	The registry state did not match.

Implemented traits: Debug, Display, Error

Fetch

crates/core/kernel/src/lib.rs#L2016

A Field’s words on their way: Runtime::fetch.

Variants

Name	Description
`Here(FieldData)`	In Host memory already.
`Coming { schema: Schema, domain: Domain, coming: Box<dyn Downloading> }`	Coming from a device.

Methods

Function	Description
`fn take(self) -> Result<FieldData, ExecutionError>`	The Field’s words, once they have come.