entelechy-graphGenerated

Layer: core · Lines of code: 8,206 · Integration test files: 1

Brief

Entelechy Graph Runtime: composes Kernels by KernelID with cached, dirty-tracked evaluation

Description

Graph Runtime (L6).

A Graph is a program: nodes bound to stable KernelIds, typed connections between their ports, and named outputs. The Graph owns composition; each Kernel owns its computation. The Evaluator runs a Graph against a Runtime, caches node outputs, re-executes a node only when its inputs changed, and commits state between evaluations. The Graph binds nodes by id; it never sees source or Kernel bodies.


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

Structs

Name	Brief
`NodeId`	Name of a node within a graph. A copy is a count, not a copy of its text.
`Name`	A node’s name: text shared by every copy, read as a `str`, ordered, hashed and compared as one.
`GraphParam`	A graph parameter: part of the graph’s interface, like a Kernel’s.
`Node`	A node: a Kernel binding plus its connections and parameter overrides.
`Awake`	When a node is awake: while row `row` of `source` (a count, as `value()` reads one in a `domain`) is not 0. A frame reads the row as the last frame left it; a node asleep is not run, its readers take its last outputs, the state it feeds stays, and what only it reads does not run either. A node that has never run runs once, as nothing of it is there to take.
`Reads`	What a node reads across evaluations: see `Graph::reads`.
`Graph`	A graph document.

Enumerations

Name	Brief
`Source`	Where an input port receives its image.
`Binding`	How an input port is fed.
`ParamValue`	A parameter value on a node: a literal, or a graph parameter by name.
`GraphError`	Structural problems with a graph.

Traits

Name	Brief
`AsGraph`	A graph as an evaluation takes it: borrowed, or shared. A shared graph the evaluator still holds is known unchanged by its identity alone, as none can change it while held; a borrowed one is compared whole.

Functions

Function	Brief
`fn split_port(text: &str) -> Option<(NodeId, String)>`	Splits `node.port` at the last dot (placed node ids contain dots: `fx.gray.out`); `None` when the text names no port.

Re-exports

Compare, DomainError, DomainExpr, DomainOp, DomainSpec, Requirement, Context, Domain, InputState, Value, KernelId, Bound, EvaluateError, Evaluator, Fusions, Held, Holding, Placed, PlanEntry, Refused, Report, Reused, binding_fault, borrowed_domain, type_fault

NodeId

crates/core/graph/src/lib.rs#L55

Name of a node within a graph. A copy is a count, not a copy of its text.

Properties

Name	Type	Description
`0`	`Name`

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

Name

crates/core/graph/src/lib.rs#L60

A node’s name: text shared by every copy, read as a str, ordered, hashed and compared as one.

Methods

Function	Description
`fn as_str(&self) -> &str`	The name as text.

Implemented traits: Borrow, Clone, Debug, Deref, Display, Eq, From, Hash, Ord, PartialEq, PartialOrd

GraphParam

crates/core/graph/src/lib.rs#L264

A graph parameter: part of the graph’s interface, like a Kernel’s.

Properties

Name	Type	Description
`name`	`String`	Parameter name.
`ty`	`String`	Its type as written; a record is read back by it.
`default`	`Value`	Default value, of that type; a value given for it takes its shape.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Node

crates/core/graph/src/lib.rs#L275

A node: a Kernel binding plus its connections and parameter overrides.

Properties

Name	Type	Description
`id`	`NodeId`	Node name; a placed sub-graph’s nodes carry a dotted prefix.
`kernel`	`KernelId`	The Kernel this node executes.
`inputs`	`BTreeMap<String, Binding>`	Input port bindings.
`params`	`BTreeMap<String, ParamValue>`	Parameter overrides; unlisted parameters use manifest defaults.
`domain`	`Option<DomainSpec>`	Output extent; defaults to the first input’s extent.
`is_async`	`bool`	`async = true;`: the node runs on a thread off the frame. Until a run lands, readers take its last output and the state it feeds stays. Its first run is on the frame.
`awake`	`Vec<Awake>`	`awake = value(source, row);`, its own and its placements’: while any reads 0 the node sleeps. See `Awake`.
`at`	`Option<String>`	Where the node was written, `file:line:column`, for diagnostics.

Implemented traits: Clone, Debug, PartialEq

Awake

crates/core/graph/src/lib.rs#L318

When a node is awake: while row row of source (a count, as value() reads one in a domain) is not 0. A frame reads the row as the last frame left it; a node asleep is not run, its readers take its last outputs, the state it feeds stays, and what only it reads does not run either. A node that has never run runs once, as nothing of it is there to take.

Properties

Name	Type	Description
`source`	`Source`	What holds the row.
`row`	`u32`	The row.

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

Reads

crates/core/graph/src/lib.rs#L327

What a node reads across evaluations: see Graph::reads.

Properties

Name	Type	Description
`holds_state`	`bool`	A port reads the node `<~`: what it gives is state, kept from one evaluation to the next.
`new_state`	`Vec<NodeId>`	Nodes holding state it reads `<-`: as this evaluation made them.
`committed`	`Vec<NodeId>`	Nodes it reads `<~`: as the last evaluation committed them.

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

Graph

crates/core/graph/src/lib.rs#L339

A graph document.

Properties

Name	Type	Description
`name`	`String`	Graph name.
`externals`	`Vec<String>`	External Field names the caller must supply.
`texts`	`Vec<(String, String)>`	Text externals: name and text, supplied as `Rows<Int>` of the characters’ codes.
`params`	`Vec<GraphParam>`	Parameters the caller may override.
`requirements`	`Vec<Requirement>`	What its parameters must hold, checked before each evaluation.
`times_params`	`Vec<String>`	Parameters that size the graph (a node’s `times`); changing one lowers the document again.
`nodes`	`Vec<Node>`	Nodes in document order, sub-graphs flattened in place.
`outputs`	`Vec<(String, Source)>`	Named results in document order; interfaces present the first.
`fallbacks`	`Vec<(String, Source)>`	Fallbacks: an external’s name and the source it reads while the caller supplies nothing (its file absent or unreadable).
`placed`	`Vec<(String, Vec<(String, Source)>)>`	Each placed graph’s outputs, by the id it was placed under, each wired to the node that gives it.
`repeated`	`Vec<(String, NodeId)>`	Each node placed `times = N` (N at least one), by its name, to the node of its last time, `name/N`, which `name.port` means.

Methods

Function	Description
`fn producer(&self, node: &NodeId, port: &str) -> Option<(NodeId, String)>`	The node and port that produce what `node.port` names: a node’s own port; a repeated node’s last time’s (`grow.result` is `grow/12.result`); a placed graph’s output (`kept.count`), by the node inside it that gives it; or the graph’s own output named `node`, as `node.result`. `None` when the name is none of these.
`fn primary_output(&self) -> Option<&(String, Source)>`	The first declared output.
`fn node(&self, id: &NodeId) -> Option<&Node>`	Looks up a node.
`fn index(&self) -> BTreeMap<&NodeId, usize>`	Node index by name; an evaluation builds it once for lookups.
`fn read_through(&self, also: impl IntoIterator<Item = NodeId>) -> BTreeSet<NodeId>`	The nodes a frame runs: what something reads. Every output’s node (a file’s too), every state’s (what a `<~` carries and the source it starts from), every node an `awake` reads, the nodes in `also` (those pinned to be read), and every node they read through `<-`, in turn. A node none of them reads computes nothing anyone sees, so it does not run. Every node is taken as awake: see `Graph::read_awake`.
`fn read_awake(&self, also: impl IntoIterator<Item = NodeId>, asleep: &BTreeSet<NodeId>) -> BTreeSet<NodeId>`	`Graph::read_through` with the nodes in `asleep` asleep: each is still reached, as its readers take what it last gave, but what it reads is reached only through another reader.
`fn read_by(&self, seeds: BTreeSet<NodeId>) -> BTreeSet<NodeId>`	`seeds` and every node they read through `<-`, in turn.
`fn fallback(&self, external: &str) -> Option<&Source>`	What an external reads while the caller supplies nothing for it.
`fn reads(&self, id: &NodeId) -> Option<Reads>`	What node `id` reads across evaluations: whether it holds state (a port reads it `<~`, as the last evaluation committed it), the nodes holding state it reads `<-` (their new state, made earlier in this evaluation), and the nodes it reads `<~` (as the last evaluation committed them). `None` for no such node.
`fn shown_only(&self, presented: &BTreeSet<String>) -> BTreeSet<NodeId>`	The nodes whose outputs reach only what is shown: no state reads them, through any chain of nodes (a `<~` source or its initial value), nor any output outside `presented`, the outputs an interface shows or plays and keeps nothing of. What such a node computes is seen and not kept, so a run of it may differ from the next by a device’s rounding and nothing that follows depends on which.
`fn order(&self) -> Result<Vec<usize>, GraphError>`	Checks names and dependencies and returns node indices in an order where every producer precedes its consumers.

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

Source

crates/core/graph/src/lib.rs#L192

Where an input port receives its image.

Variants

Name	Description
`External(String)`	An image supplied by the caller under this name.
`Node { node: NodeId, port: String }`	An output port of another node.

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

Binding

crates/core/graph/src/lib.rs#L215

How an input port is fed.

Variants

Name	Description
`Now(Source)`	The source’s value from this evaluation.
`Previous { source: Source, initial: Source, migration: Option<KernelId> }`	The source’s value committed by the previous successful evaluation; `initial` feeds the port before the first commit and after a state reset. State lives in the Graph; Kernels stay pure.

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

ParamValue

crates/core/graph/src/lib.rs#L254

A parameter value on a node: a literal, or a graph parameter by name.

Variants

Name	Description
`Literal(Value)`	A fixed value.
`Graph(String)`	The graph parameter with this name, resolved at evaluation from the caller’s overrides or the graph’s defaults.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

GraphError

crates/core/graph/src/lib.rs#L371

Structural problems with a graph.

Variants

Name	Description
`DuplicateName(String)`	Two nodes or externals share a name.
`UnknownSource { node: NodeId, port: String, source: Source, near: Option<String> }`	A port or the output refers to a name that is neither a node nor an external.
`Cycle(Vec<NodeId>)`	Nodes depend on each other in a cycle.
`UnknownOutput(Source)`	A graph output refers to an unknown source.
`NoOutput`	The graph declares no output.
`FeedbackNeedsNode { node: NodeId, port: String }`	A `<~` binding reads an external; only node outputs carry state.
`TwoMigrations { state: Source, first: KernelId, second: KernelId }`	Two `<~` readers of one state name different migrations for it.

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

AsGraph

crates/core/graph/src/lib.rs#L29

A graph as an evaluation takes it: borrowed, or shared. A shared graph the evaluator still holds is known unchanged by its identity alone, as none can change it while held; a borrowed one is compared whole.

Methods

Function	Description
`fn graph(&self) -> &Graph`	The graph.
`fn shared(&self) -> Option<&Arc<Graph>>`	The graph shared, when it is.