entelechy-irGenerated

Layer: core · Lines of code: 9,437 · Integration test files: 0

Brief

Entelechy IR: typed, SSA-like, backend-neutral Kernel representation

Description

Entelechy IR (L3).

The typed, SSA-like, structured, backend-independent form of a Kernel. Each instruction defines one value and refers only to values defined before it in its block or an enclosing one; control flow is if and bounded loop. Host access is explicit operations, so validation proves a Kernel’s capabilities before it runs.


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

Structs

Name	Brief
`KernelId`	Stable identity of a Kernel, `name@version` (`image.grayscale@1`). Graphs bind to it, never to source paths.
`InvalidKernelId`	The text is not a valid `name@version` Kernel id.
`Port`	A named, typed input or output.
`Param`	A named parameter of any value type, with a default value.
`Manifest`	The stable contract between a Kernel and the runtime.
`ValueId`	Index of a value within a function, assigned in pre-order over its instructions, nested blocks included; also its slot in a flat frame.
`Field`	One field of a struct.
`StructDef`	A Kernel-defined record type. Struct `i` contains only structs below `i`, so none is recursive.
`Block`	A nested block: instructions and the value the block yields.
`PartLayout`	Where a path through an element leads.
`Instruction`	An instruction: a typed value defined by an operation.
`Function`	A function: arguments, a top-level block and results. Function `i` calls only functions below `i`, so none is recursive.
`Module`	A complete compiled Kernel.

Enumerations

Name	Brief
`Mode`	How a Kernel executes over its domain.
`Combine`	How a scattered value combines with the element at its address.
`BinaryOp`	Binary operations on scalars, vectors, and truth values.
`UnaryOp`	Unary operations.
`Intrinsic`	Pure math intrinsics; their signatures are the one source for the compiler, the validator and every backend.
`Op`	One SSA operation. Host access is explicit and named.
`Step`	One step from a whole value towards a part, as `Op::Part` takes it.

Functions

Function	Brief
`fn scalar_kind(ty: Type) -> Option<Scalar>`	The kind of word a value type’s scalars are kept as.
`fn schema_of(ty: Type, structs: &[StructDef]) -> Option<Schema>`	The storage layout of a value type: vectors and structs flattened to scalars in declaration order. `None` for unknown structs.
`fn number_names(ty: Type, structs: &[StructDef]) -> Option<Vec<String>>`	The name of each number an element of type `ty` holds, in the order `schema_of` lays them out: a struct’s fields by name, nested ones joined by a dot; a vector’s lanes `x` to `w`; a matrix’s numbered from 0; a value of one number unnamed (`""`). `None` for unknown structs.
`fn template(ty: Type, structs: &[StructDef]) -> Value`	A value of type `ty` with every word zero.
`fn value_as(value: &Value, ty: Type, structs: &[StructDef]) -> Option<Value>`	`value` retyped as `ty` when their layouts match (see `Number::as_kind`); otherwise `None`.
`fn measure(structs: &[StructDef], ty: Type) -> (usize, usize)`	The parts a value of `ty` holds and how deep its structs nest, each struct in `structs` it reaches within `MAX_VALUE_PARTS` and `MAX_TYPE_DEPTH`.
`fn measure_struct(def: &StructDef, field: &dyn Fn(Type) -> (usize, usize)) -> (usize, usize)`	A struct’s parts and depth, from what `field` measures its fields’ types at; an array’s elements are measured once.
`fn too_large((parts, depth): (usize, usize)) -> Option<String>`	Why a value of `ty` may not be: it holds past `MAX_VALUE_PARTS` or nests past `MAX_TYPE_DEPTH`.
`fn words(structs: &[StructDef], ty: Type) -> usize`	Words a value of this type takes in the flat layout the Host, backends and IR share: a struct’s fields end to end, a matrix’s columns.
`fn part_at(structs: &[StructDef], ty: Type, k: usize) -> Option<(usize, Type)>`	Where part `k` (struct field, matrix column or vector component) of a value of this type begins and its type, as `Op::Extract` takes it.
`fn elements_of(structs: &[StructDef], ty: Type) -> Option<(Type, usize, usize)>`	The part type, count and word stride of an indexed value of this type, as `Op::Subscript` takes them, clamping the index into `0..count`.
`fn part_layout(structs: &[StructDef], element: Type, path: &[Step]) -> Option<PartLayout>`	Where a path through an element of this type leads; `None` when the path does not fit the type.
`fn loop_looks(count: u32, until: Option<&Block>, body: &Block, functions: &[u64]) -> bool`	Whether a loop of `count` iterations checks its element’s work at each iteration; `functions` is `Module::functions_work`. See `LOOK_WORK`.

Constants

Name	Type	Value	Brief
`IR_VERSION`	`u32`	`1`	The IR version, raised when a module’s validity or meaning changes.
`MAX_GROUP`	`u32`	`256`	The most lanes a group holds: what every device runs together.
`MAX_ARRAY_COUNT`	`u32`	`4096`	Largest element count an array type may declare.
`MAX_VALUE_PARTS`	`usize`	`_`	The most parts a value may hold: its words and the structs and arrays around them. Every walk over a value’s type is bounded by it.
`MAX_TYPE_DEPTH`	`usize`	`64`	The deepest structs and arrays may nest in a type.
`MAX_LOOP_COUNT`	`u32`	`65_536`	Largest iteration bound a `loop` may write: a literal count, and an `[each]`’s. A count read at run time is bounded by `MAX_BUDGET` instead, so the element’s work budget is what stops it.
`DEFAULT_BUDGET`	`u32`	`_`	The default work budget: loop iterations an element may run.
`MAX_BUDGET`	`u32`	`_`	The largest work budget a Kernel may declare.
`WORK_BLOCK`	`u32`	`1024`	The loop iterations an element adds to its run’s total at a time. The total counts whole blocks: one shared addition per block, and a Kernel whose elements cannot fill one is not counted.
`TYPICAL_OPEN_LOOP`	`u32`	`4`	The iterations `Module::typical_work` counts for a loop whose count is read at run time or that may stop early.
`LOOK_WORK`	`u64`	`_`	The most iterations one run of a loop, nested ones included, may take while its work is checked only at its end. A loop that can run more also checks at the start of each iteration, so an element runs at most this far past a bound. An innermost loop costs one addition.

Re-exports

NamedManifest, port_type_name, type_name, Carried, Sizes, carried, sizes, Renumbering, account, account_renumbered, Capabilities, Capability, Encoding, Number, PortType, Scalar, Schema, Shape, ShapeIndex, Type, Value, FuseError, InputUse, counted, counts_only, extent_params, fuse, fuse_indexed, fuse_outputs, fused_name, input_use, offset_read, samples_only, group_fault, lanes, carried_builders, optimize, renumbered, Validated, ValidationError, linear_index_type, validate

KernelId

crates/core/ir/src/lib.rs#L44

Stable identity of a Kernel, name@version (image.grayscale@1). Graphs bind to it, never to source paths.

Methods

Function	Description
`fn new(name: &str, version: u32) -> Result<Self, InvalidKernelId>`	Builds an id from its parts, checking the name shape.
`fn name(&self) -> &str`	The dotted name without the version.
`fn version(&self) -> u32`	The version.

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

InvalidKernelId

crates/core/ir/src/lib.rs#L88

The text is not a valid name@version Kernel id.

Properties

Name	Type	Description
`0`	`String`

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

Port

crates/core/ir/src/lib.rs#L118

A named, typed input or output.

Properties

Name	Type	Description
`name`	`String`	Port name.
`ty`	`PortType`	What the port carries.

Methods

Function	Description
`fn element(&self) -> Type`	The element type the entry produces or `sample` yields for this port.
`fn shape(&self) -> Shape`	How the port’s elements are addressed.

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

Param

crates/core/ir/src/lib.rs#L212

A named parameter of any value type, with a default value.

Properties

Name	Type	Description
`name`	`String`	Parameter name.
`ty`	`Type`	Its type: any value type, the module’s structs and arrays included.
`default`	`Value`	Default value, of that type.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Manifest

crates/core/ir/src/lib.rs#L265

The stable contract between a Kernel and the runtime.

Properties

Name	Type	Description
`id`	`KernelId`	Kernel identity.
`mode`	`Mode`	How the Kernel executes.
`requires`	`Capabilities`	Capabilities the Kernel declares.
`inputs`	`Vec<Port>`	Inputs in declaration order.
`params`	`Vec<Param>`	Parameters in declaration order.
`outputs`	`Vec<Port>`	Outputs in declaration order.
`memories`	`Vec<String>`	Names of the memories: ports in both `inputs` (bound by the graph, read with `at`) and `outputs`, which an ordered Kernel writes step by step with `Op::Put`. They come last in both lists, in one order.
`budget`	`u32`	Loop iterations one element (a scan step, a reduction merge) may run, nested loops included; past it the element fails on every backend. See `Module::counts_work`.

Methods

Function	Description
`fn named<'a>(self: &'a Self, structs: &'a [StructDef]) -> NamedManifest<'a>`	The manifest printed with a module’s struct names.

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

ValueId

crates/core/ir/src/lib.rs#L419

Index of a value within a function, assigned in pre-order over its instructions, nested blocks included; also its slot in a flat frame.

Properties

Name	Type	Description
`0`	`u32`

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

Field

crates/core/ir/src/lib.rs#L935

One field of a struct.

Properties

Name	Type	Description
`name`	`String`	Field name.
`ty`	`Type`	Field type: plain, or an earlier struct in the table.

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

StructDef

crates/core/ir/src/lib.rs#L948

A Kernel-defined record type. Struct i contains only structs below i, so none is recursive.

An array [T; N] is a struct of N fields of type T named 0 to N - 1, with element set to T; Op::Subscript also indexes it.

Properties

Name	Type	Description
`name`	`String`	Name for inspection and diagnostics; an array’s is `[T; N]`.
`fields`	`Vec<Field>`	Fields in declaration order.
`element`	`Option<Type>`	The element type when the struct is an array.

Methods

Function	Description
`fn record(name: impl Into<String>, fields: Vec<Field>) -> Self`	A named record.
`fn array(element: Type, element_name: &str, count: u32) -> Self`	The array `[element; count]`, named by the element’s spelling.
`fn is_array(&self) -> bool`	Whether the struct is an array, and of what.

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

Block

crates/core/ir/src/lib.rs#L1100

A nested block: instructions and the value the block yields.

Properties

Name	Type	Description
`body`	`Vec<Instruction>`	Instructions in order.
`result`	`ValueId`	The value the block yields; defined in the block or an enclosing one.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

PartLayout

crates/core/ir/src/lib.rs#L1385

Where a path through an element leads.

Properties

Name	Type	Description
`base`	`usize`	The words before the part that are known without running.
`steps`	`Vec<(ValueId, usize, usize)>`	The index steps resolved at run time: each index’s value, choice count and word stride.
`ty`	`Type`	What the path names.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Instruction

crates/core/ir/src/lib.rs#L1420

An instruction: a typed value defined by an operation.

Properties

Name	Type	Description
`id`	`ValueId`	The value this instruction defines; its pre-order position.
`ty`	`Type`	The type of the defined value.
`op`	`Op`	How the value is computed.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Function

crates/core/ir/src/lib.rs#L1432

A function: arguments, a top-level block and results. Function i calls only functions below i, so none is recursive.

Properties

Name	Type	Description
`name`	`String`	Name for inspection and diagnostics.
`args`	`Vec<Type>`	Argument types.
`body`	`Vec<Instruction>`	Top-level instructions.
`results`	`Vec<ValueId>`	Values returned, in order.
`bindings`	`Vec<(ValueId, String)>`	The `let` bindings in source order with the values they name, for inspection and traces; they carry no meaning.

Methods

Function	Description
`fn slot_count(&self) -> usize`	Number of value slots the function defines, nested blocks included.
`fn type_of(&self, id: ValueId) -> Option<Type>`	The type of the instruction defining `id` at any depth; `None` for an argument or a value the function lacks.
`fn result_type(&self) -> Type`	The type of the first result, as a caller receives it; `Float` when no instruction defines it.
`fn any_type(&self, holds: &dyn Fn(Type) -> bool) -> bool`	Whether any argument or computed value matches `holds`.

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

Module

crates/core/ir/src/lib.rs#L1693

A complete compiled Kernel.

Properties

Name	Type	Description
`manifest`	`Manifest`	The manifest.
`structs`	`Vec<StructDef>`	Struct types in dependency order.
`functions`	`Vec<Function>`	Helper functions in dependency order.
`entry`	`Function`	The entry point, executed once per element (of the output’s domain in `Mode::Map`, of the first input’s in `Mode::Reduce`). Its results map to `manifest.outputs` in order.
`merge`	`Option<Function>`	In `Mode::Reduce`, the fold: `(T, T) -> T` over the entry’s result type `T`. Present exactly when the mode is `Reduce`.
`init`	`Option<Function>`	In `Mode::Scan`, the carried value before the first element: `() -> T`. Present exactly when the mode is `Scan`.

Methods

Function	Description
`fn worst_work(&self) -> u64`	The most loop iterations one element can run: every loop at its bound (`MAX_LOOP_COUNT` for a run-time count), nested loops multiplied, the longer branch arm, calls counted where made. Saturates.
`fn typical_work(&self) -> u64`	The operations one element takes as a rule, at least one: each instruction one; a loop of a written count runs its body that many times, one whose count is read at run time, or that may stop early, `TYPICAL_OPEN_LOOP` times at most, and one counting rounds of the loop limit once; the longer branch arm; a call what its function takes. An estimate of size, for choosing where a run goes, never a bound.
`fn typical_work_given(&self, params: &[Value]) -> u64`	`Module::typical_work` for a run given `params`: a loop that counts a parameter, and does not stop early, runs its body that parameter’s value of times, clamped to its bound.
`fn typical_reads_params(&self) -> bool`	Whether a run’s `Module::typical_work_given` depends on its parameters: some loop counts one.
`fn accounted(&self) -> bool`	Whether `account()` has placed the module’s work checks.
`fn functions_work(&self) -> Vec<u64>`	For each function, the most loop iterations one call may run.
`fn counts_work(&self) -> bool`	Whether a backend counts this module’s work as it runs: only when its worst case can pass its budget or fill a `WORK_BLOCK`.
`fn holds(&self, scalar: Type) -> bool`	Whether any port, parameter, struct field or computed value is made of `scalar`.

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

Mode

crates/core/ir/src/lib.rs#L290

How a Kernel executes over its domain.

Variants

Name	Description
`Map`	The entry runs once per element of the output domain.
`Reduce`	The entry runs per element of the first input; `merge` folds the results pairwise into the single element of a `Rows` output. `merge` is associative and commutative: the backend picks the fold’s tree.
`Scan`	The entry runs per row of the first input, in order, reading the previous result through `Op::Carried` (`init` before the first) and writing each result to that element of a `Rows` output.
`Scatter { base: u32, combine: Combine }`	The entry runs per element of the first input, yielding an address into `base` and a value. The output is `base` with each value combined into its address as if applied in element order; under `Combine::Sum` an integer is the element’s whole total. Addresses outside `base` are dropped; `base` has the output’s shape and layout.
`Prefix { combine: Combine }`	The entry runs per row of the first input; each element of the `Rows` output is its value combined by `Combine` with every value before it (an inclusive prefix fold). The rule is order-free (integer `sum`, `min`, `max`), so any grouping gives the reference’s words.
`Group { size: u32 }`	The entry runs once per element of the output domain, as a map does, the elements in groups of `size` (by linear index: element `e` is lane `e % size` of group `e / size`). Lanes of a group hand each other values through `Op::Exchange`, which every lane reaches alike; a group past the domain’s end runs whole, and its lanes past the end write nothing.

Methods

Function	Description
`fn name(self) -> &'static str`	Stable spelling used in manifests.

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

Combine

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

How a scattered value combines with the element at its address.

Variants

Name	Description
`Sum`	Fieldwise addition. A float adds in element order; an integer is the element’s whole total and fails, at the first element, only when that total overflows (`entelechy_rules::Sums`).
`Min`	Fieldwise minimum.
`Max`	Fieldwise maximum.
`Last`	The value replaces the element; the last source in element order wins.

Methods

Function	Description
`fn name(self) -> &'static str`	Stable spelling used in `.ent` sources.
`fn parse(name: &str) -> Option<Self>`	The spelling’s meaning, if it is one.
`fn order_free(self, element: Type, structs: &[StructDef]) -> bool`	Whether the rule’s answer over `element` is independent of pair order: `min` and `max` always, `sum` when no scalar is a float. Only such a rule takes pairs a scatter emits.

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

BinaryOp

crates/core/ir/src/lib.rs#L429

Binary operations on scalars, vectors, and truth values.

Variants

Name	Description
`Add`	`a + b`
`Sub`	`a - b`
`Mul`	`a * b`
`Div`	`a / b`
`Rem`	`a % b`: the remainder with the sign of `a`, as `/` truncates.
`Less`	`a < b`
`LessEqual`	`a <= b`
`Greater`	`a > b`
`GreaterEqual`	`a >= b`
`Equal`	`a == b`
`NotEqual`	`a != b`
`And`	`a && b`
`Or`	`a \|\| b`
`BitAnd`	`a & b` on integers.
`BitOr`	`a \| b` on integers.
`BitXor`	`a ^ b` on integers.
`Shl`	`a << b` on integers; the count is taken modulo 32.
`Shr`	`a >> b` on integers, arithmetic; the count is taken modulo 32.
`Ushr`	`a >>> b` on integers, logical; the count is taken modulo 32.

Methods

Function Description

fn result_type(self, a: Type, b: Type) -> Option<Type> Result type of a op b, or None when the operands cannot combine. Both sides share one scalar kind (Float/Double and Int/Long meet only through a conversion). Vectors combine componentwise with same-size vectors or a scalar of their kind. Matrices add and subtract with their own order and scale by a scalar; the compiler writes their products out. Comparisons take two scalars of one type and give Bool; equality also compares Bools and whole vectors and matrices. && and || take Bools. Bit operators and shifts take integers of either width and integer vectors, a scalar broadcasting.

fn symbol(self) -> &'static str Source spelling.

Function	Description
`fn result_type(self, a: Type, b: Type) -> Option<Type>`	Result type of `a op b`, or `None` when the operands cannot combine. Both sides share one scalar kind (`Float`/`Double` and `Int`/`Long` meet only through a conversion). Vectors combine componentwise with same-size vectors or a scalar of their kind. Matrices add and subtract with their own order and scale by a scalar; the compiler writes their products out. Comparisons take two scalars of one type and give `Bool`; equality also compares `Bool`s and whole vectors and matrices. `&&` and `\|\|` take `Bool`s. Bit operators and shifts take integers of either width and integer vectors, a scalar broadcasting.
`fn symbol(self) -> &'static str`	Source spelling.

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

UnaryOp

crates/core/ir/src/lib.rs#L558

Unary operations.

Variants

Name	Description
`Neg`	`-a` on numbers and vectors.
`Not`	`!a` on truth values.

Methods

Function	Description
`fn result_type(self, a: Type) -> Option<Type>`	Result type, or `None` when the operand does not fit.

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

Intrinsic

crates/core/ir/src/lib.rs#L579

Pure math intrinsics; their signatures are the one source for the compiler, the validator and every backend.

Variants

Name	Description
`Floor`	Largest integer value not greater than the input, componentwise.
`Ceil`	Smallest integer value not less than the input, componentwise.
`Round`	Nearest integer, ties to even, componentwise.
`Sign`	-1, 0, or 1 by the sign, componentwise; `Int` stays `Int`.
`Log`	Natural logarithm, componentwise.
`Tan`	Tangent, componentwise.
`Asin`	Arc sine, componentwise.
`Acos`	Arc cosine, componentwise.
`Atan`	Arc tangent of one value, componentwise; `atan2` takes two.
`Fract`	Fractional part, componentwise.
`Abs`	Absolute value, componentwise.
`Sqrt`	Square root, componentwise.
`Sin`	Sine, componentwise.
`Cos`	Cosine, componentwise.
`Min`	Componentwise minimum; a `Float` beside a vector broadcasts.
`Max`	Componentwise maximum; a `Float` beside a vector broadcasts.
`Clamp`	`clamp(x, low, high)` componentwise; `Float` bounds broadcast.
`Mix`	`mix(a, b, t)` linear interpolation, `t` a `Float` or componentwise.
`AddWrap`	`add_wrap(a, b)` on `Int`s: the sum modulo 2^32, never a failure.
`SubWrap`	`sub_wrap(a, b)` on `Int`s: the difference modulo 2^32.
`MulWrap`	`mul_wrap(a, b)` on `Int`s: the low 32 bits of the product.
`ToFloat`	Convert `Int` or `Bool` (as 0 or 1) to `Float`.
`ToInt`	Convert `Float` (truncating toward zero) or `Bool` (as 0 or 1) to `Int`.
`ToDouble`	Convert any number, or a `Bool` as 0 or 1, to `Double`.
`ToLong`	Convert any number (floats truncating) or `Bool` (0 or 1) to `Long`.
`Pow`	`pow(base, exponent)` componentwise; a `Float` exponent broadcasts.
`Exp`	`e^x` componentwise.
`Step`	`step(edge, x)`: 1 where `x >= edge`, else 0; a `Float` edge broadcasts.
`Smoothstep`	`smoothstep(low, high, x)` componentwise; `Float` edges broadcast.
`Atan2`	`atan2(y, x)` on floats.
`Trunc`	The integer part, toward zero, componentwise.
`Exp2`	2 raised to x, componentwise.
`Log2`	The base-2 logarithm, componentwise.
`Sinh`	The hyperbolic sine, componentwise.
`Cosh`	The hyperbolic cosine, componentwise.
`Tanh`	The hyperbolic tangent, componentwise.
`Fma`	`fma(a, b, c)`: a * b + c rounded once, componentwise.
`Popcount`	The count of one bits of an Int.
`Clz`	The count of leading zero bits of an Int, 32 for zero.
`Ctz`	The count of trailing zero bits of an Int, 32 for zero.
`Rotl`	`rotl(x, n)`: the bits rotated left by n modulo 32.
`Rotr`	`rotr(x, n)`: the bits rotated right by n modulo 32.
`Ult`	`ult(a, b)`: whether a is below b as unsigned 32-bit values.
`Udiv`	`udiv(a, b)`: the unsigned quotient; a zero divisor is a failure.
`Urem`	`urem(a, b)`: the unsigned remainder; a zero divisor is a failure.
`Mulhi`	`mulhi(a, b)`: the high 32 bits of the signed 64-bit product.
`Umulhi`	`umulhi(a, b)`: the high 32 bits of the unsigned 64-bit product.
`Bits`	`bits(x)`: a Float’s 32 bits as an Int, unchanged.
`FromBits`	`from_bits(x)`: an Int’s 32 bits as a Float, unchanged.

Methods

Function	Description
`fn name(self) -> &'static str`	Source spelling.
`fn describe(self) -> &'static str`	One sentence on what the intrinsic computes, for `help`.
`fn argument_names(self) -> &'static [&'static str]`	The names of the arguments, for `help`.
`fn from_name(name: &str) -> Option<Self>`	Looks up an intrinsic by source name.
`fn result_type(self, args: &[Type]) -> Option<Type>`	Result type for the argument types, or `None` if ill-typed.

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

Op

crates/core/ir/src/lib.rs#L1167

One SSA operation. Host access is explicit and named.

Variants

Name	Description
`Const(Value)`	A literal.
`Param(u32)`	The Kernel parameter at the given manifest index.
`Arg(u32)`	The current function’s argument at the given index.
`Unary(UnaryOp, ValueId)`	Unary operation.
`Binary(BinaryOp, ValueId, ValueId)`	Binary operation.
`Construct(Vec<ValueId>)`	Build a vector, integer vector, matrix (from columns) or struct (from fields); the instruction type says which.
`Extract(ValueId, u32)`	Extract a vector component, matrix column, struct field or array element at a constant index.
`Subscript(ValueId, ValueId)`	The element of an array, the column of a matrix or the component of a vector at an `Int` index, clamped into range.
`Call(u32, Vec<ValueId>)`	Call a Kernel-defined function by index with arguments.
`Intrinsic(Intrinsic, Vec<ValueId>)`	A pure intrinsic.
`If { condition: ValueId, then: Block, otherwise: Block }`	Yield `then` or `otherwise` by a `Bool`; only the taken block runs.
`Match { scrutinee: ValueId, arms: Vec<(Vec<i32>, Block)>, otherwise: Block }`	Yield the arm whose values hold the `Int` `scrutinee`, else `otherwise`; only that block runs. No value appears in two arms.
`Loop { count: u32, bound: Option<ValueId>, init: ValueId, until: Option<Block>, body: Block }`	Run `body` at most `count` times, threading one carried value from `init`: each iteration reads it through `Op::Carried` and yields its replacement. `until`, tested on the carried value before each iteration, stops the loop when it holds. Yields the final value.
`Each { count: u32, body: Block }`	Build an array of `count` elements: `body` runs once for each, in order, `Op::Index` its position, and yields that element. An `[each]` not written out: its runs are not loop iterations, and count as no work but what their own loops do.
`Carried`	The carried value of the innermost enclosing loop (an `Op::Each` carries none), or, outside any loop in a scan’s entry, the scan’s carried value.
`Index`	The iteration index of the innermost enclosing loop or position of the innermost enclosing `Op::Each` as `Int`, or, outside both in a scan’s entry, the element index.
`Coord`	The current element’s coordinate: `Vec2` over a grid, `Vec3` over a volume; rows have `element()` instead. Entry point only.
`Domain`	The output domain’s extent: `Int` for rows, `Vec2` for a grid, `Vec3` for a volume. Entry point only.
`Time`	Session time in seconds as `Float`, the clock rounded to it. Context: `time.read`.
`Clock`	Session time in seconds as `Double`, the clock whole. Context: `time.read`.
`Rate`	The sound device’s clock in samples per second as `Float`, zero without a device. Context: `time.read`.
`Queued`	The samples (per channel) the sound device holds and has not yet played, as `Int`, zero without a device. Context: `time.read`.
`Pointer`	Pointer position in output pixels as `Vec2`. Context: `input.read`.
`PointerDown`	Whether the pointer button is held, as `Bool`. Context: `input.read`.
`Button(ValueId)`	Whether the pointer button with the given `Int` number is held, as `Bool`: 0 left, 1 right, 2 middle. Context: `input.read`.
`Wheel`	What the wheel scrolled since the last evaluation, as `Vec2`. Context: `input.read`.
`Pads`	How many pads are connected, as `Int`. Context: `input.read`.
`Stick(ValueId)`	A pad’s axis pair by number as `Vec2`: 0 left stick, 1 right, 2 the triggers. Sticks run `-1..1` (`y` away from the person), triggers `0..1`; zero without a pad. Context: `input.read`.
`Window`	The window’s size in physical pixels as `Vec2`, zero by zero without a window. Context: `input.read`.
`Scale`	The window’s scale factor, physical pixels per logical pixel, as `Float`; one without a window. Context: `input.read`.
`Key(ValueId)`	Whether the key with the given `Int` code is held, as `Bool`. Context: `input.read`.
`Typed(ValueId)`	The character typed since the last evaluation at the given `Int` place, as an `Int` code point; 0 after the last. Context: `input.read`.
`Element`	The current element’s linear index as `Int`. Entry point only.
`Lane`	The current element’s place in its group, `0` to the group’s size less one, as `Int`. A group’s entry only.
`Exchange(ValueId, ValueId)`	The value (the first operand) lane `lane` of this group gave at this point, the lane wrapped round the group’s size: every lane gives its own and takes another’s, so no two write one place. Every lane reaches it alike (its control flow depends on nothing a lane holds alone), in a group’s entry only, and in no function it calls.
`Sample(u32)`	The element of an input at the current coordinate, clamped to the input’s extent, as its element type. The input’s shape must match the output’s. Host call: `field.read`. Entry point only.
`At(u32, ValueId)`	The element of an input at an address of the input’s index type (`Int`, `Vec2`, or `Vec3`; clamped), as its element type. Host call: `field.read`.
`Part { input: u32, at: Option<ValueId>, path: Vec<Step> }`	Part of one input element, named by a path; a backend reads only the words it names. The element is the one at the address, as `Op::At` takes it, or else this element’s own, as `Op::Sample` reads it (entry point only). Host call: `field.read`.
`AtLinear(u32, ValueId)`	The input element at an address of its index type, interpolated linearly (bilinear on a grid, trilinear on a volume; clamped at the edges). All-float layouts only. Host call: `field.read`.
`Count(u32)`	Number of elements of an input as `Int`. Host call: `field.read`.
`Size(u32)`	Extent of an input as its index type. Host call: `field.read`.
`Put(u32, ValueId, ValueId)`	Writes a value into a memory input at an address of its index type, in step order; later reads see it, an address outside is dropped. Yields the value. Host call: `field.write`. Ordered Kernel entry only.
`Emit(ValueId)`	Emits one more scatter pair (target address, element value), laid out as the pair the entry returns. An element’s pairs are those it emits, in order, then the one it returns; an address outside the target is dropped. Yields the pair. Host call: `field.write`. Only in a scatter’s entry and its callees, under an order-free rule.
`Spend(ValueId)`	Adds the body iterations of the loop just before it (the operand) to the element’s work and yields them as `Int`. Placed only by `account()`; see `Module::worst_work`.
`Look`	Checks the element’s work, as `Bool`: `true` (a failure, recorded where seen; the element stops its loops) once it passes its Kernel’s budget or its run the Host’s bound. Otherwise hands the run’s total the `WORK_BLOCK`s filled since the last check. Placed only by `account()`.
`Lanes { body: Block }`	Runs `body` once for each lane of the group, in lane order, as that lane: its element, place, reads, `Op::Lane`, work and failures are the lane’s. Yields the array of the lanes’ results. A lane that fails is held, the lowest one held, until the next `Op::Meet`, and runs no more. Not a loop: `Op::Index` and `Op::Carried` in it are those of the loop around it. Placed only by `lanes()`.
`Meet(Option<ValueId>)`	The end of a stretch of the group between exchanges: once a lane has failed, the run fails here with the lowest lane held. At an exchange, the operand is the array of what the lanes give there, for a trace to answer a lane’s exchanges from; at the entry’s end there is none. Yields `Bool` `true`. Placed only by `lanes()`.

Methods

Function	Description
`fn blocks(&self) -> Vec<&Block>`	The blocks the op carries, in order: an `if`’s two, a `match`’s arms then its default, a `loop`’s test then its body. Every walk over nested instructions goes through here.
`fn blocks_mut(&mut self) -> Vec<&mut Block>`	`Op::blocks`, to change them.

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

Step

crates/core/ir/src/lib.rs#L1374

One step from a whole value towards a part, as Op::Part takes it.

Variants

Name	Description
`Field(u32)`	A field of a record, a column of a matrix or a component of a vector, by index: what `Op::Extract` takes.
`Index(ValueId)`	The array element, matrix column or vector component at a clamped `Int`: what `Op::Subscript` takes.

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