Struct ExecFuture

pub struct ExecFuture<'a, S, OA, OG>
where
    S: StateRead,
{ /* private fields */ }

A future that when polled attempts to make progress on VM execution.

This poll implementation steps forward the VM by the stored operations, handling synchronous and asynchronous operations differently:

• For synchronous operations, it directly steps the VM to execute the operation.
• For asynchronous operations, it creates a future that will complete the operation and temporarily takes ownership of the VM. This future is stored in pending_op until it’s ready.

This type should not be constructed directly. Instead, it is used as a part of the implementation of Vm::exec and exposed publicly for documentation of its behaviour.

Yield Behavior

Execution yields in two scenarios:

• Asynchronous Operations: When an async operation is encountered, the method yields until the operation’s future is ready. This allows other tasks to run while awaiting the asynchronous operation to complete.
• Gas Yield Limit Reached: The method also yields based on a gas spending limit. If executing an operation causes gas.spent to exceed gas.next_yield_threshold, the method yields to allow the scheduler to run other tasks. This prevents long or complex sequences of operations from monopolizing CPU time.

Upon yielding, the method ensures that the state of the VM and the execution context (including gas counters and any pending operations) are preserved for when the poll method is called again.

Error Handling

Errors encountered during operation execution result in an immediate return of Poll::Ready(Err(...)), encapsulating the error within a ExecError. This includes errors from:

• Synchronous operations that fail during their execution.
• Asynchronous operations, where errors are handled once the future resolves.

The VM’s program counter will remain on the operation that caused the error.

Completion

The future completes (Poll::Ready(Ok(...))) when all operations have been executed and no more work remains. At this point, ownership over the VM is dropped and the total amount of gas spent during execution is returned. Attempting to poll the future after completion will panic.

Trait Implementations

impl<'a, S, OA, OG> Future for ExecFuture<'a, S, OA, OG>

where S: StateRead, OA: OpAccess<Op = Op> + Unpin, OG: OpGasCost, OA::Error: Into<OpError<S::Error>>,

type Output = Result<u64, ExecError<<S as StateRead>::Error>>

Returns a result with the total gas spent.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.