Crate vihaco_runtime

Expand description

Component execution, composite metadata, and observation machinery.

The nondefault typed-declarations feature enables experimental typed execution and capability contracts, including derive support. It decouples the Component/Composite markers from HasInstructionSet; Cargo unification selects that contract for the shared runtime package instance. Declaration macros provide complete dialect/component capabilities and typed composite fields. Feature-off execution retains the existing declarations. The two declaration modes require separate Cargo feature graphs.

The nondefault program-image-execution feature implies typed-declarations and adds PopFromStack, PushToStack, typed stack access, and capability- gated message preparation. A #[program] device supplies program access and operand-storage wiring. Composite authors implement Steps and choose effect handling; program execution lives in stdlib.

With typed-declarations, #[dialect] gives public runtime instruction structs syntax parsers. Operand types retain their authored scope. Only immediate marked nongeneric unit/tuple structs belong to a dialect. Differing annotated operands generate a phase parameter defaulting to Runtime. Composite syntax aggregates lower through instruction-owned Lower implementations; unchanged instructions receive identity lowering.

use vihaco_runtime::{dialect, Parse, chumsky::Parser};

#[dialect]
pub mod arithmetic {
    #[instruction]
    pub struct Add(pub i64);

    #[instruction]
    #[pattern = "'stop"]
    pub struct Halt;
}

let source = arithmetic::Add::parser().parse("add -3")
    .into_result().unwrap();
assert_eq!(source, arithmetic::Add(-3));
let runtime = source;
assert_eq!(runtime.0, -3);

The attribute consumes instruction and pattern helpers, preserves module and field visibility, and supplies Clone/Debug/PartialEq without duplicating those authored derives. Named fields, generic or raw leaf names, conditional membership, and generated-name collisions are rejected. Gate the entire module with cfg/cfg_attr. Unannotated pattern bindings use their runtime field’s parser. A binding such as $0:u64 retains that syntax operand type; differing runtime types require explicit lowering. Parser annotations retain ordinary Rust type scope.

Re-exports§

pub use crate as runtime;
pub use chumsky;

Modules§

loader: Program-construction capabilities and legacy section-loading hooks.
metadata

Macros§

field: Name a composite field or nested route as a marker type.

Structs§

BytecodeSectionView: A lightweight view into a parsed bytecode section.
CompositeMetadata
NoMessage: Execution input for instructions that need no runtime-supplied message.
PopFromStack: Copied operands prepared for an instruction, distinct from its payload.
PushToStack: Results to insert during the framework’s effect-application phase.
Runtime: Executable operands, after instruction lowering.
SstSectionView: A lightweight view into a parsed SST section.
StackBatch: Owned operands in their original stack order.
StackBatchIntoIter: Consuming iterator over a StackBatch, without materializing another buffer.
Syntax: Retained source operands, before instruction lowering.

Enums§

Effects
InputCount: Where a homogeneous batch’s operand count is obtained.

Traits§

Apply: Framework hook to apply one effect during crate::Step.
BuildMessage: Build execution input for one composite field route and instruction type.
Component: An execution-capable device, independent of its executable instruction set.
Composite: A machine assembled from device fields, independent of executable selection.
Dispatch: Dispatch a composite instruction to its destination’s crate::Step.
EffectSink
Execute: Execute one instruction type with runtime-supplied input.
Field: Access a composite field route and describe its child type and source spellings.
GeneratedComponent
HasInstructionSet: The instruction types exposed by a device to its two execution layers.
HasOperandStack: Framework wiring from composite instruction preparation to operand storage.
HasProgram: Access to the composite’s execution-state device, supplied by #[program]. This selects mutable invocation state; the runner borrows program data separately. Instruction selection and PC management remain internal to stdlib execution.
Lower: Lower an instruction using the capabilities supplied by a program loader.
MemberOf: Membership of a type in a group identified by the marker type G.
Message
Observe
Parse: A parser whose input is &'src str (char stream) and whose error type is Simple<char>.
PopStack: Low-level typed operand access, excluding protected frame locals.
PushStack: Low-level typed insertion into logical stack storage.
Reset
StackInputCount: Count metadata for a component/instruction pair using crate::StackBatch.
StackValue: One copied logical stack value and its storage-representation conversions.
Step: Execution behavior for one composite field route and instruction type.
SurfaceInstruction: Marker for enums whose pattern-derived parser represents instruction syntax.

Functions§

expect_exactly_one_effect

Attribute Macros§

component: Declare a component’s complete dialect capabilities.
composite: Declare device fields and complete child capabilities.
dialect: Declare instructions with retained syntax operands and capability-based lowering.
dispatch: Adapt an authored execute method to the generated component runtime interface.
machine: Preserve the annotated item as the compatibility machine marker.
observe: Generate effect observer implementations from the annotated methods.

Derive Macros§

Instruction: Derive the bytecode-instruction traits (OpCode, FromBytesWithOpcode, WriteBytes) for an instruction enum.
Message: Mark a runtime-supplied message type with the Message trait.
Parse