Crate massa_execution_worker

General description

The execution worker launches a persistent thread allowing the execution of operations that can contain executable bytecode and managing interactions with the ledger. When the worker is launched, a ExecutionManager and a ExecutionController are returned. ExecutionManager allows stopping the worker, and ExecutionController is the cloneable structure through which users interact with the worker.

The worker is fed through the ExecutionController with information about blockclique changes and newly finalized blocks and will execute the operations in those blocks, as well as pending asynchronous operations on empty slots. The worker can also query the current state of the ledger, and simulate operations in a read-only context.

The execution worker has shared read access to the final ledger, and must be the only module with runtime write access to the final ledger.

A note on finality

The operations contained in a final slot are ready to be executed as final only once all the previous slots are final and their operations are executed as final or ready to be so. This ensures the sequential order of the final executions of operations, thus ensuring that writes to the final ledger are irreversible.

Slots are called “active” if they have not been executed as final, and are not ready to be executed as final. Active slots can therefore be final slots, or slots containing blocks from the blockclique, or empty (miss) slots. Active slots can be executed in a speculative way: their execution might need to be reverted as new blocks finalize or arrive, causing changes to them or to active slots before them.

Miss slots are executed as well because they can contain implicit and asynchronous operations.

Architecture

This crate is meant to be included only at the binary level to launch the worker, not by the lib crates that will interact with it. It depends on the massa-execution-exports crate that contains all the publicly exposed elements and through which users will actually interact with the worker.

worker.rs

This module runs the main loop of the worker thread. It contains the logic to process incoming blockclique change notifications and read-only execution requests. It sequences the blocks according to their slot number into queues, and requests the execution of active and final slots to execution.rs.

slot_sequencer.rs

Implements SlotSequencer that allows sequencing slots for execution.

controller.rs

Implements ExecutionManager and ExecutionController that serve as interfaces for users to interact with the worker in worker.rs.

execution.rs

Contains the machinery to execute final and non-final slots, and track the state and results of those executions. This module initializes and holds a reference to the interface from interface_impl.rs that allows the crate to provide execution state access to the virtual machine runtime (massa-sc-runtime crate). It also serves as an access point to the current execution state and speculative ledger as defined in speculative_ledger.rs.

speculative_ledger.rs

A speculative (non-final) ledger that supports canceling already-executed operations in the case of some blockclique changes.

speculative_executed_ops.rs

A speculative (non-final) list of previously executed operations to prevent reuse.

request_queue.rs

This module contains the implementation of a generic finite-size execution request queue. It handles requests that come with an MPSC to send back the result of their execution once it’s done.

stats.rs

Defines a structure that gathers execution statistics.

execution-info

See documentation in execution_info.rs file.

Modules

• active_history 🔒
• context 🔒
  This module represents the context in which the VM executes bytecode. It provides information such as the current call stack. It also maintains a “speculative” ledger state which is a virtual ledger as seen after applying everything that happened so far in the context. More generally, the context acts only on its own state and does not write anything persistent to the consensus state.
• controller 🔒
  This module implements an execution controller. See massa-execution-exports/controller_traits.rs for functional details.
• datastore_scan 🔒
  A file describing an optimized datastore keys traversal algorithm. It is shared between execution.rs and speculative_ledger.rs.
• execution 🔒
  This module deals with executing final and active slots, as well as read-only requests. It also keeps a history of executed slots, thus holding the speculative state of the ledger.
• interface_impl 🔒
  Implementation of the interface between massa-execution-worker and massa-sc-runtime. This allows the VM runtime to access the Massa execution context, for example to interact with the ledger. See the definition of Interface in the massa-sc-runtime crate for functional details.
• request_queue 🔒
  This file defines a generic finite-size execution request queue with an MPSC-based result sender.
• slot_sequencer 🔒
  Copyright (c) 2022 MASSA LABS info@massa.net This module allows Execution to manage slot sequencing.
• speculative_async_pool 🔒
  The speculative asynchronous pool represents the state of the pool at an arbitrary execution slot.
• speculative_deferred_calls 🔒
  Speculative async call registry.
• speculative_executed_denunciations 🔒
  Copyright (c) 2023 MASSA LABS info@massa.net Speculative list of previously executed denunciations, to prevent reuse.
• speculative_executed_ops 🔒
  Copyright (c) 2022 MASSA LABS info@massa.net Speculative list of previously executed operations, to prevent reuse.
• speculative_ledger 🔒
  The speculative ledger represents, in a compressed way, the state of the ledger at an arbitrary execution slot. It never actually writes to the consensus state but keeps track of the changes that were applied to it since its creation.
• speculative_roll_state 🔒
• stats 🔒
  Copyright (c) 2022 MASSA LABS info@massa.net
• storage_backend
  Provide abstraction and implementations of a storage backend for the the dump-block feature
• worker 🔒
  Copyright (c) 2022 MASSA LABS info@massa.net This module allows launching the execution worker thread, returning objects to communicate with it. The worker thread processes incoming notifications of blockclique changes, orders active and final blocks in queues sorted by increasing slot number, and requests the execution of active and final slots from execution.rs.

Functions

• start_execution_worker
  Launches an execution worker thread and returns an ExecutionManager to interact with it