entelechy-abi自动生成

层：核心层 · 代码行数：1,703 · 集成测试文件：2

简述

能力 ABI：Kernel 被允许看到的世界（能力、类型、句柄）。

Entelechy Capability ABI: the world a Kernel is allowed to see

描述

Capability ABI (L2).

The world visible to a Kernel: value types, opaque handles, named capabilities, and a Scope that gates every Host call on an explicit grant. Backends call the Host for a Kernel only through a Scope built from its declared capabilities. No capability means no access.


内部依赖	`entelechy-host`
外部依赖	—
源码	`crates/core/abi`

模块

名称	简述
`names`	Near-miss suggestions for unknown names: the one rule every layer that reports an unknown name uses.
`pad`	A pad’s buttons, by the number `button()` takes.

结构体

名称	简述
`UnknownCapability`	The name does not correspond to any capability.
`Capabilities`	An explicit set of capabilities: a bit a capability, in the order of `Capability::ALL`.
`UnknownType`	The name does not correspond to any type.
`PortType`	What a port carries: a Field of `element`s in one `Shape`. An image is the grid of `Vec4`.
`InputState`	Pointer and key state for one evaluation. Key codes are browser key codes (ASCII uppercase letters and digits, space 32, enter 13, escape 27, arrows 37 to 40), 0 to 255. Pointer buttons: 0 left, 1 right, 2 middle.
`Context`	`C` in `Y = K(X, P, C)`: the world for one evaluation, read by Kernels through builtins behind `time.read` and `input.read`.
`Invocation`	Everything a Kernel receives for one execution: `X`, `P` and `C` in `Y = K(X, P, C)`.
`Scope`	A capability-gated view of the Host.

枚举

名称	简述
`Capability`	A named authority a Kernel may declare and be granted; what each grants is `Capability::doc`.
`Type`	Types that cross the Kernel boundary, by structure: a `Scalar`, a vector of two to four, a square float-kind matrix, or a Kernel’s own struct. Each named type has a same-named constant (`Type::Vec3`), usable as a pattern.
`Value`	A value crossing the Kernel boundary: a parameter, a constant; structs and arrays as a `Value::Record`. A value wider than 16 bytes is kept apart, so every value, and every IR instruction holding a constant, is as small as the common ones and not as the widest.
`Number`	One scalar of a value, of any kind.
`AbiError`	Errors a Kernel can observe when calling the Host through the ABI.

Trait

名称	简述
`ShapeIndex`	Value types that address a shape’s elements.

函数

函数	简述
`fn nearest<'a>(wanted: &str, known: impl IntoIterator<Item = &'a str>) -> Option<&'a str>`	The name among `known` that `wanted` was most likely meant to be.
`fn did_you_mean<'a>(wanted: &str, known: impl IntoIterator<Item = &'a str>) -> String`	`; did you mean` x`?` for the nearest name, or empty.
`fn suggestion(near: Option<&str>) -> String`	`; did you mean` name`?` for a near miss already found, or empty.
`fn edit_distance(a: &str, b: &str) -> usize`	How many single-character insertions, deletions, replacements and swaps of two neighbors turn one string into the other; a swap (`resutl` for `result`) counts as one.
`fn widened(value: &Value, wanted: &[Scalar]) -> Option<Vec<u32>>`	`value`’s words laid out as `wanted`, each scalar converted in order (`Number::as_kind`); `None` for another layout.

常量

名称	类型	取值	简述
`pad::SOUTH`	`i32`	`8`	The lower face button (A, Cross).
`pad::EAST`	`i32`	`9`	The right face button (B, Circle).
`pad::WEST`	`i32`	`10`	The left face button (X, Square).
`pad::NORTH`	`i32`	`11`	The upper face button (Y, Triangle).
`pad::LEFT_SHOULDER`	`i32`	`12`	The left shoulder.
`pad::RIGHT_SHOULDER`	`i32`	`13`	The right shoulder.
`pad::LEFT_THUMB`	`i32`	`14`	The left stick pressed in.
`pad::RIGHT_THUMB`	`i32`	`15`	The right stick pressed in.
`pad::START`	`i32`	`16`	Start.
`pad::SELECT`	`i32`	`17`	Select.
`ABI_VERSION`	`u32`	`1`	The version of the Capability ABI: what a Kernel may ask of the Host and how values cross.
`TYPED`	`usize`	`32`	How many characters one evaluation’s input holds; those typed past them wait for the next.
`BUTTONS`	`i32`	`24`	Button numbers `InputState::button` knows: a pointer’s 0 to 2, a pad’s from 8.

重导出

Census, Domain, Encoding, FieldBytes, FieldData, Handle, Host, HostError, Image, MadeFrom, PAGE_WORDS, Pages, Pixel, Scalar, Schema, Shape, Version, DEFAULT_WORK, MAX_WORK, encoding

UnknownCapability

crates/core/abi/src/lib.rs#L77

The name does not correspond to any capability.

属性

名称	类型	说明
`0`	`String`

实现的 Trait: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

Capabilities

crates/core/abi/src/lib.rs#L101

An explicit set of capabilities: a bit a capability, in the order of Capability::ALL.

方法

函数	说明
`fn none() -> Self`	The empty set: no access at all.
`fn contains(&self, capability: Capability) -> bool`	Whether the set grants `capability`.
`fn insert(&mut self, capability: Capability)`	Adds a capability.
`fn iter(&self) -> impl Iterator<Item = Capability> + '_`	Iterates capabilities in stable order.

实现的 Trait: Clone, Copy, Debug, Default, Display, Eq, FromIterator, PartialEq, StructuralPartialEq

UnknownType

crates/core/abi/src/lib.rs#L424

The name does not correspond to any type.

属性

名称	类型	说明
`0`	`String`

实现的 Trait: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

PortType

crates/core/abi/src/lib.rs#L889

What a port carries: a Field of elements in one Shape. An image is the grid of Vec4.

属性

名称	类型	说明
`element`	`Type`	The element type as the Kernel sees it (`Type::Struct` indexes the Kernel’s struct table).
`shape`	`Shape`	How elements are addressed.
`schema`	`Schema`	The element’s storage layout.

方法

函数	说明
`fn image() -> Self`	The image port: a grid of `Vec4`.
`fn is_image(&self) -> bool`	Whether this is the image port.
`fn index_type(&self) -> Type`	The value type that addresses one element: `Int`, `Vec2`, or `Vec3`.

实现的 Trait: Clone, Debug, Display, Eq, Hash, PartialEq, StructuralPartialEq

InputState

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

Pointer and key state for one evaluation. Key codes are browser key codes (ASCII uppercase letters and digits, space 32, enter 13, escape 27, arrows 37 to 40), 0 to 255. Pointer buttons: 0 left, 1 right, 2 middle.

属性

名称	类型	说明
`pointer`	`[f32; 2]`	Pointer position in output pixels.
`pointer_down`	`bool`	Whether the primary pointer button is held.
`pointer_right`	`bool`	Whether the secondary (right) pointer button is held.
`pointer_middle`	`bool`	Whether the middle pointer button is held.
`wheel`	`[f32; 2]`	Wheel scroll since the last evaluation, in lines: `x` sideways, `y` positive away from the person.
`sticks`	`[[f32; 2]; 3]`	A pad’s axes in `-1..1`: left stick, right stick, and the triggers as one pair (`x` left, `y` right, in `0..1`). Zero without a pad.
`pads`	`u32`	How many pads are connected.

方法

函数	说明
`fn button(&self, code: i32) -> bool`	Whether the button numbered `code` is held: a pointer’s 0 to 2, a pad’s from 8 (see `pad`); other numbers are never held.
`fn set_button(&mut self, code: i32, down: bool)`	Holds or releases a button; numbers outside `0..BUTTONS` are ignored, and the pointer’s three keep their own fields.
`fn button_bits(&self) -> u32`	The held buttons as bits, `button(n)` at bit `n`.
`fn stick(&self, which: i32) -> [f32; 2]`	A pad axis pair: 0 left stick, 1 right, 2 triggers; zeros otherwise.
`fn key(&self, code: i32) -> bool`	Whether the key with `code` is held; codes outside `0..256` are never held.
`fn set_key(&mut self, code: i32, down: bool)`	Presses or releases a key; codes outside `0..256` are ignored.
`fn key_words(&self) -> [u32; 8]`	The key set as eight 32-bit words, bit `code` set when held.
`fn typed(&self, k: i32) -> i32`	The `k`th character typed since the last evaluation as a code point, 0 after the last and for `k` outside `0..TYPED`.
`fn typed_words(&self) -> [u32; 32]`	The characters typed, as code points, 0 after the last.
`fn type_text<'a>(&mut self, text: &'a str) -> &'a str`	Adds characters typed after those already held; gives back those past the room left, for a later evaluation. A NUL is not a character typed.
`fn clear_typed(&mut self)`	Forgets the characters typed, once an evaluation has seen them.
`fn fingerprint(&self) -> u64`	A value that changes whenever any observable input changes.

实现的 Trait: Clone, Copy, Debug, Default, PartialEq, StructuralPartialEq

Context

crates/core/abi/src/lib.rs#L1152

C in Y = K(X, P, C): the world for one evaluation, read by Kernels through builtins behind time.read and input.read.

属性

名称	类型	说明
`time`	`f64`	Session time in seconds, whole: `clock()` reads it as a `Double`, `time()` rounded to a `Float`.
`rate`	`f32`	The driving sound device’s samples per second; zero without one.
`queued`	`u32`	The samples (per channel) the sound device holds and has not yet played; zero without one.
`input`	`InputState`	Pointer and key state.
`window`	`[f32; 2]`	The window’s size in physical pixels; zero by zero without one. A node’s `domain` may take it.
`scale`	`f32`	Physical pixels per logical pixel; one without a window.

方法

函数	说明
`fn float_time(&self) -> f32`	What `time()` reads: the clock rounded to the nearest `Float`. Every backend reads it from here.
`fn has_window(&self) -> bool`	Whether a window is open: both sides of `window` are positive.
`fn input_fingerprint(&self) -> u64`	A hash of what `input.read` observes: input, window size, scale.

实现的 Trait: Clone, Copy, Debug, Default, PartialEq, StructuralPartialEq

Invocation

crates/core/abi/src/lib.rs#L1213

Everything a Kernel receives for one execution: X, P and C in Y = K(X, P, C).

属性

名称	类型	说明
`inputs`	`Vec<Handle>`	Field inputs in manifest order.
`params`	`Vec<Value>`	Parameter values in manifest order.
`domain`	`Domain`	Output domain.
`context`	`Context`	Time and input for this execution.

实现的 Trait: Clone, Debug, PartialEq, StructuralPartialEq

Scope

crates/core/abi/src/lib.rs#L1254

A capability-gated view of the Host.

Every method checks its capability before touching the Host. Backends construct one Scope per execution from the Kernel manifest.

方法

函数	说明
`fn new(host: &'a mut Host, granted: Capabilities) -> Self`	Wraps the Host with the given grant.
`fn granted(&self) -> &Capabilities`	The capabilities this scope grants.
`fn work(&self) -> u64`	The loop iterations this run may take over all its elements (`Host::work`). A bound; it needs no capability.
`fn room(&self) -> usize`	The words the Host may still allocate under its budget. A bound; it needs no capability.
`fn bound(&self, field: Handle) -> Result<(Shape, Schema), AbiError>`	A bound handle’s shape and element layout, to check a binding before a run. A check; it needs no capability and reads no word.
`fn size(&self, field: Handle) -> Result<Domain, AbiError>`	The extent of an input. Requires `field.read`.
`fn schema(&self, field: Handle) -> Result<Schema, AbiError>`	The element layout of an input. Requires `field.read`.
`fn element(&self, field: Handle, index: u32) -> Result<Cow<'_, [u32]>, AbiError>`	One element of an input by linear index, as widened words. Requires `field.read`. Fails while the Field is device-resident.
`fn values(&self, field: Handle) -> Result<Cow<'_, [u32]>, AbiError>`	Every element of an input as widened words. Requires `field.read`.
`fn storage(&self, field: Handle) -> Result<&[u32], AbiError>`	An input’s memory as kept: the Kernel’s words for a wide schema, packed scalars for a narrow one (`Schema::load` reads them). Requires `field.read`.
`fn working(&mut self, field: Handle) -> Result<Vec<u32>, AbiError>`	A copy of an input’s memory as kept, to write in place: a scan’s memory, which the bound Field never sees changed. Copied a page at a time where the Host knows the Field was made from words it still holds (`Host::working`). Requires `field.read`.
`fn adopt_derived(&mut self, schema: Schema, domain: Domain, storage: Vec<u32>, base: Handle, changed: Pages) -> Result<Handle, AbiError>`	A new Field of `storage`, as kept, made from input `base`’s words but on the pages `changed` (`Host::adopt_derived`): what a scan leaves its memory as. Requires `field.write`.
`fn adopt_storage(&mut self, schema: Schema, domain: Domain, storage: Vec<u32>) -> Result<Handle, AbiError>`	A new Field of `storage`, as kept. Requires `field.write`.
`fn resident(&self, field: Handle) -> Result<Option<&dyn Any + Send + Sync>, AbiError>`	The device object of a resident input, if any. Requires `field.read`.
`fn made_from(&self, field: Handle) -> Result<Vec<MadeFrom>, AbiError>`	The words an input was made from, nearest first, and the storage words it may differ from each on (`Host::made_from`), for a device to bring a copy of those words up to date. Requires `field.read`.
`fn version(&self, field: Handle) -> Result<Version, AbiError>`	An input’s words as they are now (`Host::version`), which a device copy of them is known by. Requires `field.read`.
`fn holds(&self, version: Version) -> Result<bool, AbiError>`	Whether `version` is still what its Field holds (`Host::holds`). Requires `field.read`.
`fn make_resident(&mut self, field: Handle, device: Box<dyn Any + Send + Sync>) -> Result<(), AbiError>`	Gives an input’s words a copy on the device, beside the Host’s. Requires `field.read`.
`fn create(&mut self, schema: Schema, domain: Domain) -> Result<Handle, AbiError>`	A new zeroed Field. Requires `field.write`.
`fn can_hold(&self, fields: &[(&Schema, Domain)]) -> Result<(), AbiError>`	Whether these Fields would fit under the Host’s budget now (`Host::can_hold`), asked before device allocation. Requires `field.write`.
`fn create_for_fill(&mut self, schema: Schema, domain: Domain) -> Result<Handle, AbiError>`	A new Field with unspecified words, for a backend that writes every word before any read. Requires `field.write`.
`fn storage_mut(&mut self, field: Handle) -> Result<&mut [u32], AbiError>`	The memory of a Field this scope created, as kept, to fill in place. Requires `field.write`.
`fn write_values(&mut self, field: Handle, values: &[u32]) -> Result<(), AbiError>`	Replaces every element of a Field this scope created with wide words, narrowed as the Field keeps them. Requires `field.write`.
`fn write_storage(&mut self, field: Handle, storage: &[u32]) -> Result<(), AbiError>`	Replaces the memory of a Field this scope created, as kept. Requires `field.write`.
`fn write_element(&mut self, field: Handle, index: u32, words: &[u32]) -> Result<(), AbiError>`	Replaces one element of a Field this scope created. Requires `field.write`.
`fn adopt_resident(&mut self, schema: Schema, domain: Domain, device: Box<dyn Any + Send + Sync>) -> Result<Handle, AbiError>`	A new Field whose words live on the device. Requires `field.write`.
`fn release(&mut self, field: Handle) -> Result<(), AbiError>`	Releases a Field this scope created. Requires `field.write`.

Capability

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

A named authority a Kernel may declare and be granted; what each grants is Capability::doc.

变体

名称	说明
`FieldRead`	`field.read`.
`FieldWrite`	`field.write`.
`TimeRead`	`time.read`.
`InputRead`	`input.read`.

方法

函数	说明
`fn name(self) -> &'static str`	Stable spelling used in `.ent` sources and manifests.
`fn doc(self) -> &'static str`	What it grants, one sentence: the part of the world a Kernel that declares it may touch.

实现的 Trait: Clone, Copy, Debug, Display, Eq, FromIterator, FromStr, Hash, Ord, PartialEq, PartialOrd, StructuralPartialEq

Type

crates/core/abi/src/lib.rs#L179

Types that cross the Kernel boundary, by structure: a Scalar, a vector of two to four, a square float-kind matrix, or a Kernel’s own struct. Each named type has a same-named constant (Type::Vec3), usable as a pattern.

变体

名称	说明
`Scalar(Scalar)`	One scalar.
`Vector(Scalar, u8)`	Two to four components of one kind (see `Type::vector`).
`Matrix(Scalar, u8)`	A square float-kind matrix of the given order, column-major.
`Struct(u32)`	A Kernel-defined record, by index into the module’s struct table. Structs stay inside a Kernel: they never cross the ABI as parameters or ports.

方法

函数	说明
`fn name(self) -> &'static str`	Stable spelling used in `.ent` sources; structs print by index.
`fn shape(self) -> Option<(Type, u8)>`	The scalar type and count a value is made of; `None` for a struct.
`fn scalar(self) -> Option<Type>`	The scalar type a value of this type is made of.
`fn kind(self) -> Option<Scalar>`	The kind of scalar a value of this type is made of.
`fn is_64bit(self) -> bool`	Whether this is a 64-bit scalar, or a vector or matrix of them.
`fn is_float_kind(self) -> bool`	Whether this is made of floats of either width.
`fn is_int_kind(self) -> bool`	Whether this is an integer of either width, or a vector of them.
`fn words(self) -> Option<usize>`	Words a value takes, two per 64-bit scalar; `None` for a struct.
`fn with_scalar(self, scalar: Type) -> Option<Type>`	This shape made of `scalar` (`Vec3` of `Double` is `DVec3`), if such a type exists.
`fn vector(scalar: Type, n: u8) -> Option<Type>`	The vector of `n` components of `scalar` (the scalar when `n` is one). Floats and doubles come in 2 to 4, integers and longs in 2 or 3, booleans alone.
`fn matrix(kind: Scalar, n: u8) -> Option<Type>`	The square matrix of order `n` of a float kind, if it exists.
`fn order(self) -> Option<u8>`	The order of a square matrix type.
`fn column(self) -> Option<Type>`	The column type of a matrix type.
`fn matrix_of(self) -> Option<Type>`	The matrix type whose columns are this vector type.
`fn components(self) -> Option<u8>`	Number of components of a 32-bit float vector.
`fn int_components(self) -> Option<u8>`	Number of components of a 32-bit integer vector.
`fn lanes(self) -> Option<(u8, Type)>`	Number of components of a vector of any kind, and their type.
`fn other_kind(self) -> Option<Type>`	The same-width vector of the other 32-bit kind (float and int).

实现的 Trait: Clone, Copy, Debug, Display, Eq, FromStr, Hash, PartialEq, StructuralPartialEq

Value

crates/core/abi/src/lib.rs#L451

A value crossing the Kernel boundary: a parameter, a constant; structs and arrays as a Value::Record. A value wider than 16 bytes is kept apart, so every value, and every IR instruction holding a constant, is as small as the common ones and not as the widest.

变体

名称	说明
`Float(f32)`	A float.
`Int(i32)`	An integer.
`Bool(bool)`	A truth value.
`Vec2([f32; 2])`	A two-component vector.
`Vec3([f32; 3])`	A three-component vector.
`Vec4([f32; 4])`	A four-component vector.
`IVec2([i32; 2])`	A two-component integer vector.
`IVec3([i32; 3])`	A three-component integer vector.
`IVec4([i32; 4])`	A four-component integer vector.
`Mat2([f32; 4])`	A 2x2 matrix, column by column.
`Mat3(Box<[f32; 9]>)`	A 3x3 matrix, column by column.
`Mat4(Box<[f32; 16]>)`	A 4x4 matrix, column by column.
`Double(f64)`	A 64-bit float.
`Long(i64)`	A 64-bit integer.
`DVec2([f64; 2])`	Two doubles.
`DVec3(Box<[f64; 3]>)`	Three doubles.
`DVec4(Box<[f64; 4]>)`	Four doubles.
`LVec2([i64; 2])`	Two longs.
`LVec3(Box<[i64; 3]>)`	Three longs.
`DMat2(Box<[f64; 4]>)`	A 2x2 matrix of doubles, column by column.
`DMat3(Box<[f64; 9]>)`	A 3x3 matrix of doubles, column by column.
`DMat4(Box<[f64; 16]>)`	A 4x4 matrix of doubles, column by column.
`Record(Vec<Value>)`	A struct’s fields or an array’s elements in order, matched by layout, never by name.

方法

函数	说明
`fn ty(&self) -> Option<Type>`	The type of a non-record value.
`fn numbers(&self) -> Vec<Number>`	Its scalars in layout order.
`fn matches_scalars(&self, scalars: &[Scalar]) -> bool`	Whether this value is made of `scalars`, in order, a word each: the layout a parameter of that type holds. Nothing is gathered to answer.
`fn push_words(&self, out: &mut Vec<u32>)`	Appends the Kernel’s words to `out`, as `Value::words` gives them.
`fn words(&self) -> Vec<u32>`	The Kernel’s words, one per 32-bit scalar and two per 64-bit one, in layout order.
`fn scalars(&self) -> Vec<Scalar>`	What each word is, in layout order.
`fn shaped_like(&self, template: &Value) -> Option<Value>`	This value in `template`’s shape, when its scalars convert in order to the template’s (`Number::as_kind`). Layout decides: `[[1, 0], [0, 1]]` is a `Mat2`.
`fn rebuilt(&self, words: &mut impl Iterator<Item = u32>) -> Value`	A value of this one’s shape made of `words`, taken in order.

实现的 Trait: Clone, Debug, Display, PartialEq, StructuralPartialEq

Number

crates/core/abi/src/lib.rs#L503

One scalar of a value, of any kind.

变体

名称	说明
`Float(f32)`	An `f32`.
`Int(i32)`	An `i32`.
`Bool(bool)`	A truth value.
`Double(f64)`	An `f64`.
`Long(i64)`	An `i64`.

方法

函数	说明
`fn kind(self) -> Scalar`	The kind of word this scalar is kept as.
`fn of_element(schema: &Schema, element: &[u32]) -> Vec<Number>`	The numbers of one element’s Kernel words as `schema` lays them out, in order: what `Number::push_words` wrote, read back.
`fn push_words(self, out: &mut Vec<u32>)`	Its words: one, or two for a 64-bit scalar, the low one first.
`fn as_kind(self, kind: Scalar) -> Option<Number>`	This given value as one of `kind`, when it converts: an integer to either float or a wider integer, a float to the other width, a long to an `Int` that holds it, a double to a `Float` that holds its size. Kernel arithmetic is separate.

实现的 Trait: Clone, Copy, Debug, PartialEq, StructuralPartialEq

AbiError

crates/core/abi/src/lib.rs#L1226

Errors a Kernel can observe when calling the Host through the ABI.

变体

名称	说明
`Denied(Capability)`	The Kernel was not granted the capability the call requires.
`Host(HostError)`	The Host rejected the call.

实现的 Trait: Clone, Debug, Display, Eq, Error, From, PartialEq, StructuralPartialEq

ShapeIndex

crates/core/abi/src/lib.rs#L934

Value types that address a shape’s elements.

方法

函数	说明
`fn index_type(self) -> Type`	`Int` for rows, `Vec2` for grids, `Vec3` for volumes.