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 starts with a fixed buffer size defined by INITIAL_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 execute_sync( self, program: &Program, host: &mut impl SyncHost, ) -> Result<ExecutionOutput, ExecutionError>

Executes the given program synchronously and returns the execution output.

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

Async variant of Self::execute_sync for hosts that need async callbacks.

pub fn execute_trace_inputs_sync( self, program: &Program, host: &mut impl SyncHost, ) -> Result<TraceBuildInputs, ExecutionError>

Executes the given program synchronously and returns the bundled trace inputs required by crate::trace::build_trace.

Example

use miden_assembly::Assembler;
use miden_processor::{DefaultHost, FastProcessor, StackInputs};

let program = Assembler::default().assemble_program("begin push.1 drop end").unwrap();
let mut host = DefaultHost::default();

let trace_inputs = FastProcessor::new(StackInputs::default())
    .execute_trace_inputs_sync(&program, &mut host)
    .unwrap();
let trace = miden_processor::trace::build_trace(trace_inputs).unwrap();

assert_eq!(*trace.program_hash(), program.hash());

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

Async variant of Self::execute_trace_inputs_sync for async hosts.

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

where T: Tracer<Processor = FastProcessor>,

Executes the given program with the provided tracer using an async host.

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

where T: Tracer<Processor = FastProcessor>,

Executes the given program with the provided tracer using a sync host.

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

Executes a single clock cycle synchronously.

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

Async variant of Self::step_sync.

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

Executes the given program synchronously one step at a time.

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

Async variant of Self::execute_by_step_sync.

impl FastProcessor

pub fn new(stack_inputs: StackInputs) -> FastProcessor

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)
    .expect("advice inputs should fit advice map limits")
    .with_debugging(true)
    .with_tracing(true);

When using non-default advice map limits, prefer Self::new_with_options so the advice inputs are validated against the intended execution options.

pub fn with_advice( self, advice_inputs: AdviceInputs, ) -> Result<FastProcessor, AdviceError>

Sets the advice inputs for the processor.

Advice inputs are loaded into the live advice provider immediately and are validated against the processor’s current ExecutionOptions. If the advice map needs non-default limits, construct the processor with Self::new_with_options or call Self::with_options before calling this method.

pub fn with_options( self, options: ExecutionOptions, ) -> Result<FastProcessor, AdviceError>

Sets the execution options for the processor.

This will override any previously set debugging or tracing settings.

Existing advice inputs are revalidated against the new options before they are applied. To load advice inputs that require non-default advice map limits, call this before Self::with_advice or use Self::new_with_options.

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

Enables or disables debugging mode.

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

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

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, ) -> Result<FastProcessor, AdviceError>

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_sync().

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.

This method is only meant to be used to access the stack top by operation handlers, and system event handlers.

Preconditions

• idx must be less than or equal to 15.

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

Same as Self::stack_get(), but returns ZERO if idx falls below index 0 in the stack buffer.

Use this instead of stack_get() when idx may exceed 15.

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

Mutable variant of stack_get().

This method is only meant to be used to access the stack top by operation handlers, and system event handlers.

Preconditions

• idx must be less than or equal to 15.

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.

This method is only meant to be used to access the stack top by operation handlers, and system event handlers.

Preconditions

• start_idx must be less than or equal to 12.

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

Same as Self::stack_get_word(), but returns ZERO for any element that falls below index 0 in the stack buffer.

Use this instead of stack_get_word() when start_idx + WORD_SIZE may exceed stack_top_idx.

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 into_parts(self) -> (AdviceProvider, Memory, PrecompileTranscript)

Consumes the processor and returns the advice provider, memory, and precompile transcript.

pub fn execution_options(&self) -> &ExecutionOptions

Returns a reference to the execution options.

pub fn state(&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.

Trait Implementations

impl Debug for FastProcessor

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

Formats the value using the given formatter.