Trait Kernel 

pub trait Kernel: Send + KernelInternals {
    // Required methods
    fn engine(&self) -> Engine;
    fn set_inputs(&mut self, coords: &[u64]);
    fn set_input(&mut self, name: &str, value: Value) -> Result<(), String>;
    fn set_cursor(
        &mut self,
        name: &str,
        partition: &Partition,
    ) -> Result<(), String>;
    fn eval(&mut self);
    fn pull(&mut self, name: &str) -> Value;
    fn input_names(&self) -> Vec<String>;
    fn output_names(&self) -> Vec<String>;
    fn output_type(&self, name: &str) -> Option<PortType>;
    fn externs(&self) -> Vec<(String, PortType)>;
    fn cursor_schemas(&self) -> &[SourceSchema];
    fn plan(&self) -> EnginePlan;
    fn input_value(&self, name: &str) -> Option<Value>;
    fn traversals(&self) -> &[Traversal];
    fn traverse(&mut self, index: usize) -> Result<TraversalStream, String>;
    fn invalidate_all(&mut self);
    fn shared_cells(&self) -> Vec<SharedCellEntry>;
    fn attach_shared_cell(
        &mut self,
        name: &str,
        cell: SharedCell,
    ) -> Result<(), String>;
    fn into_program(self: Box<Self>) -> Arc<dyn KernelProgram> ;

    // Provided methods
    fn input_index(&self, name: &str) -> Option<usize> { ... }
    fn set_input_at(&mut self, index: usize, value: Value) -> Result<(), String> { ... }
    fn output_index(&self, name: &str) -> Option<usize> { ... }
    fn pull_at(&mut self, index: usize) -> Value { ... }
    fn traverse_all(&mut self) -> Result<Vec<TraversalStream>, String> { ... }
}

A kernel on any engine: the interpreter, the closure tier, the hybrid kernel, or pure native code. Every engine accepts every program the interpreter accepts, or refuses it at construction with a reason, and computes the same values for the same inputs; the choice of engine changes how fast a program runs and nothing else. This trait is the surface a host drives an engine through without knowing which one it has.

The interpreter kernel and the compiled kernels also keep their inherent methods (raw slot readers, eval(&[u64]), engine_counts) as engine-specific extras; where a name is shared, the inherent method is the one a call on the concrete type reaches, and the trait’s is reached through dyn Kernel or Kernel::pull(&mut k, …).

Required Methods

fn engine(&self) -> Engine

The engine this kernel runs on.

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

Set the coordinate inputs for the next evaluation.

fn set_input(&mut self, name: &str, value: Value) -> Result<(), String>

Set an extern by name. One rule on every engine: the value must satisfy the declared port type (a carrier’s bit-stuffed forms included) or be None, which clears the extern; a value of another type is refused at the write, never healed. A coordinate is set with Self::set_inputs, not here. An unknown name is an error naming the known ones.

fn set_cursor( &mut self, name: &str, partition: &Partition, ) -> Result<(), String>

Narrow a cursor to one partition: its Ext slot and its six scalar projections are set.

fn eval(&mut self)

Evaluate every output for the inputs set so far.

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

The named output for the inputs set so far, evaluating what it needs and no more: the output’s cone, on the interpreter, the closure tier, and the hybrid kernel alike (pure native code, being one function, evaluates the program). A side channel in the cone fires when the output is pulled; a failing node fails when pulled, with the same attributed message on every engine: the node’s name, the outputs it feeds, the program’s context, and its inputs. The value is owned; a handle is never returned to the host, and a slot that holds None reads as None.

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

Every input by name, the coordinates first.

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

Every named output.

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

The declared port type of a named output.

fn externs(&self) -> Vec<(String, PortType)>

The externs by name and declared type.

fn cursor_schemas(&self) -> &[SourceSchema]

The cursors the program declares, with the partitions the compiler resolved where it could.

fn plan(&self) -> EnginePlan

What this kernel’s engine decided for the program: how much of it runs as native segments, as closure steps, and on the interpreter. The one planning detail a kernel exposes.

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

The value of a named input as the kernel holds it now, an extern or a coordinate; None for a name that is not an input.

fn traversals(&self) -> &[Traversal]

The traversals the program declares, in document order.

fn traverse(&mut self, index: usize) -> Result<TraversalStream, String>

Open the traversal at index against this kernel’s current values (SRD 113 §3.6): the comprehension’s sources see the wires they reference as this kernel holds them now, and the cascaded wires are snapshotted into every activation. On every engine (engine parity, step 8).

fn invalidate_all(&mut self)

Begin the next cycle with nothing current, so every step, a side channel included, runs again when pulled. The runtime model makes a cycle whose inputs did not move cost nothing; this is how a host runs such a cycle anyway, as the polydat binary does when every input is fixed.

fn shared_cells(&self) -> Vec<SharedCellEntry>

The cells this kernel’s shared bindings are bound to (scope model §6): one register per binding, which every kernel holding the cell reads and writes.

fn attach_shared_cell( &mut self, name: &str, cell: SharedCell, ) -> Result<(), String>

Bind the shared binding name to cell, so this kernel and every other holder of the cell read and write one register: a write on any of them is what the others read next, and a dependent output is recomputed. A name that is not a shared binding is an error naming the ones that are.

fn into_program(self: Box<Self>) -> Arc<dyn KernelProgram>

The program this kernel runs, shareable across threads: each thread creates its own kernel from it with KernelProgram::create_kernel.

Provided Methods

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

The index of a named input among Self::input_names, the coordinates first: what Self::set_input_at takes.

fn set_input_at(&mut self, index: usize, value: Value) -> Result<(), String>

Self::set_input by index, for a host that binds the same inputs every cycle: the name is resolved once, with Self::input_index, and no lookup runs per write.

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

The index of a named output among Self::output_names: what Self::pull_at takes.

fn pull_at(&mut self, index: usize) -> Value

Self::pull by index, for a host that reads the same outputs every cycle: the name is resolved once, with Self::output_index, and no lookup runs per pull.

fn traverse_all(&mut self) -> Result<Vec<TraversalStream>, String>

Open every traversal, in document order.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Kernel for CompiledKernelPull

impl Kernel for CompiledKernelPush

impl Kernel for CompiledKernelPushPull

impl Kernel for CompiledKernelRaw

impl Kernel for HybridKernelPull

impl Kernel for HybridKernelPushPull

impl Kernel for HybridKernelRaw

impl Kernel for PolydatKernel