entelechy-hostGenerated

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

Brief

Entelechy Host Core: primitive resources with explicit ownership and budgets

Description

Host Core (L1).

The Host owns primitive resources and hands out opaque handles; it holds no product logic. Every resource has one owner, an explicit budget, and a handle that is invalid after release.

The one resource is a Field: a Domain of elements laid out by a Schema. A Kernel sees one 32-bit word per scalar (two for a 64-bit one); memory may keep a scalar narrower (Encoding). An image is a grid of four-float elements; the pixel helpers are views of it.


Internal dependencies	—
External dependencies	—
Source	`crates/core/host`

Modules

Name	Brief
`encoding`	How a scalar is kept in memory. A Kernel computes in 32-bit words; a Field may keep a scalar narrower, widened on read and narrowed on write. An encoding is storage only.

Structs

Name	Brief
`Handle`	Opaque handle to a Host-owned Field, images included. Its generation keeps a released slot out of reach of stale copies.
`Schema`	The flattened element layout of a Field: scalars in declaration order, each with its encoding. Names live in the declaring Kernel.
`FieldData`	Elements laid out by a `Schema` over a `Domain`, first axis fastest. Storage holds Kernel words for a wide schema, packed scalars for a narrow one.
`Image`	A dense row-major RGBA float grid: the pixel view of a Field at observation boundaries (files, windows, tests).
`Pages`	Pages of a Field’s storage, a bit each: those a Field made from another holds different words in.
`Version`	A Field’s words as they were between two writes in place: what a Field made from another, or a buffer kept after a release, names as what it holds. A Field written in place has a new version, so nothing takes the words it held before for the words it holds.
`MadeFrom`	What a Field was made from: other words, and the storage words, page by page, it may differ from them on.
`FieldBytes`	Where one Field’s bytes are (`Host::field_bytes`).
`Census`	Where the memory the Host holds is (`Host::census`).
`Host`	The Host: a bounded store of primitive resources, and a bound on the compute one run may spend.

Enumerations

Name	Brief
`encoding::Encoding`	How one scalar is kept. `Encoding::Word` is the Kernel’s own 32-bit word; the others are narrower.
`Scalar`	What one word of an element is to a Kernel. `Double` and `Long` words come in pairs, low first, and are kept whole; the 32-bit kinds may be kept narrower (`Encoding`).
`Shape`	How a Field’s elements are addressed: a dense lattice a Kernel maps over. Irregular data is rows plus indices.
`Domain`	The extent of a Field. Every side is at least one.
`HostError`	Errors reported by the Host. The Host never silently clamps, recovers, or reallocates.

Functions

Function	Brief
`fn load(storage: &[u32], byte: usize, bytes: usize) -> u32`	The `bytes` stored at byte `byte` of `storage`, in the low bits; they lie within one word.
`fn store(storage: &mut [u32], byte: usize, bytes: usize, bits: u32)`	Stores the low `bytes` of `bits` at byte `byte` of `storage`, keeping the other bytes of its word.
`fn f16_to_f32(h: u32) -> u32`	A half float’s bits to a float’s, exactly.
`fn f32_to_f16(x: u32) -> u32`	A float’s bits to a half float’s: to nearest, ties to even; overflow is infinity, underflow a signed zero, NaN a quiet NaN.

Constants

Name	Type	Value	Brief
`encoding::UNORM8`	`f32`	`_`	The reciprocals a normalized integer is read back through, as `f32` constants every backend spells by their bits.
`encoding::UNORM16`	`f32`	`_`	See `UNORM8`.
`encoding::SNORM8`	`f32`	`_`	See `UNORM8`.
`MAX_ELEMENTS`	`usize`	`_`	The most elements one Field holds: every element’s index is an `Int`, as `element()` gives it, on every backend.
`PAGE_WORDS`	`usize`	`4096`	Words a page of a Field’s storage holds: the unit in which a Field made from another says what changed (`Host::adopt_derived`).
`DEFAULT_WORK`	`u64`	`4_000_000_000`	The default loop iterations of one Kernel run, all elements together.
`MAX_WORK`	`u64`	`_`	The most loop iterations a Host may let one run take.

Type aliases

Name	Type	Brief
`Pixel`	`[f32; 4]`	One RGBA pixel with linear float components.

Re-exports

Encoding

Handle

crates/core/host/src/lib.rs#L23

Opaque handle to a Host-owned Field, images included. Its generation keeps a released slot out of reach of stale copies.

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

Schema

crates/core/host/src/lib.rs#L92

The flattened element layout of a Field: scalars in declaration order, each with its encoding. Names live in the declaring Kernel.

Elements are packed little-endian, scalar after scalar and element after element. Every scalar sits at a multiple of its own size, so none crosses a 32-bit word. Shared: a copy is the same layout, at no cost.

Methods

Function	Description
`fn new(scalars: Vec<Scalar>) -> Self`	Builds a schema from scalars in order, each a whole word.
`fn encoded(scalars: Vec<Scalar>, encodings: Vec<Encoding>) -> Result<Self, String>`	Builds a schema whose scalars are kept as `encodings`. Refused when an encoding does not fit its scalar or a scalar would be misaligned.
`fn with_encoding(&self, encoding: Encoding) -> Result<Self, String>`	The same scalars, every one kept as `encoding`.
`fn pixel() -> Self`	The layout of a pixel: four floats.
`fn scalars(&self) -> &[Scalar]`	The scalars in order, as a Kernel sees them.
`fn encodings(&self) -> &[Encoding]`	How each scalar is kept.
`fn offsets(&self) -> &[usize]`	Each scalar’s byte offset within an element.
`fn uniform_encoding(&self) -> Option<Encoding>`	The one encoding every scalar is kept in, when there is one.
`fn value_words(&self) -> usize`	Words a Kernel sees per element: one per scalar.
`fn element_bytes(&self) -> usize`	Bytes an element takes in memory.
`fn is_wide(&self) -> bool`	Whether every scalar is kept as a whole word.
`fn storage_words(&self, count: usize) -> usize`	Words of memory `count` elements take, rounded up to a whole word.
`fn load(&self, storage: &[u32], element: usize, scalar: usize) -> u32`	The Kernel’s word for scalar `scalar` of element `element`, widened.
`fn store(&self, storage: &mut [u32], element: usize, scalar: usize, word: u32)`	Narrows `word` into scalar `scalar` of element `element`.
`fn pack(&self, values: &[u32]) -> Vec<u32>`	The memory `count` elements of Kernel words take, narrowed.
`fn unpack(&self, storage: &[u32], count: usize) -> Vec<u32>`	The Kernel’s words of `count` elements kept in `storage`, widened.
`fn is_pixel(&self) -> bool`	Whether elements are pixels: four floats, however they are kept.
`fn is_picture(&self, domain: Domain) -> bool`	Whether a Field of this layout over `domain` is a picture: a Grid of pixels. The one rule for what is shown, read and written as an image; a row or a volume of pixels is not one.
`fn describe(&self) -> String`	The layout for a diagnostic (“four floats kept as unorm8”); `Display` writes the spelling files and the wire carry.

Implemented traits: Clone, Debug, Display, Eq, FromStr, Hash, PartialEq, StructuralPartialEq

FieldData

crates/core/host/src/lib.rs#L533

Elements laid out by a Schema over a Domain, first axis fastest. Storage holds Kernel words for a wide schema, packed scalars for a narrow one.

Methods

Function	Description
`fn new(schema: Schema, domain: Domain) -> Result<Self, HostError>`	A zeroed Field.
`fn from_storage(schema: Schema, domain: Domain, storage: Vec<u32>) -> Result<Self, HostError>`	Wraps existing storage of `Schema::storage_words` length.
`fn from_values(schema: Schema, domain: Domain, values: &[u32]) -> Result<Self, HostError>`	A Field from the Kernel’s words, one per scalar per element, narrowed as the schema says.
`fn from_image(image: Image) -> Self`	A grid of pixels from an image.
`fn schema(&self) -> &Schema`	The element layout.
`fn domain(&self) -> Domain`	The extent.
`fn count(&self) -> u32`	Number of elements.
`fn storage(&self) -> &[u32]`	The memory as kept, as a file or a device holds it.
`fn values(&self) -> Cow<'_, [u32]>`	The Kernel’s words, element after element, widened when narrow.
`fn element(&self, index: u32) -> Result<Cow<'_, [u32]>, HostError>`	The Kernel’s words of one element by linear index.
`fn to_image(&self) -> Result<Image, HostError>`	The pixels of a Field of pixels, as an image of `width` by `height * depth` rows, widened.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Image

crates/core/host/src/lib.rs#L684

A dense row-major RGBA float grid: the pixel view of a Field at observation boundaries (files, windows, tests).

Methods

Function	Description
`fn new(width: u32, height: u32) -> Result<Self, HostError>`	Creates a black, fully transparent image.
`fn from_pixels(width: u32, height: u32, pixels: Vec<Pixel>) -> Result<Self, HostError>`	Wraps existing pixel data of the image’s length.
`fn width(&self) -> u32`	Image width in pixels.
`fn height(&self) -> u32`	Image height in pixels.
`fn pixels(&self) -> &[Pixel]`	Row-major pixel data.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Pages

crates/core/host/src/lib.rs#L843

Pages of a Field’s storage, a bit each: those a Field made from another holds different words in.

Methods

Function	Description
`fn new() -> Self`	No page.
`fn mark(&mut self, word: usize)`	The page of storage word `word` marked.
`fn mark_words(&mut self, first: usize, count: usize)`	The pages of `count` storage words from `first` marked.
`fn is_empty(&self) -> bool`	Whether no page is marked.
`fn add(&mut self, other: &Pages)`	Every page `other` marks marked here too.
`fn count(&self) -> usize`	How many pages are marked.
`fn iter(&self) -> impl Iterator<Item = usize> + '_`	The marked pages, in order.

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

Version

crates/core/host/src/lib.rs#L954

A Field’s words as they were between two writes in place: what a Field made from another, or a buffer kept after a release, names as what it holds. A Field written in place has a new version, so nothing takes the words it held before for the words it holds.

Methods

Function	Description
`fn field(self) -> Handle`	The Field whose words these are.

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

MadeFrom

crates/core/host/src/lib.rs#L962

What a Field was made from: other words, and the storage words, page by page, it may differ from them on.

Properties

Name	Type	Description
`words`	`Version`	The words it was made from.
`changed`	`Vec<Range<usize>>`	The storage words it may differ from them on, a page at a time.

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

FieldBytes

crates/core/host/src/lib.rs#L1005

Where one Field’s bytes are (Host::field_bytes).

Properties

Name	Type	Description
`host`	`u64`	Its words in Host memory: all of them, or a resident one’s kept copy.
`device`	`u64`	Its words on a device.

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

Census

crates/core/host/src/lib.rs#L1014

Where the memory the Host holds is (Host::census).

Properties

Name	Type	Description
`fields`	`u64`	Live Fields.
`host`	`u64`	Bytes of Fields in Host memory only.
`device`	`u64`	Bytes of resident Fields on their devices.
`kept`	`u64`	Bytes resident Fields also keep in Host memory, the words they were uploaded from.
`spare`	`u64`	Bytes of word buffers released Fields left for reuse.

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

Host

crates/core/host/src/lib.rs#L1088

The Host: a bounded store of primitive resources, and a bound on the compute one run may spend.

Methods

Function	Description
`fn new(budget_words: usize) -> Self`	Creates a Host holding at most `budget_words` live words; a pixel is four words.
`fn work(&self) -> u64`	The loop iterations one Kernel run may take, all elements together; it keeps a run from holding a device until a driver resets it.
`fn set_work(&mut self, iterations: u64)`	Sets `Host::work`, clamped to `1..=MAX_WORK`.
`fn live(&self) -> usize`	Number of live resources, resident ones included.
`fn resident_count(&self) -> usize`	Number of live resources whose words are on a device.
`fn used_words(&self) -> usize`	Words currently allocated.
`fn field_bytes(&self, handle: Handle) -> Result<FieldBytes, HostError>`	Where a live Field’s bytes are: in Host memory, on a device, or both (a resident Field keeps the words it was uploaded from).
`fn census(&self) -> Census`	Every live Field’s bytes, and the Host’s spare buffers’: where the memory the Host holds is.
`fn budget_words(&self) -> usize`	Total word budget.
`fn create(&mut self, schema: Schema, domain: Domain) -> Result<Handle, HostError>`	Allocates a zeroed Field.
`fn create_for_fill(&mut self, schema: Schema, domain: Domain) -> Result<Handle, HostError>`	A Field whose words are whatever its buffer holds, for a backend that writes every word before any is read, as a map over a domain does.
`fn adopt(&mut self, data: FieldData) -> Result<Handle, HostError>`	Takes ownership of existing data.
`fn adopt_resident(&mut self, schema: Schema, domain: Domain, device: Box<dyn Any + Send + Sync>) -> Result<Handle, HostError>`	Takes ownership of a Field whose words are on a device; `device` is what the owning backend needs to find them.
`fn create_image(&mut self, width: u32, height: u32) -> Result<Handle, HostError>`	Allocates a black image: a grid of pixels.
`fn adopt_image(&mut self, image: Image) -> Result<Handle, HostError>`	Takes ownership of an image as a grid of pixels.
`fn can_hold(&self, fields: &[(&Schema, Domain)]) -> Result<(), HostError>`	Whether Fields of these schemas over these domains fit the budget now; a backend allocating elsewhere asks this first.
`fn reserve(&mut self, fields: &[(&Schema, Domain)]) -> Result<usize, HostError>`	Sets aside room for Fields of these schemas over these domains held elsewhere (another Host, on another thread) and answers the words set aside. The budget counts them with this Host’s Fields until `Host::unreserve`.
`fn unreserve(&mut self, words: usize)`	Gives back words `Host::reserve` set aside.
`fn schema(&self, handle: Handle) -> Result<&Schema, HostError>`	The element layout, resident or not.
`fn domain(&self, handle: Handle) -> Result<Domain, HostError>`	The extent, resident or not.
`fn image_size(&self, handle: Handle) -> Result<(u32, u32), HostError>`	Width and height, resident or not; a volume reports its first two.
`fn data(&self, handle: Handle) -> Result<&FieldData, HostError>`	Borrows the data behind a handle; fails with `HostError::Resident` when its words are on a device only.
`fn element(&self, handle: Handle, index: u32) -> Result<Cow<'_, [u32]>, HostError>`	The Kernel’s words of one element by linear index, widened.
`fn storage_mut(&mut self, handle: Handle) -> Result<&mut [u32], HostError>`	A Field’s storage as kept, to write in place: a backend fills a new Field here.
`fn write_storage(&mut self, handle: Handle, storage: &[u32]) -> Result<(), HostError>`	Replaces the whole storage, as kept; the length must match.
`fn write_values(&mut self, handle: Handle, values: &[u32]) -> Result<(), HostError>`	Replaces every element with the Kernel’s words, one per scalar per element, narrowed as kept.
`fn write_element(&mut self, handle: Handle, index: u32, words: &[u32]) -> Result<(), HostError>`	Replaces one element with the Kernel’s words, narrowed as kept.
`fn resident(&self, handle: Handle) -> Result<Option<&dyn Any + Send + Sync>, HostError>`	The device object of a resident Field; `None` in Host memory.
`fn make_resident(&mut self, handle: Handle, device: Box<dyn Any + Send + Sync>) -> Result<(), HostError>`	Gives a Field’s words a copy on a device, `device`, which the Host keeps beside its own. Layout, extent and identity stay.
`fn materialize(&mut self, handle: Handle, words: Vec<u32>) -> Result<(), HostError>`	Brings a resident Field’s downloaded words into Host memory beside the device’s, which stay: the two are one value, and what the device holds can still be drawn from it. A Field in memory stays as it is.
`fn let_go_of_copy(&mut self, handle: Handle) -> Result<u64, HostError>`	Lets go of the Host copy a resident Field keeps of its words; the device’s stay, and `Host::materialize` brings them back when something on the processor reads them. Answers the bytes let go.
`fn release(&mut self, handle: Handle) -> Result<(), HostError>`	Releases a Field, resident or not. The handle is invalid afterwards.
`fn working(&mut self, handle: Handle) -> Result<Vec<u32>, HostError>`	A copy of a Field’s words to write in place, as a scan’s memory is, made from a released buffer where one holds words it differs from on known pages alone, those pages copied in: the buffer of the words the Field was made from, of a Field made from the Field, or of one made from the same words; else a buffer of the Field’s words copied whole.
`fn adopt_derived(&mut self, data: FieldData, base: Handle, changed: Pages) -> Result<Handle, HostError>`	Takes ownership of `data`, made from Field `base`’s words but on the pages `changed`: kept as known, so its words are copied and compared a page at a time. Where `base` is gone or of another size it is adopted as any Field.
`fn version(&self, handle: Handle) -> Result<Version, HostError>`	A live Field’s words as they are now.
`fn holds(&self, version: Version) -> bool`	Whether `version` is still what its Field holds.
`fn made_from(&self, handle: Handle) -> Result<Vec<MadeFrom>, HostError>`	The words a Field was made from, nearest first, each with the storage words, page by page, it may differ from them on; none where that is not known.
`fn same(&self, a: Handle, b: Handle) -> Option<bool>`	Whether two Fields in Host memory hold the same words: a Field made from the other is compared on its changed pages alone, two made from the same words on the pages either changed. `None` where either is on a device only.
`fn image(&self, handle: Handle) -> Result<Image, HostError>`	A copy of a Field of pixels as an image. Fails with `HostError::Resident` on a device, `HostError::NotPixels` for other layouts.
`fn read_pixel(&self, handle: Handle, x: u32, y: u32) -> Result<Pixel, HostError>`	Reads one pixel, widened.

… and 1 more; see the source.

encoding::Encoding

crates/core/host/src/encoding.rs#L24

How one scalar is kept. Encoding::Word is the Kernel’s own 32-bit word; the others are narrower.

Variants

Name	Description
`Word`	A whole 32-bit word: `f32`, `i32`, or a `0`/`1` boolean.
`F16`	A float as IEEE half precision.
`Unorm8`	A float in `0..=1` as a byte.
`Snorm8`	A float in `-1..=1` as a signed byte.
`Unorm16`	A float in `0..=1` as 16 bits.
`U8`	An integer or boolean as an unsigned byte.
`I8`	An integer or boolean as a signed byte.
`U16`	An integer or boolean as unsigned 16 bits.
`I16`	An integer or boolean as signed 16 bits.

Methods

Function	Description
`fn name(self) -> &'static str`	The spelling after `as` in a port type, and in a schema’s text.
`fn parse(name: &str) -> Option<Self>`	The encoding a name spells, the narrow ones only.
`fn bytes(self) -> usize`	Bytes one scalar takes.
`fn is_float(self) -> bool`	Whether this encoding keeps floats (as against integers).
`fn fits(self, scalar: Scalar) -> bool`	Whether a scalar of this kind may be kept this way: floats by float encodings, integers and booleans by integer ones, 64-bit scalars only whole.
`fn decode(self, kind: Scalar, bits: u32) -> u32`	The Kernel’s word of `kind` for the stored bits (in the low `bytes()`).
`fn encode(self, word: u32) -> u32`	The stored bits (in the low `bytes()`) for the Kernel’s word.

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

Scalar

crates/core/host/src/lib.rs#L41

What one word of an element is to a Kernel. Double and Long words come in pairs, low first, and are kept whole; the 32-bit kinds may be kept narrower (Encoding).

Variants

Name	Description
`Float`	An `f32`.
`Int`	An `i32`.
`Bool`	A `0` or `1`.
`Double`	One word of an `f64`, low first.
`Long`	One word of an `i64`, low first.

Methods

Function	Description
`fn words(self) -> usize`	Words a scalar of this kind takes.

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

Shape

crates/core/host/src/lib.rs#L405

How a Field’s elements are addressed: a dense lattice a Kernel maps over. Irregular data is rows plus indices.

Variants

Name	Description
`Rows`	One dimension, addressed by an index.
`Grid`	Two dimensions, addressed by a coordinate pair.
`Volume`	Three dimensions, addressed by a coordinate triple.

Methods

Function	Description
`fn name(self) -> &'static str`	Stable spelling used in `.ent` sources.
`fn dims(self) -> u8`	Number of dimensions.

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

Domain

crates/core/host/src/lib.rs#L442

The extent of a Field. Every side is at least one.

Variants

Name	Description
`Rows(u32)`	`count` elements in a row.
`Grid(u32, u32)`	`width` by `height` elements.
`Volume(u32, u32, u32)`	`width` by `height` by `depth` elements.

Methods

Function	Description
`fn shape(self) -> Shape`	The shape.
`fn width(self) -> u32`	Elements along the first axis.
`fn height(self) -> u32`	Elements along the second axis; one for rows.
`fn depth(self) -> u32`	Elements along the third axis; one below a volume.
`fn count(self) -> usize`	Total number of elements, saturating at `usize::MAX` (past `MAX_ELEMENTS`).
`fn is_empty(self) -> bool`	Whether any side is zero.

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

HostError

crates/core/host/src/lib.rs#L742

Errors reported by the Host. The Host never silently clamps, recovers, or reallocates.

Variants

Name	Description
`InvalidHandle(Handle)`	The handle does not refer to a live resource.
`BudgetExceeded { requested: usize, available: usize }`	Allocating the resource would exceed the Host budget.
`OutOfBounds { x: u32, y: u32, width: u32, height: u32 }`	A pixel coordinate lies outside the image.
`ElementOutOfBounds { index: u32, count: u32 }`	An element index lies outside the Field.
`ZeroSize`	Fields must have at least one element and one word per element.
`TooManyElements(Domain)`	The domain holds more than `MAX_ELEMENTS`.
`PixelCount { expected: usize, actual: usize }`	Pixel data length does not match the dimensions.
`WordCount { expected: usize, actual: usize }`	Word data length does not match the domain and schema.
`Resident(Handle)`	The Field’s words are on a device; materialize it first.
`NotPixels`	The Field’s elements are not pixels, so it has no image view.

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