Struct Scheduler

pub struct Scheduler<DL>
where
    DL: CellDataProvider + HeaderProvider + ExtensionProvider + Send + Sync + Clone + 'static,
{

    pub tx_data: TxData<DL>,
    pub script_version: ScriptVersion,
    pub syscalls_generator: TransactionScriptsSyscallsGenerator<DL>,
    pub total_cycles: Cycle,
    pub current_iteration_cycles: Cycle,
    pub next_vm_id: u64,
    pub next_fd_slot: u64,
    pub states: BTreeMap<u64, VmState>,
    pub fds: BTreeMap<Fd, u64>,
    pub inherited_fd: BTreeMap<u64, Vec<Fd>>,
    pub instantiated: BTreeMap<u64, (MachineContext<DL>, AsmMachine)>,
    pub suspended: BTreeMap<u64, Snapshot2<DataPieceId>>,
    pub terminated_vms: BTreeMap<u64, i8>,
    pub message_box: Arc<Mutex<Vec<Message>>>,
}

A single Scheduler instance is used to verify a single script within a CKB transaction.

A scheduler holds & manipulates a core, the scheduler also holds all CKB-VM machines, each CKB-VM machine also gets a mutable reference of the core for IO operations.

Fields

tx_data: TxData<DL>

Context data for current running transaction & script.

script_version: ScriptVersion

In fact, Scheduler here has the potential to totally replace TransactionScriptsVerifier, nonetheless much of current syscall implementation is strictly tied to TransactionScriptsVerifier, we are using it here to save some extra code.

syscalls_generator: TransactionScriptsSyscallsGenerator<DL>

Generate system calls.

total_cycles: Cycle

Total cycles.

current_iteration_cycles: Cycle

Current iteration cycles. This value is periodically added to total_cycles and cleared

next_vm_id: u64

Next vm id used by spawn.

next_fd_slot: u64

Next fd used by pipe.

states: BTreeMap<u64, VmState>

Used to store VM state.

fds: BTreeMap<Fd, u64>

Used to confirm the owner of fd.

inherited_fd: BTreeMap<u64, Vec<Fd>>

Verify the VM’s inherited fd list.

instantiated: BTreeMap<u64, (MachineContext<DL>, AsmMachine)>

Instantiated vms.

suspended: BTreeMap<u64, Snapshot2<DataPieceId>>

Suspended vms.

terminated_vms: BTreeMap<u64, i8>

Terminated vms.

message_box: Arc<Mutex<Vec<Message>>>

MessageBox is expected to be empty before returning from run function, there is no need to persist messages.

Implementations

impl<DL> Scheduler<DL>

where DL: CellDataProvider + HeaderProvider + ExtensionProvider + Send + Sync + Clone + 'static,

pub fn new( tx_data: TxData<DL>, script_version: ScriptVersion, syscalls_generator: TransactionScriptsSyscallsGenerator<DL>, ) -> Self

Create a new scheduler from empty state

pub fn consumed_cycles(&self) -> Cycle

Return total cycles.

pub fn consumed_cycles_add(&mut self, cycles: Cycle) -> Result<(), Error>

Add cycles to total cycles.

pub fn resume( tx_data: TxData<DL>, script_version: ScriptVersion, syscalls_generator: TransactionScriptsSyscallsGenerator<DL>, full: FullSuspendedState, ) -> Self

Resume a previously suspended scheduler state

pub fn suspend(self) -> Result<FullSuspendedState, Error>

Suspend current scheduler into a serializable full state

pub fn run(&mut self, mode: RunMode) -> Result<(i8, Cycle), Error>

This is the only entrypoint for running the scheduler, both newly created instance and resumed instance are supported. It accepts 2 run mode, one can either limit the cycles to execute, or use a pause signal to trigger termination.

Only when the execution terminates without VM errors, will this function return an exit code(could still be non-zero) and total consumed cycles.

Err would be returned in the following cases:

• Cycle limit reached, the returned error would be ckb_vm::Error::CyclesExceeded,
• Pause trigger, the returned error would be ckb_vm::Error::Pause,
• Other terminating errors

pub fn iterate_prepare_machine( &mut self, pause: Pause, limit_cycles: Cycle, ) -> Result<(u64, &mut AsmMachine), Error>

Returns the machine that needs to be executed in the current iterate.

pub fn iterate_process_results( &mut self, vm_id_to_run: u64, result: Result<i8, Error>, cycles: u64, ) -> Result<(), Error>

Process machine execution results in the current iterate.

pub fn boot_vm( &mut self, data_piece_id: &DataPieceId, offset: u64, length: u64, args: &[Bytes], ) -> Result<u64, Error>

Boot a vm by given program and args.