Struct GkKernel 

pub struct GkKernel {
    pub constants_folded: usize,
    /* private fields */
}

A compiled GK kernel: an Arc<GkProgram> plus one GkState.

Invariants

• Scope coordinates are always populated. After construction scope_coords reflects this kernel’s place in the comprehension chain: leaf-first list of super::ScopeCoord from the kernel’s own scope up through every enclosing comprehension. Root-scope kernels (no parent) start with their own coords (or empty). Self::materialize_wiring_from_outer re-computes the path so post-bind it includes the outer’s chain. Consumers (presentation layer, inspector, scope-aware diagnostics) call Self::scope_coordinates without needing to walk the scope tree themselves. See [super::scope_coords].

Fields

constants_folded: usize

Number of init-time constants folded during compilation.

Implementations

impl GkKernel

pub fn mark_inherited_outputs<I>(&mut self, names: I)

where I: IntoIterator<Item = String>,

Mark a set of output names as inherited (cascade-only) on the program. Must be called immediately after construction, before the Arc<GkProgram> is shared. Panics if the Arc has other references.

pub fn program(&self) -> &Arc<GkProgram>

The shared immutable program.

pub fn commit_write_throughs(&mut self)

SRD-67 Phase 5 — per-cycle commit. Pulls each write- through’s synthetic source output and stores its value through the corresponding cell-bound input slot for the declared export name. Reads of that name in the parent or in sibling kernels share the same cell and observe the write on the next read.

No-op when the kernel carries no write-throughs.

pub fn set_cursor_schemas(&mut self, schemas: Vec<SourceSchema>)

Set source schemas on the program (called by the compiler).

pub fn set_ast(&mut self, ast: Arc<GkFile>)

Attach the parsed AST as live program metadata. Called by every DSL compile entry point immediately after the assembler produces the kernel, while the program Arc is still uniquely owned. The subscope synthesizer (SRD-13f §“Wire-reference classification”) queries this to integrate parent bindings’ matter into child scopes.

pub fn state(&mut self) -> &mut GkState

The per-fiber mutable evaluation state.

pub fn state_ref(&self) -> &GkState

Read-only access to the kernel’s evaluation state. Used by callers (e.g. the scope-init pass) that need to inspect pulled values without consuming the kernel.

pub fn set_inputs(&mut self, coords: &[u64])

Convenience: set coordinate inputs on the owned state.

pub fn get_input(&self, name: &str) -> Option<Value>

Read an input value by name. Cell-aware: cell-bound slots return the cell’s current value.

pub fn pull(&mut self, output_name: &str) -> &Value

Convenience: pull from the owned state.

pub fn input_names(&self) -> Vec<String>

Return the names of the inputs.

pub fn output_names(&self) -> Vec<&str>

Return the names of all available output variates.

pub fn get_constant(&self, name: &str) -> Option<&Value>

Read the value of a named output that was folded to a constant.

Underlying primitive — prefer Self::lookup for scope-aware name resolution. This method only succeeds for constant-folded outputs whose buffer is populated; it returns None for auto-passthrough outputs (where the value lives in the input slot) and for cycle-dependent outputs that haven’t been pulled.

pub fn lookup(&self, name: &str) -> Option<Value>

Look up a name in this kernel’s scope.

The canonical scope-aware read documented by SRD-16 §“Visibility Rules: Shadowing”: own-scope folded outputs shadow inherited extern values, with auto-passthrough outputs falling through to the input slot transparently.

Resolution order:

1. Folded output buffer (compile-time constants).
2. Cell-aware input read (covers extern values bound via materialize_wiring_from_outer, auto-passthrough outputs from input ...: u64 / extern, and shared-cell-backed slots — the cell is queried on every read so reads pick up writes from sibling kernels intrinsically).

Returns None when the name doesn’t resolve in either tier or when the resolved value is Value::None (unset).

Returns Value (owned, not borrowed) because shared-cell reads acquire a Mutex and clone out — there’s no long-lived borrow into the cell. For non-shared slots the clone is cheap (Value’s Clone is Arc-based for vectors, primitive copy otherwise).

This is the single read API for scope-aware name lookup and is cell-aware by default — callers don’t need to know whether a name is shared or not.

pub fn advance_broadcasts(&mut self)

SRD-13f Push B.2 — advance this kernel’s broadcast state: pull every output that has an attached broadcast cell, forcing the eval cone to recompute against current inputs and writing the fresh value through the cell. Descendant kernels with input slots cell-attached to these outputs then observe the current value on their next read_input without any per-fiber-write coordination.

Intended to run once per cycle on each per-fiber outer kernel whose outputs are visible to inner scopes. The alternative — validity-bit + auto-pull-on-stale-read — would put the trigger fully inside the GK engine (so inner reads transparently fetch fresh values), but requires the engine to track upstream dependencies across the cell boundary. This eager-broadcast form is simpler and lives entirely within the kernel’s own surface: callers ask the kernel to advance its broadcasts; the kernel does the pulls; cells receive the values.

pub fn shared_cells_in_scope(&self) -> Vec<SharedCellEntry>

Every shared cell visible at this kernel’s scope — own input slots’ attached cells unioned with the transit cells inherited from ancestors. The typed ScopeKernel::shared_cells_in_scope delegates here.

Used by materialize_wiring_from_outer to compute the parent’s full visible cell set and propagate it to the child. Public for the typed surface; semantics are the same as the typed accessor.

pub fn for_iteration( canonical: &Arc<GkKernel>, parent: &Arc<GkKernel>, bindings: &[(String, Value)], ) -> Arc<GkKernel>

Construct a per-iteration kernel: clone canonical’s program, bind it to parent’s scope, and pre-load every (var, value) binding into the corresponding input slot.

This is the canonical recipe for materialising the scope kernel at one specific iteration position — the runtime dispatcher uses it before descending into a comprehension iteration’s children, and the pre-map walker uses it for the same purpose so nested for_each clauses with outer-iter-var interpolation (vec_{profile}) resolve at pre-map time.

Owning the recipe here ensures both consumers produce identical kernels for identical inputs; previously each site reimplemented the three-step from_program → materialize_wiring_from_outer → set_input dance and could (and did) drift.

pub fn scope_coordinates(&self) -> &[ScopeCoord]

The leaf-first scope coordinate path — see the [super::scope_coords] module doc for the formal definition. Always reflects the current binding state: after Self::materialize_wiring_from_outer the path includes the outer kernel’s full chain; for root scopes the path is just this kernel’s own coords (or empty).

pub fn scope_values(&self) -> Vec<(String, Value)>

Extract the scope values that were set via materialize_wiring_from_outer. Returns [(name, value)] for inputs that are not at their default. Used by OpBuilder to inject the same values into every fiber’s state, including per-op-template kernels whose input layout differs from this kernel’s. The name- keyed shape is the cross-kernel-safe contract: an index captured against this kernel’s layout is meaningless when applied to a kernel synthesised from a different source (different extern declaration order, lazy-cascade omissions, etc.). Naming the binding makes the cross-scope write unambiguous — a missing name on the target program is a no-op rather than a silently mis-routed write.

pub fn into_program(self) -> Arc<GkProgram>

Extract the program for concurrent use.

impl GkKernel

pub fn build_subscope( &self, matter: GkMatter<'_>, ) -> Result<GkKernel, ContractViolation>

THE subscope-construction path. Per the kernel-construction invariant, this is the ONE method through which a parent kernel produces a child. compile_gk produces root kernels; everything else is a subscope and routes here.

Cell propagation, scope-coordinate plumbing, and Rule 2 write-throughs flow from self (the parent) into the returned child. Returns the child kernel plus any write-through bindings finalize produced (empty for the program-matter form, populated for the source-matter form when a result-LHS collides with a parent shared cell).

Trait Implementations

impl Construction for GkKernel

type Error = ContractViolation

Construction error type.

fn root(matter: GkMatter<'_>) -> Result<Self, Self::Error>

Path 1: build a root context from gk matter. No parent. Subscope-only fields on the matter (result-binding rewrites, inherited-output cascade, finalize-time contract checks) are not applicable here and are ignored.

fn subscope(&self, matter: GkMatter<'_>) -> Result<Self, Self::Error>

Path 2: build a subscope context against self from gk matter. The parent supervises: cell cascade, Rule 2 rewrites, scope-coordinate threading, init-binding contract checks all flow from self into the child.

impl Dataflow for GkKernel

fn set_wire_idx(&mut self, idx: usize, value: Value)

Write a value to wire idx. Out-of-range indices are a programming error (the caller already had a resolved index); panics in debug, no-ops in release.

fn get_wire_idx(&self, idx: usize) -> Value

Read the current value of wire idx. Out-of-range behaviour mirrors set_wire_idx.

fn set_wire<W: WireKey>(&mut self, key: W, value: Value) -> bool

Write a value to a wire identified by key (index or name). Returns whether the wire was found.

fn get_wire<W: WireKey>(&self, key: W) -> Option<Value>

Read the current value of a wire identified by key (index or name). Returns None when the wire is not found.

impl Debug for GkKernel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Metadata for GkKernel

fn find_input(&self, name: &str) -> Option<usize>

Resolve an input name to its wire index, if present.

fn input_names(&self) -> Vec<String>

All declared input wire names, in declaration order.

fn output_names(&self) -> Vec<String>

All declared output wire names, in declaration order.

fn coord_count(&self) -> usize

Number of coordinate inputs (the leading prefix of the input slot vector — written via the cycle dispatcher).

fn input_port_type(&self, name: &str) -> Option<PortType>

Declared port type of an input wire, if known.