Documentation
¶
Overview ¶
Package checkpoint provides the data structures used to capture (a snapshot of) the state of an executing machine, so that execution can later be resumed from that point. See CheckPoint for the central type and a discussion of how such snapshots may be optimised.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CheckPoint ¶
CheckPoint represents a captured state of an executing machine, such that execution can be continued later from this position (sometimes also known as a "continuation"). As such, the checkpoint must include all information necessary to allow execution to continue. However, to reduce the size of a checkpoint, certain optimsiations of this information are permitted. As such, implementations can manage this information in different ways (e.g. using compression, read-access lists, page-access lists, etc).
For example suppose that a machine, upon reaching the checkpoint, has 1GB of some RAM allocated. A full checkpoint would include all of this data and, therefore, be at least 1GB in size. Suppose, however, that executing the machine from this point onwards only requires accessing 1MB of data from that RAM. Then, in fact, a valid implementation might only store that 1MB of information (e.g. to reduce network transport costs, or proof size, etc).
Finally, to support more aggressive optimisation, checkpoints have a notion of their "validity window". To understand this, consider a refinement of the example above. Suppose there are M execution steps remaining from the checkpoint until the machine terminates, but that executing these M steps now requires the full 1GB of RAM. However, we now suppose that executing the next N steps requires accessing only 1MB of that RAM. Then, the checkpoint may only store that 1MB of data if it is marked as being valid for (upto) N steps of execution. The purpose of this is to allow a program's execution to be broken up into multiple checkpoints, such that each checkpoint only stores the data it requires for executing its portion of the overall execution.
func NewCheckPoint ¶
func NewCheckPoint[W word.Word[W]](callStack []StackFrame, dataStack []W, memory []Memory[W]) CheckPoint[W]
NewCheckPoint constructs a checkpoint from a snapshot of the call stack, data stack and memories of an executing machine. The provided slices are retained by reference, so callers which intend to continue mutating the underlying storage (e.g. an interpreter's live stacks) should pass copies.
func (CheckPoint[W]) CallStack ¶
func (p CheckPoint[W]) CallStack() []StackFrame
CallStack returns the captured call stack of paused callers.
func (CheckPoint[W]) DataStack ¶
func (p CheckPoint[W]) DataStack() []W
DataStack returns the captured data stack holding the activation records (registers) of all active function calls.
func (CheckPoint[W]) MarshalBinary ¶
func (p CheckPoint[W]) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler, serialising this checkpoint into the checkpoint format (see above).
func (CheckPoint[W]) Memories ¶
func (p CheckPoint[W]) Memories() []Memory[W]
Memories returns the captured memory snapshots.
func (*CheckPoint[W]) UnmarshalBinary ¶
func (p *CheckPoint[W]) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler, reconstructing a checkpoint previously serialised by MarshalBinary.
type Memory ¶
type Memory[W any] struct { // contains filtered or unexported fields }
Memory captures a snapshot of the contents of a single (mutable) memory module. To support sparse memories, the contents are described as a sequence of pages, each covering a contiguous region; regions not covered by any page are implicitly zero.
func NewMemory ¶
NewMemory constructs a snapshot of a single memory module, identified by its module identifier, described by the given sequence of pages, and with the given access clock (zero for memories which do not track timestamps).
type Page ¶
type Page[W any] struct { // contains filtered or unexported fields }
Page represents a variable-length chunk of data within a given memory.
func NewPage ¶
NewPage constructs a single page of memory beginning at the given physical address and holding the given data (with no per-cell timestamps).
func NewTimestampedPage ¶
NewTimestampedPage constructs a page carrying a per-cell timestamp alongside each data word; len(timestamps) must equal len(data).
func (Page[W]) Clone ¶
Clone returns a deep copy of this page, with its own copy of the underlying data. This is useful when the page references storage (e.g. live memory) which may subsequently be mutated.
func (Page[W]) Data ¶
func (p Page[W]) Data() []W
Data returns the words stored in this page, beginning at Address.
func (Page[W]) Timestamps ¶
Timestamps returns the per-cell timestamps parallel to Data, or nil if this page carries no timestamps.
type StackFrame ¶
type StackFrame struct {
// module identifier of the executing function.
FunctionId uint16
// frame pointer of the executing function.
FramePointer uint32
// program counter identifies next bytecode to execute.
ProgramCounter uint32
}
StackFrame captures relevant information about all functions currently executing a CALL. Such functions are "paused" whilst the active function is being executed. The purpose of a stack frame is to record the Frame Pointer (FP) and Program Counter (PC) of the relevant function so that these can be restored when it becomes the active function.
func NewStackFrame ¶
func NewStackFrame(fid uint16, fp uint32, pc uint32) StackFrame
NewStackFrame constructs a stack frame recording the function identifier, frame pointer and program counter of a paused function.
Source Files