Struct stack_vm::Machine

pub struct Machine<'a, T: 'a + Debug> {
    pub code: Code<T>,
    pub instruction_table: &'a InstructionTable<T>,
    pub ip: usize,
    pub constants: &'a dyn Table<Item = T>,
    pub call_stack: Stack<Frame<T>>,
    pub operand_stack: Stack<T>,
}

Machine contains all the information needed to run your program.

• A Code, used describe the source instructions and data to execute.
• An instruction pointer, which points to the currently-executing instruciton.
• A Table of constants, which you can use in your instructions if needed.
• A Stack of Frame used to keep track of calls being executed.
• A Stack of T which is used as the main operand stack.

Fields

code: Code<T>

instruction_table: &'a InstructionTable<T>

ip: usize

constants: &'a dyn Table<Item = T>

call_stack: Stack<Frame<T>>

operand_stack: Stack<T>

Methods

impl<'a, T: 'a + Debug> Machine<'a, T>

pub fn new(
    code: Code<T>,
    constants: &'a dyn Table<Item = T>,
    instruction_table: &'a InstructionTable<T>
) -> Machine<'a, T>

Returns a new Machine ready to execute instructions.

The machine is initialised by passing in your Code which contains all the code and data of your program, and a Table of constants`.

pub fn run(&mut self)

Run the machine.

Kick off the process of running the program.

Steps through the instructions in your program executing them one-by-one. Each instruction function is executed, much like a callback.

Stops when either the last instruction is executed or when the last frame is removed from the call stack.

pub fn get_local(&self, name: &str) -> Option<&T>

Look up a local variable in the current call frame.

Note that the variable may not be set in the current frame but it's up to your instruction to figure out how to deal with this situation.

pub fn get_local_deep(&self, name: &str) -> Option<&T>

Look for a local variable in all call frames.

The machine will look in each frame in the call stack starting at the top and moving down until it locates the local variable in question or runs out of stack frames.

pub fn set_local(&mut self, name: &str, value: T)

Set a local variable in the current call frame.

Places a value in the frame's local variable table.

pub fn operand_push(&mut self, value: T)

Push an operand onto the operand stack.

pub fn operand_pop(&mut self) -> T

Pop an operand off the operand stack.

pub fn get_data(&self, idx: usize) -> &T

Retrieve a reference to a T stored in the Code's data section.

pub fn jump(&mut self, label: &str)

Perform a jump to a named label.

This method performs the following actions:

• Retrieve the instruction pointer for a given label from the Code.
• Set the machine's instruction pointer to the new location.

This method will panic the thread if the label does not exist.

pub fn call(&mut self, label: &str)

Performs a call to a named label.

This method is very similar to jump except that it records it's current instruction pointer and saves it in the call stack.

This method performs the following actions:

• Create a new frame with it's return address set to the current instruction pointer.
• Jump to the named label using jump.

This method specifically does not transfer operands to call arguments.

pub fn ret(&mut self)

Performs a return.

This method pops the top frame off the call stack and moves the instruction pointer back to the frame's return address. It's up to you to push your return value onto the operand stack (if your language has such return semantics).

The last call frame contains a return address at the end of the source code, so the machine will stop executing at the beginning of the next iteration.

If you call ret too many times then the machine will panic when it attempts to pop the last frame off the stack.