vihaco / virtual ISA & machine framework
Author’s guide
  1. Start here
  2. The mental model
  3. Your first machine
  4. Essential concepts
  5. Dialects and instructions
  6. Writing components
  7. Preparing messages
  8. Stack inputs and outputs
  9. Writing composites
  10. Executing one instruction
  11. Handling effects
  12. Running programs
  13. Images and Loadables
  14. Parsing source
  15. Loading SST programs
  16. Emitting SST from a compiler
  17. Binary formats
  18. Patterns for larger machines
  19. Testing and extending
  20. Pattern parser reference

Preparing messages

A component knows what input it needs, but it doesn’t need to know where that input comes from. A message can hold operands, values from an instruction field, information from program metadata, or data from another device. The component’s Execute<I>::Message tells the caller which type to supply.

Composite-specific construction

BuildMessage<F, I, Context, M> is the composite-specific construction interface. The composite author implements it to decide how that machine builds input for instruction I at field route F. Usually callers can leave M at its default, the child’s message type. Context defaults to (); the program runner passes the borrowed module instead.

The body of build_message can read machine-specific state, apply application policy, or explicitly call a message’s ReusableMessageRecipe::prepare. Recipes provide reusable logic; they do not automatically implement BuildMessage for a composite.

Your step can call build_message(instruction, context) before calling the device. The builder takes &mut self because it may consume operands. Its job ends when the message is ready: your step still needs to execute the operation and handle the result. Implementing a builder doesn’t create that step.

Custom messages

When preparation needs something specific to your application, give it a distinct message type. Here the builder reads a prefix from the composite:

use vihaco::{BuildMessage, Execute, component, composite, dialect, field};

#[dialect]
mod display {
    #[instruction]
    pub struct Show;
}

struct Prefix(String);

#[component]
#[instructions { display }]
struct Display;

impl Execute<display::Show> for Display {
    type Message = Prefix;
    type Effect = String;
    type Error = eyre::Report;
    fn execute(&mut self, _: &display::Show, prefix: Prefix) -> eyre::Result<String> {
        Ok(prefix.0)
    }
}

#[composite]
struct Machine {
    #[device(1)]
    display: Display,
    prefix: String,
}

impl BuildMessage<field!(Machine::display), display::Show, (), Prefix> for Machine {
    fn build_message(&mut self, _: &display::Show, _: &()) -> eyre::Result<Prefix> {
        Ok(Prefix(self.prefix.clone()))
    }
}

fn main() -> eyre::Result<()> {
    let mut machine = Machine { display: Display, prefix: "result: ".into() };
    let message = machine.build_message(&display::Show, &())?;
    assert_eq!(machine.display.execute(&display::Show, message)?, "result: ");
    Ok(())
}

Name M explicitly when separating generic builders for different message shapes, as this example does with Prefix. M must still match the child’s execution message; it can’t change the associated type. A custom builder can also construct a message owned by another crate, even when that message has a reusable recipe. The composite chooses whether to use it.

Reusable recipes from message authors

ReusableMessageRecipe<Parent, Route, I, Context> is how upstream message authors provide a generic way to build their messages over arbitrary machines with specific capabilities. Implement it on the message type, with bounds on Parent describing capabilities such as operand-stack access. The recipe can use instruction data and a shared read-only context without depending on a specific composite’s fields or layout.

Machines use a reusable recipe by explicitly calling it inside the body of their BuildMessage::build_message implementation. This keeps the decision with the composite author. Here upstream represents a separate message library; its recipe needs only HasOperandStack<I> and word-valued PopStack access:

use vihaco::{
    BuildMessage, Execute, ExecutionState, PushStack, ReusableMessageRecipe,
    component, composite, dialect, field,
};

mod upstream {
    use vihaco::{HasOperandStack, PopStack, ReusableMessageRecipe};

    pub struct Pair(pub u64, pub u64);

    impl<C, F, I, Context: ?Sized> ReusableMessageRecipe<C, F, I, Context> for Pair
    where
        C: HasOperandStack<I>,
        C::Source: PopStack<u64>,
    {
        fn prepare(machine: &mut C, _: &I, _: &Context) -> eyre::Result<Self> {
            let stack = machine.operand_stack(2);
            let rhs = stack.pop()?;
            let lhs = stack.pop()?;
            Ok(Self(lhs, rhs))
        }
    }
}

#[dialect]
mod arithmetic {
    #[instruction]
    pub struct Add;
}

#[component]
#[instructions { arithmetic }]
struct Calculator;

impl Execute<arithmetic::Add> for Calculator {
    type Message = upstream::Pair;
    type Effect = u64;
    type Error = eyre::Report;

    fn execute(&mut self, _: &arithmetic::Add, pair: upstream::Pair) -> eyre::Result<u64> {
        pair.0.checked_add(pair.1).ok_or_else(|| eyre::eyre!("addition overflow"))
    }
}

#[composite]
struct Machine {
    #[device(0)]
    #[program]
    execution: vihaco_stdlib::ExecutionState,
    #[device(1)]
    calculator: Calculator,
}

impl<I> BuildMessage<field!(Machine::calculator), I, (), upstream::Pair> for Machine
where
    Calculator: Execute<I, Message = upstream::Pair>,
{
    fn build_message(&mut self, instruction: &I, context: &()) -> eyre::Result<upstream::Pair> {
        <upstream::Pair as ReusableMessageRecipe<
            Self, field!(Machine::calculator), I, (),
        >>::prepare(self, instruction, context)
    }
}

fn main() -> eyre::Result<()> {
    let mut machine = Machine { execution: ExecutionState::new(), calculator: Calculator };
    // Operand access requires a running invocation, as in the first-machine example.
    use vihaco::module::{FunctionInfo, LocalModule, Signature};
    let program: LocalModule<(), vihaco::Value, vihaco::Type> = LocalModule {
        code: vec![()], main_function: Some(0),
        functions: vec![FunctionInfo {
            name: 0, signature: Signature { params: vec![], ret: vec![] },
            local_count: 0, start_address: 0, end_address: 1, file: 0,
        }], ..Default::default()
    };
    machine.execution.start(&program, &[])?;
    machine.execution.push(20_u64);
    machine.execution.push(22_u64);
    let message = machine.build_message(&arithmetic::Add, &())?;
    assert_eq!(machine.calculator.execute(&arithmetic::Add, message)?, 42);
    assert!(machine.execution.stack().is_empty());
    Ok(())
}

Route lets recipes select a device or require device-specific capabilities. Context may be unsized and can carry program metadata or other read-only data. The machine remains mutable so a recipe can consume operands. A recipe can work across many composites; it does not need a per-composite implementation from the message’s author.

Standard recipes and migration

Vihaco supplies ReusableMessageRecipe implementations for NoMessage, PopFromStack tuples and batches, and stdlib execution messages. Composite builders explicitly delegate to them, just as in the example above. See the first machine for delegation shared across the standard message types of a device.

A builder generic over every message type opts that whole device into recipes. If some messages need custom construction, use separate builders with explicit message types, as in the message-kind pattern, instead of overlapping a general delegating implementation with a specialized one.

When migrating from automatic preparation, add these delegating BuildMessage implementations to your composite. AutomaticMessage and the automatic BuildMessage blanket implementation have been removed, and PrepareMessage is now named ReusableMessageRecipe. Existing custom BuildMessage implementations can keep their construction logic. If you previously implemented the hidden recipe traits, rename PrepareMessage and remove AutomaticMessage.

Context and validation

If your builder needs read-only information from outside the machine, such as function metadata or strings, give it a context type. Dispatch passes that context to the step, and the step can pass it to the builder. The component receives the prepared message.

The builder is also a place to check references and input requirements that depend on how the runtime is organized. Pay attention to when you consume input: an error won’t restore earlier changes. Add error context when it helps identify the operation or reference that failed.

Several instructions can share preparation through the message-kind pattern. For input that comes straight from operands, start with the standard stack protocols.

On this page
  1. Composite-specific construction
  2. Custom messages
  3. Reusable recipes from message authors
  4. Standard recipes and migration
  5. Context and validation