Struct Executor

#[repr(C)]
pub struct Executor<'a> {

    pub program: Arc<Program>,
    pub executor_mode: ExecutorMode,
    pub unconstrained: bool,
    pub print_report: bool,
    pub shard_size: u32,
    pub shard_batch_size: u32,
    pub max_syscall_cycles: u32,
    pub syscall_map: HashMap<SyscallCode, Arc<dyn Syscall>>,
    pub opts: SP1CoreOpts,
    pub memory_checkpoint: PagedMemory<Option<MemoryRecord>>,
    pub uninitialized_memory_checkpoint: PagedMemory<bool>,
    pub memory_accesses: MemoryAccessRecord,
    pub max_cycles: Option<u64>,
    pub state: ExecutionState,
    pub record: ExecutionRecord,
    pub records: Vec<ExecutionRecord>,
    pub local_memory_access: HashMap<u32, MemoryLocalEvent>,
    pub cycle_tracker: HashMap<String, (u64, u32)>,
    pub io_buf: HashMap<u32, String>,
    pub trace_buf: Option<BufWriter<File>>,
    pub unconstrained_state: ForkState,
    pub report: ExecutionReport,
    pub subproof_verifier: Arc<dyn SubproofVerifier + 'a>,
    pub hook_registry: HookRegistry<'a>,
    pub maximal_shapes: Option<Vec<HashMap<String, usize>>>,
}

An executor for the SP1 RISC-V zkVM.

The exeuctor is responsible for executing a user program and tracing important events which occur during execution (i.e., memory reads, alu operations, etc).

Fields

program: Arc<Program>

The program.

executor_mode: ExecutorMode

The mode the executor is running in.

unconstrained: bool

Whether the runtime is in constrained mode or not.

In unconstrained mode, any events, clock, register, or memory changes are reset after leaving the unconstrained block. The only thing preserved is writes to the input stream.

print_report: bool

Whether we should write to the report.

shard_size: u32

The maximum size of each shard.

shard_batch_size: u32

The maximum number of shards to execute at once.

max_syscall_cycles: u32

The maximum number of cycles for a syscall.

syscall_map: HashMap<SyscallCode, Arc<dyn Syscall>>

The mapping between syscall codes and their implementations.

opts: SP1CoreOpts

The options for the runtime.

memory_checkpoint: PagedMemory<Option<MemoryRecord>>

Memory addresses that were touched in this batch of shards. Used to minimize the size of checkpoints.

uninitialized_memory_checkpoint: PagedMemory<bool>

Memory addresses that were initialized in this batch of shards. Used to minimize the size of checkpoints. The value stored is whether or not it had a value at the beginning of the batch.

memory_accesses: MemoryAccessRecord

The memory accesses for the current cycle.

max_cycles: Option<u64>

The maximum number of cpu cycles to use for execution.

state: ExecutionState

The state of the execution.

record: ExecutionRecord

The current trace of the execution that is being collected.

records: Vec<ExecutionRecord>

The collected records, split by cpu cycles.

local_memory_access: HashMap<u32, MemoryLocalEvent>

Local memory access events.

cycle_tracker: HashMap<String, (u64, u32)>

A counter for the number of cycles that have been executed in certain functions.

io_buf: HashMap<u32, String>

A buffer for stdout and stderr IO.

trace_buf: Option<BufWriter<File>>

A buffer for writing trace events to a file.

unconstrained_state: ForkState

The state of the runtime when in unconstrained mode.

report: ExecutionReport

Report of the program execution.

subproof_verifier: Arc<dyn SubproofVerifier + 'a>

Verifier used to sanity check verify_sp1_proof during runtime.

hook_registry: HookRegistry<'a>

Registry of hooks, to be invoked by writing to certain file descriptors.

maximal_shapes: Option<Vec<HashMap<String, usize>>>

The maximal shapes for the program.

Implementations

impl<'a> Executor<'a>

pub fn new(program: Program, opts: SP1CoreOpts) -> Self

Create a new Executor from a program and options.

pub fn with_context( program: Program, opts: SP1CoreOpts, context: SP1Context<'a>, ) -> Self

Create a new runtime from a program, options, and a context.

Panics

This function may panic if it fails to create the trace file if TRACE_FILE is set.

pub fn hook(&self, fd: u32, buf: &[u8]) -> Result<Vec<Vec<u8>>>

Invokes a hook with the given file descriptor fd with the data buf.

Errors

If the file descriptor is not found in the HookRegistry, this function will return an error.

pub fn hook_env<'b>(&'b self) -> HookEnv<'b, 'a>

Prepare a HookEnv for use by hooks.

pub fn recover( program: Program, state: ExecutionState, opts: SP1CoreOpts, ) -> Self

Recover runtime state from a program and existing execution state.

pub fn registers(&mut self) -> [u32; 32]

Get the current values of the registers.

pub fn register(&mut self, register: Register) -> u32

Get the current value of a register.

pub fn word(&mut self, addr: u32) -> u32

Get the current value of a word.

pub fn byte(&mut self, addr: u32) -> u8

Get the current value of a byte.

pub const fn timestamp(&self, position: &MemoryAccessPosition) -> u32

Get the current timestamp for a given memory access position.

pub fn shard(&self) -> u32

Get the current shard.

pub fn mr( &mut self, addr: u32, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryReadRecord

Read a word from memory and create an access record.

pub fn mw( &mut self, addr: u32, value: u32, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryWriteRecord

Write a word to memory and create an access record.

pub fn mr_cpu(&mut self, addr: u32, position: MemoryAccessPosition) -> u32

Read from memory, assuming that all addresses are aligned.

pub fn mw_cpu(&mut self, addr: u32, value: u32, position: MemoryAccessPosition)

Write to memory.

Panics

This function will panic if the address is not aligned or if the memory accesses are already initialized.

pub fn rr(&mut self, register: Register, position: MemoryAccessPosition) -> u32

Read from a register.

pub fn rw(&mut self, register: Register, value: u32)

Write to a register.

pub fn bump_record(&mut self)

Bump the record.

pub fn execute_record( &mut self, ) -> Result<(Vec<ExecutionRecord>, bool), ExecutionError>

Execute up to self.shard_batch_size cycles, returning the events emitted and whether the program ended.

Errors

This function will return an error if the program execution fails.

pub fn execute_state( &mut self, ) -> Result<(ExecutionState, bool), ExecutionError>

Execute up to self.shard_batch_size cycles, returning the checkpoint from before execution and whether the program ended.

Errors

This function will return an error if the program execution fails.

pub fn run_fast(&mut self) -> Result<(), ExecutionError>

Executes the program without tracing and without emitting events.

Errors

This function will return an error if the program execution fails.

pub fn run(&mut self) -> Result<(), ExecutionError>

Executes the program and prints the execution report.

Errors

This function will return an error if the program execution fails.

pub fn execute(&mut self) -> Result<bool, ExecutionError>

Executes up to self.shard_batch_size cycles of the program, returning whether the program has finished.

impl<'a> Executor<'a>

pub fn write_stdin<T: Serialize>(&mut self, input: &T)

Write a serializable input to the standard input stream.

pub fn write_stdin_slice(&mut self, input: &[u8])

Write a slice of bytes to the standard input stream.

pub fn write_vecs(&mut self, inputs: &[Vec<u8>])

Write a slice of vecs to the standard input stream.

pub fn write_proof( &mut self, proof: SP1ReduceProof<BabyBearPoseidon2>, vk: StarkVerifyingKey<BabyBearPoseidon2>, )

Write a proof and verifying key to the proof stream.

pub fn read_public_values<T: DeserializeOwned>(&mut self) -> T

Read a serializable public values from the public values stream.

pub fn read_public_values_slice(&mut self, buf: &mut [u8])

Read a slice of bytes from the public values stream.

Trait Implementations

impl<'a> Read for Executor<'a>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.