Struct FastProcessor 

pub struct FastProcessor { /* private fields */ }

A fast processor which doesn’t generate any trace.

This processor is designed to be as fast as possible. Hence, it only keeps track of the current state of the processor (i.e. the stack, current clock cycle, current memory context, and free memory pointer).

Stack Management

A few key points about how the stack was designed for maximum performance:

• The stack has a fixed buffer size defined by STACK_BUFFER_SIZE.
  • This was observed to increase performance by at least 2x compared to using a Vec with push() & pop().
  • We track the stack top and bottom using indices stack_top_idx and stack_bot_idx, respectively.
• Since we are using a fixed-size buffer, we need to ensure that stack buffer accesses are not out of bounds. Naively, we could check for this on every access. However, every operation alters the stack depth by a predetermined amount, allowing us to precisely determine the minimum number of operations required to reach a stack buffer boundary, whether at the top or bottom.
  • For example, if the stack top is 10 elements away from the top boundary, and the stack bottom is 15 elements away from the bottom boundary, then we can safely execute 10 operations that modify the stack depth with no bounds check.
• When switching contexts (e.g., during a call or syscall), all elements past the first 16 are stored in an ExecutionContextInfo struct, and the stack is truncated to 16 elements. This will be restored when returning from the call or syscall.

Clock Cycle Management

• The clock cycle (clk) is managed in the same way as in Process. That is, it is incremented by 1 for every row that Process adds to the main trace.
  • It is important to do so because the clock cycle is used to determine the context ID for new execution contexts when using call or dyncall.

Implementations

impl FastProcessor

pub fn new(stack_inputs: StackInputs) -> Self

Creates a new FastProcessor instance with the given stack inputs.

By default, advice inputs are empty and execution options use their defaults (debugging and tracing disabled).

Example

use miden_processor::FastProcessor;

let processor = FastProcessor::new(stack_inputs)
    .with_advice(advice_inputs)
    .with_debugging(true)
    .with_tracing(true);

pub fn with_advice(self, advice_inputs: AdviceInputs) -> Self

Sets the advice inputs for the processor.

pub fn with_options(self, options: ExecutionOptions) -> Self

Sets the execution options for the processor.

This will override any previously set debugging or tracing settings.

pub fn with_debugging(self, enabled: bool) -> Self

Enables or disables debugging mode.

When debugging is enabled, debug decorators will be executed during program execution.

pub fn with_tracing(self, enabled: bool) -> Self

Enables or disables tracing mode.

When tracing is enabled, trace decorators will be executed during program execution.

pub fn new_with_options( stack_inputs: StackInputs, advice_inputs: AdviceInputs, options: ExecutionOptions, ) -> Self

Constructor for creating a FastProcessor with all options specified at once.

For a more fluent API, consider using FastProcessor::new() with builder methods.

pub fn get_initial_resume_context( &mut self, program: &Program, ) -> Result<ResumeContext, ExecutionError>

Returns the resume context to be used with the first call to step().

pub fn in_debug_mode(&self) -> bool

Returns whether the processor is executing in debug mode.

pub fn stack(&self) -> &[Felt]

Returns the stack, such that the top of the stack is at the last index of the returned slice.

pub fn stack_top(&self) -> &[Felt]

Returns the top 16 elements of the stack.

pub fn stack_top_mut(&mut self) -> &mut [Felt]

Returns a mutable reference to the top 16 elements of the stack.

pub fn stack_get(&self, idx: usize) -> Felt

Returns the element on the stack at index idx.

pub fn stack_get_mut(&mut self, idx: usize) -> &mut Felt

Mutable variant of stack_get().

pub fn stack_get_word(&self, start_idx: usize) -> Word

Returns the word on the stack starting at index start_idx in “stack order”.

For start_idx=0 the top element of the stack will be at position 0 in the word.

For example, if the stack looks like this:

top bottom v v a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p

Then

• stack_get_word(0) returns [a, b, c, d],
• stack_get_word(1) returns [b, c, d, e],
• etc.

pub fn stack_depth(&self) -> u32

Returns the number of elements on the stack in the current context.

pub fn memory(&self) -> &Memory

Returns a reference to the processor’s memory.

pub fn state(&mut self) -> ProcessorState<'_>

Returns a narrowed interface for reading and updating the processor state.

pub fn stack_write(&mut self, idx: usize, element: Felt)

Writes an element to the stack at the given index.

pub fn stack_write_word(&mut self, start_idx: usize, word: &Word)

Writes a word to the stack starting at the given index.

word[0] goes to stack position start_idx (top), word[1] to start_idx+1, etc.

pub fn stack_swap(&mut self, idx1: usize, idx2: usize)

Swaps the elements at the given indices on the stack.

pub async fn execute( self, program: &Program, host: &mut impl Host, ) -> Result<ExecutionOutput, ExecutionError>

Executes the given program and returns the stack outputs as well as the advice provider.

pub async fn execute_for_trace( self, program: &Program, host: &mut impl Host, ) -> Result<(ExecutionOutput, TraceGenerationContext), ExecutionError>

Executes the given program and returns the stack outputs, the advice provider, and context necessary to build the trace.

pub async fn execute_with_tracer<T>( self, program: &Program, host: &mut impl Host, tracer: &mut T, ) -> Result<ExecutionOutput, ExecutionError>

where T: Tracer<Processor = Self>,

Executes the given program with the provided tracer and returns the stack outputs, and the advice provider.

pub async fn step( &mut self, host: &mut impl Host, resume_ctx: ResumeContext, ) -> Result<Option<ResumeContext>, ExecutionError>

Executes a single clock cycle

pub fn step_sync( &mut self, host: &mut impl Host, resume_ctx: ResumeContext, ) -> Result<Option<ResumeContext>, ExecutionError>

Convenience sync wrapper to Self::step.

pub fn execute_by_step_sync( self, program: &Program, host: &mut impl Host, ) -> Result<StackOutputs, ExecutionError>

Executes the given program step by step (calling Self::step repeatedly) and returns the stack outputs.

pub fn execute_sync( self, program: &Program, host: &mut impl Host, ) -> Result<ExecutionOutput, ExecutionError>

Convenience sync wrapper to Self::execute.

This method is only available on non-wasm32 targets. On wasm32, use the async execute() method directly since wasm32 runs in the browser’s event loop.

Panics

Panics if called from within an existing Tokio runtime. Use the async execute() method instead in async contexts.

pub fn execute_for_trace_sync( self, program: &Program, host: &mut impl Host, ) -> Result<(ExecutionOutput, TraceGenerationContext), ExecutionError>

Convenience sync wrapper to Self::execute_for_trace.

This method is only available on non-wasm32 targets. On wasm32, use the async execute_for_trace() method directly since wasm32 runs in the browser’s event loop.

Panics

Panics if called from within an existing Tokio runtime. Use the async execute_for_trace() method instead in async contexts.

Trait Implementations

impl Debug for FastProcessor

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

Formats the value using the given formatter.