The VmSession Class

This session class is a stateful container for a static program, but also its variable memory, its string table, and its Runtime Statistics.

class VmSession

Holds the current instruction pointer, variable memory, and string table for programs.

This class holds a program definition and defines the size and content of an associated variable memory and string table. In addition to that, the current instruction pointer location for executing the associated program is held in this class. VirtualMachine class instances (specifically CpuVirtualMachine) use VmSession instances to access the next portion of an executed program, and to steer instruction pointer movement. Also, the VirtualMachine classes access the VmSession’s variable memory and string table contents when executing a Program instance’s code.

Author
Jan Winkler
Date
2022-12-19

Public Types

enum VariableIoBehavior

Describes the intended I/O behavior of a variable.

A variable can either be used only for in-memory storage, or for input/output operations. In each case, a variable needs to be declared by a program. A program itself cannot change a variable’s behavior, but can query which behavior is intended and whether the variable was changed since the last interaction. The behavior needs to be set from outside the program. An input variable that is set from outside of the program allows a program to perform actions based on whether new input is available. An output variable can be set from inside the program, and outside of the program an executing entity can check whether new output is available.

Per default, all variables are defined as store only. All variable behaviors allow storing data independent from their intended I/O behavior.

Values:

Store = 0

Variable is used for in-memory storage only, no I/O behavior is expected.

Input = 1

Variable is expected to receive input from outside.

Output = 2

Variable is expected to be read from outside.

Public Functions

VmSession(Program program, size_t variable_count, size_t string_table_count, size_t max_string_size)

Standard constructor.

Requires a Program instance, and the definition of variable memory and string table size. The variable_count parameter represents the number of allowed variables (indexed starting at 0, consecutively). The string_table_count and max_string_size parameters represent the number of string table items possible, and the maximum length per string table item, respectively.

Parameters
  • program: The Program instance to associate to this VmSession instance
  • variable_count: The maximum number of variables
  • string_table_count: The maximum number of string table items
  • max_string_size: The maximum length per string table item

informAboutStep(OpCode operator_code)

Informs the session which operator is being executed in this step.

The overall number of steps, but also per operator type are recorded in the runtime statistics.

Parameters
  • operator_code: The OpCode value of the operator being executed

resetRuntimeStatistics()

Resets the runtime statistics.

reset()

Resets the entire VmSession object.

This function resets the internal state of this session instance, retaining its configuration parameters and associated program data.

getRuntimeStatistics() const

Returns a reference to the runtime statistics.

Return
A constant reference to the runtime statistics object

setVariableBehavior(int32_t variable_index, VariableIoBehavior behavior)

Sets the I/O behavior for a variable.

A variable can have three I/O behaviors: Store only, store and input, or store and output (see VariableIoBehavior for more details). For store only variables, no specific behavior is expected. Input variables can be checked by a program via the checkIfInputWasSet operator. If from outside of the program an input variable was set via setVariableValue, this operator will yield a positive response (independent from the value that was set). For output variables, it works the other way around: When programs set such a variable, functions outside of the program can retrieve this status by using the hasOutputDataAvailable call (and retrieve the data via getVariableValue). All variables declared through setVariableBehavior can be used like any other variable by all operators.

When calling this method on a variable, this variable_index is registered in the VmSession instance’s variable memory. This means that it can’t (and doesn’t have to) be declared again by a Program instance and can be used as if it was declared already. It can be undeclared like any other previously declared variable.

See
getVariableBehavior()
Parameters
  • variable_index: The variable to set the behavior for
  • behavior: The I/O behavior to set for the variable

getVariableBehavior(int32_t variable_index, bool follow_links)

Returns the I/O behavior currently set for a variable.

Returns which variable behavior is currently defined for the variable at index variable_index (potentially resolving its links of follow_links is set). For details on the exact I/O behaviors, see setVariableBehavior.

See
setVariableBehavior()
Parameters
  • variable_index: The variable to return the I/O behavior for
  • follow_links: Whether to resolve the variable’s links

hasOutputDataAvailable(int32_t variable_index, bool follow_links)

Checks if an output variable has new data available.

If, since the last read attempt, data was written to the passed in variable index, true is returned, and false otherwise.

Return
Returns true if data was written to the variable, false otherwise
Parameters
  • variable_index: The variable index to check for new output
  • follow_links: Whether to resolve the variable’s links

setMaximumPrintBufferLength(size_t maximum_print_buffer_length)

Sets the maximum length in characters that the print buffer can hold.

If the print buffer reaches a length of more than this value, an exception is thrown. This can be prevented by regularly calling clearPrintBuffer.

getData4()

Return the next 4 bytes of program byte code.

Return
The next 4 bytes of program byte code

getData2()

Return the next 2 bytes of program byte code.

Return
The next 2 bytes of program byte code

getData1()

Return the next 1 byte of program byte code.

Return
The next 1 byte of program byte code

getVariableValue(int32_t variable_index, bool follow_links)

Returns the stored value of a variable.

The value returned is read from the variable at variable_index, resolving its links if follow_links is set.

See
setVariableValue()
Parameters
  • variable_index: The variable to return the stored value for
  • follow_links: Whether to resolve the variable’s links

setVariableValue(int32_t variable_index, bool follow_links, int32_t value)

Sets the value stored in a variable.

The new value value will be stored in the variable at the index variable_index, resolving its links if follow_links is set.

Parameters
  • variable_index: The variable to store value in
  • follow_links: Whether to resolve the variable’s links
  • value: The value to store in the variable

isAtEnd() const

Checks whether the associated program is at the end of its executable code.

Effectively, this function returns whether the instruction pointer points beyond the end of the code.

Return
Boolean flag denoting whether the program execution is at its end

setExitedAbnormally()

Marks the program as exited abnormally.

registerVariable(int32_t variable_index, Program::VariableType variable_type)

Registers a variable at index and type in the variable memory.

See Program::declareVariable for the intended operator use.

See
unregisterVariable()
Parameters
  • variable_index: The index to declare the variable at.
  • variable_type: The designated type of the variable.

getRealVariableIndex(int32_t variable_index, bool follow_links)

Resolves a variable index based on linkage.

The first variable index that is not a link is returned. This method detects circular linkage, and throws if either this is detected or if any variable index points outside of the valid variable memory.

Parameters
  • variable_index: The index of the start variable.
  • follow_links: Whether to resolve variable links.

setVariable(int32_t variable_index, int32_t value, bool follow_links)

Sets the value of a variable.

Sets the value of a variable at the given index to the value content. The variable index needs to be declared prior to this.

See Program::setVariable for the intended operator use.

Parameters
  • variable_index: The index of the variable.
  • value: The value to assign to the variable.
  • follow_links: Whether to resolve variable links.

unregisterVariable(int32_t variable_index)

Removes a registered variable from the internal variable memory.

See Program::undeclareVariable for the intended operator use.

See
registerVariable()
Parameters
  • variable_index: The index of the variable to undeclare.

setStringTableEntry(int32_t string_table_index, std::string_view string_content)

Sets the content of a string table entry.

See Program::setStringTableEntry for the intended operator use.

Parameters
  • string_table_index: The string table index to set.
  • string: The content to store in the string table.

getStringTableEntry(int32_t string_table_index) const

Returns the string value stored at the given index in the string table.

Return
The string read from the string table at the specified index
Parameters
  • string_table_index: The string table index to read the string from

appendToPrintBuffer(std::string_view string)

Appends a string to the current print buffer.

The print buffer is a store for all characters that should be printed to screen. This method appends a given string to the already existing content.

See
appendVariableToPrintBuffer(), getPrintBuffer(), clearPrintBuffer()
Parameters
  • string: The string to append to the print buffer.

appendVariableToPrintBuffer(int32_t variable_index, bool follow_links, bool as_char)

Appends the value of a variable to the print buffer.

The value can be added to the print buffer either via its numeric value or as the character value of the least significant byte of the variable’s value.

See
appendToPrintBuffer(), getPrintBuffer(), clearPrintBuffer()
Parameters
  • variable_index: The variable to read the value from
  • follow_links: Whether to resolve variable links
  • as_char: Whether to append the LSB char value to the buffer (true) or the numeric value of the entire int32_t (false)

getPrintBuffer() const

Returns a reference to the print buffer.

See
appendToPrintBuffer(), appendVariableToPrintBuffer(), clearPrintBuffer()

clearPrintBuffer()

Cleas the print buffer.

See
appendToPrintBuffer(), appendVariableToPrintBuffer(), getPrintBuffer()

terminate(int8_t return_code)

Marks the program as terminates and sets its return code.

To prevent further execution, this call marks the program as terminated internally. The passed in return code is stored.

See
terminateWithVariableReturnCode()
Parameters
  • return_code: The return code to store for the program

addConstantToVariable(int32_t variable_index, int32_t constant, bool follow_links)

Adds a constant to a variable’s value.

See Program::addConstantToVariable for the intended operator use.

Parameters
  • variable_index: The variable to add the constant to
  • constant: The constant to add to the variable
  • follow_links: Wehether to resolve the variable’s links

addVariableToVariable(int32_t source_variable, int32_t destination_variable, bool follow_source_links, bool follow_destination_links)

Add the value of one variable to another variable.

See Program::addVariableToVariable for the intended operator use.

Parameters
  • source_variable: The variable to add to the other variable
  • destination_variable: The variable to add the value to
  • follow_source_links: Whether to resolve the source variable’s links
  • follow_destination_links: Whether to resolve the destination variable’s links

subtractConstantFromVariable(int32_t variable_index, int32_t constant, bool follow_links)

Subtract a constant from a variable.

See Program::subtractConstantFromVariable for the intended operator use.

Parameters
  • variable_index: The variable to subtract the constant from
  • constant: The constant to subtract from the variable
  • follow_links: Wehether to resolve the variable’s links

subtractVariableFromVariable(int32_t source_variable, int32_t destination_variable, bool follow_source_links, bool follow_destination_links)

Subtract a variable from a variable.

See Program::subtractVariableFromVariable for the intended operator use.

Parameters
  • source_variable: The variable to subtract from the other variable
  • destination_variable: The variable to subtract the value from
  • follow_source_links: Whether to resolve the source variable’s links
  • follow_destination_links: Whether to resolve the destination variable’s links

relativeJumpToVariableAddressIfVariableGt0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::relativeJumpToVariableAddressIfVariableGt0 for the intended operator use.

Perform a relative jump to a variable address if a condition variable is > 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

relativeJumpToVariableAddressIfVariableLt0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::relativeJumpToVariableAddressIfVariableLt0 for the intended operator use.

Perform a relative jump to a variable address if a condition variable is < 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

relativeJumpToVariableAddressIfVariableEq0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::relativeJumpToVariableAddressIfVariableEq0 for the intended operator use.

Perform a relative jump to a variable address if a condition variable is = 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

absoluteJumpToVariableAddressIfVariableGt0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToVariableAddressIfVariableGt0 for the intended operator use.

Perform an absolute jump to a variable address if a condition variable is > 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

absoluteJumpToVariableAddressIfVariableLt0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToVariableAddressIfVariableLt0 for the intended operator use.

Perform an absolute jump to a variable address if a condition variable is < 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

absoluteJumpToVariableAddressIfVariableEq0(int32_t condition_variable, bool follow_condition_links, int32_t addr_variable, bool follow_addr_links)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToVariableAddressIfVariableEq0 for the intended operator use.

Perform an absolute jump to a variable address if a condition variable is = 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr_variable: The variable holding the target address
  • follow_addr_links: Whether to resolve the target address variable’s links

relativeJumpToAddressIfVariableGt0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::relativeJumpToAddressIfVariableGt0 for the intended operator use.

Perform a relative jump to a fixed address if a condition variable is > 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

relativeJumpToAddressIfVariableLt0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::relativeJumpToAddressIfVariableLt0 for the intended operator use.

Perform a relative jump to a fixed address if a condition variable is < 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

relativeJumpToAddressIfVariableEq0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::relativeJumpToAddressIfVariableEq0 for the intended operator use.

Perform a relative jump to a fixed address if a condition variable is = 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

absoluteJumpToAddressIfVariableGt0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToAddressIfVariableGt0 for the intended operator use.

Perform an absolute jump to a fixed address if a condition variable is > 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

absoluteJumpToAddressIfVariableLt0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToAddressIfVariableLt0 for the intended operator use.

Perform an absolute jump to a fixed address if a condition variable is < 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

absoluteJumpToAddressIfVariableEq0(int32_t condition_variable, bool follow_condition_links, int32_t addr)

NEEDS DOCUMENTATION.

See Program::absoluteJumpToAddressIfVariableEq0 for the intended operator use.

Perform an absolute jump to a fixed address if a condition variable is = 0.

Parameters
  • condition_variable: The variable holding the value to compare
  • follow_condition_links: Whether to resolve the comparison variable’s links
  • addr: The target address

loadMemorySizeIntoVariable(int32_t variable, bool follow_links)

Loads the maximum number of variables into a variable.

See Program::loadMemorySizeIntoVariable for the intended operator use.

Parameters
  • variable: The variable to store the result in
  • follow_links: Whether to resolve the variable’s links

checkIfVariableIsInput(int32_t source_variable, bool follow_source_links, int32_t destination_variable, bool follow_destination_links)

Checks if a variable is registered as input, stores the result.

See Program::checkIfVariableIsInput for the intended operator use.

Checks whether the variable source_variable is registered as an input. If yes, stores 0x1 in destination_variable, and 0x0 otherwise.

Parameters
  • source_variable: The variable to check for being an input
  • follow_source_links: Whether to resolve the source variable’s links
  • destination_variable: The variable to store the result in
  • follow_destination_links: Whether to resolve the destination variable’s links

checkIfVariableIsOutput(int32_t source_variable, bool follow_source_links, int32_t destination_variable, bool follow_destination_links)

Checks if a variable is registered as output, stores the result.

See Program::checkIfVariableIsOutput for the intended operator use.

Checks whether the variable source_variable is registered as an output. If yes, stores 0x1 in destination_variable, and 0x0 otherwise.

Parameters
  • source_variable: The variable to check for being an output
  • follow_source_links: Whether to resolve the source variable’s links
  • destination_variable: The variable to store the result in
  • follow_destination_links: Whether to resolve the destination variable’s links

copyVariable(int32_t source_variable, bool follow_source_links, int32_t destination_variable, bool follow_destination_links)

Copies the value of one variable into another.

See Program::copyVariable for the intended operator use.

Parameters
  • source_variable: The variable to copy the value from
  • follow_source_links: Whether to resolve the source variable’s links
  • destination_variable: The variable to store the result in
  • follow_destination_links: Whether to resolve the destination variable’s links

loadInputCountIntoVariable(int32_t variable, bool follow_links)

Loads the number of declared input variables into a variable.

See Program::loadInputCountIntoVariable for the intended operator use.

Parameters
  • variable: The index of the target variable
  • follow_links: Whether to resolve the variable’s links

loadOutputCountIntoVariable(int32_t variable, bool follow_links)

Loads the number of declared output variables into a variable.

See Program::loadOutputCountIntoVariable for the intended operator use.

Parameters
  • variable: The index of the target variable
  • follow_links: Whether to resolve the variable’s links

loadCurrentAddressIntoVariable(int32_t variable, bool follow_links)

Loads the current execution pointer address into a variable.

See Program::loadCurrentAddressIntoVariable for the intended operator use.

Parameters
  • variable: The index of the target variable
  • follow_links: Whether to resolve the variable’s links

checkIfInputWasSet(int32_t variable_index, bool follow_links, int32_t destination_variable, bool follow_destination_links)

Checks if an input variable has received data.

See Program::checkIfInputWasSet for the intended operator use.

If the target variable is not declared as an input variable this call will throw an exception.

Parameters
  • variable_index: The index of the input variable to check
  • follow_links: Whether to resolve the variable’s links

loadStringTableLimitIntoVariable(int32_t variable_index, bool follow_links)

Loads the maximum number of indices in the string table into a variable.

See Program::loadStringTableLimitIntoVariable for the intended operator use.

Parameters
  • variable_index: The index of the variable
  • follow_links: Whether to resolve the variable’s links

loadStringTableItemLengthLimitIntoVariable(int32_t variable_index, bool follow_links)

Loads the maximum number of characters per string table item into a variable.

See Program::loadStringTableItemLengthLimitIntoVariable for the intended operator use.

Parameters
  • variable_index: The index of the variable
  • follow_links: Whether to resolve the variable’s links

loadRandomValueIntoVariable(int32_t variable_index, bool follow_links)

Loads a random number in the range of int32_t into a variable.

See Program::loadRandomValueIntoVariable for the intended operator use.

Parameters
  • variable_index: The index of the variable
  • follow_links: Whether to resolve the variable’s links

unconditionalJumpToAbsoluteAddress(int32_t addr)

Performs an unconditional jump to an absolute address.

See Program::unconditionalJumpToAbsoluteAddress for the intended operator use.

Parameters
  • addr: The absolute address to jump to

unconditionalJumpToAbsoluteVariableAddress(int32_t variable_index, bool follow_links)

Performs an unconditional jump to an absolute address read from a variable.

See Program::unconditionalJumpToAbsoluteVariableAddress for the intended operator use.

Parameters
  • variable_index: The variable containing the absolute address to jump to
  • follow_links: Whether to resolve variable links

unconditionalJumpToRelativeAddress(int32_t addr)

Performs an unconditional jump to a relative address.

See Program::unconditionalJumpToRelativeAddress for the intended operator use.

Parameters
  • addr: The absolute address to jump to

unconditionalJumpToRelativeVariableAddress(int32_t variable_index, bool follow_links)

Performs an unconditional jump to a relative address read from a variable.

See Program::unconditionalJumpToRelativeVariableAddress for the intended operator use.

Parameters
  • variable_index: The variable containing the relative address to jump to
  • follow_links: Whether to resolve variable links

loadStringItemLengthIntoVariable(int32_t string_table_index, int32_t variable_index, bool follow_links)

Loads the length of a specific string table item into a variable.

See Program::loadStringItemLengthIntoVariable for the intended operator use.

Parameters
  • string_table_index: The string table index to read the length from
  • variable_index: The variable the length should be stored in
  • follow_links: Whether to resolve variable links

loadStringItemIntoVariables(int32_t string_table_index, int32_t start_variable_index, bool follow_links)

Loads a string table item’s content into a number of consecutive variables.

See Program::loadStringItemIntoVariables for the intended operator use.

The string item read from the string table will be iterated character by character. Each character goes into a variable at the respective relative index, starting from the specified start variable index. The variables will then contain the respective characters in their least significant byte.

Example:

  • String table item = “Entry”
  • start_variable_index + 0 = “E”
  • start_variable_index + 1 = “n”
  • start_variable_index + 2 = “t”
  • start_variable_index + 3 = “r”
  • start_variable_index + 4 = “y”

Variable links will be resolved per variable if follow_links is true.

See
loadVariableStringItemIntoVariables()
Parameters
  • string_table_index: The string table index to read the characters from
  • start_variable_index: The variable where the first character is stored
  • follow_links: Whether to resolve variable links

performSystemCall(int8_t major_code, int8_t minor_code, int32_t variable_index, bool follow_links)

Performs actions interacting with the external system.

System calls are everything categorized as interacting with the external system, i.e. not inside the running program but on VM host level. These functions are rather limited at the moment and don’t allow access to sensitive information outside, nor are they allowed to alter any states outside of the program. In their current state, system calls are limited to acquiring environment information such as details about the current date and time. The major and minor code identify the concrete action that will take place, and the result of that selected action will be stored in the variable referenced during the call.

Here is a list of currently implemented system calls (major code, minor code, description):

  • 0, 0: Get UTC timezone (hours)
  • 0, 1: Get UTC timezone (minutes)
  • 0, 2: Get current UTC time (seconds part)
  • 0, 3: Get current UTC time (minutes part)
  • 0, 4: Get current UTC time (hours part)
  • 0, 5: Get current UTC date (day part)
  • 0, 6: Get current UTC date (month part)
  • 0, 7: Get current UTC date (year part)
  • 0, 8: Get current UTC date (week part)
  • 0, 9: Get current UTC date (day of week part)

Parameters
  • major_code: The major code for the system call (see table)
  • minor_code: The minor code for the system call (see table)
  • variable_index: The variable to store the call’s result in
  • follow_links: Whether to resolve the variable’s links

bitShiftVariable(int32_t variable_index, bool follow_links, int8_t places)

Bit-shift a variable by a given number of places.

See Program::bitShiftVariable for the intended operator use.

Positive amounts of places shift to the left, negative amounts shift to the right.

Parameters
  • variable_index: The variable to bit-shift
  • follow_links: Whether to resolve variable links
  • places: The amount of places to shift by

bitWiseInvertVariable(int32_t variable_index, bool follow_links)

Bit-wise invert a variable.

See Program::bitWiseInvertVariable for the intended operator use.

Parameters
  • variable_index: The variable to invert
  • follow_links: Whether to resolve variable links

bitWiseAndTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Perform a bit-wise AND operation on two variables.

See Program::bitWiseAndTwoVariables for the intended operator use.

The result will be stored in variable_index_b: b = a & b

Parameters
  • variable_index: The first variable
  • follow_links: Whether to resolve the first variable’s links
  • variable_index: The second variable (also the target)
  • follow_links: Whether to resolve the second variable’s links

bitWiseOrTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Perform a bit-wise OR operation on two variables.

See Program::bitWiseOrTwoVariables for the intended operator use.

The result will be stored in variable_index_b: b = a | b

Parameters
  • variable_index: The first variable
  • follow_links: Whether to resolve the first variable’s links
  • variable_index: The second variable (also the target)
  • follow_links: Whether to resolve the second variable’s links

bitWiseXorTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Perform a bit-wise XOR operation on two variables.

See Program::bitWiseXorTwoVariables for the intended operator use.

The result will be stored in variable_index_b: b = a ^ b

Parameters
  • variable_index: The first variable
  • follow_links: Whether to resolve the first variable’s links
  • variable_index: The second variable (also the target)
  • follow_links: Whether to resolve the second variable’s links

moduloVariableByConstant(int32_t variable_index, bool follow_links, int32_t constant)

Performs a modulo operation on the variable, using the specified constant.

See Program::moduloVariableByConstant for the intended operator use.

The result will be stored in the same variable. variable = variable % constant

Parameters
  • variable_index: The variable to modulo
  • follow_links: Whether to resolve variable links
  • constant: The constant to modulo the variable’s value by

moduloVariableByVariable(int32_t variable_index, bool follow_links, int32_t modulo_variable_index, bool modulo_follow_links)

Performs a modulo operation on a variable, using a modulo value from a second variable.

See Program::moduloVariableByVariable for the intended operator use.

The result will be stored in the first variable. variable = variable % modulo_variable

Parameters
  • variable_index: The variable to modulo
  • follow_links: Whether to resolve the variable’s links
  • modulo_variable_index: The variable to use as modulo value
  • modulo_follow_links: Whether to resolve the modulo variable’s links

rotateVariable(int32_t variable_index, bool follow_links, int8_t places)

Bit-wise rotates a variable by a number of places.

See Program::rotateVariable for the intended operator use.

Positive values of places rotate to the left, negative values rotate to the right.

Parameters
  • variable_index: The variable to rotate
  • follow_links: Whether to resolve the variable’s links
  • places: The amount of places by which to rotate the variable

pushVariableOnStack(int32_t stack_variable_index, bool stack_follow_links, int32_t variable_index, bool follow_links)

Pushes the value of a variable onto a stack.

See Program::pushVariableOnStack for the intended operator use.

Parameters
  • stack_variable_index: The stack variable index
  • stack_follow_links: Whether to resolve the stack variable’s links
  • variable_index: The variable whose value to push onto the stack
  • follow_links: Whether to resolve the value variable’s links

pushConstantOnStack(int32_t stack_variable_index, bool stack_follow_links, int32_t constant)

Pushes a constant value onto a stack.

See Program::pushConstantOnStack for the intended operator use.

Parameters
  • stack_variable_index: The stack variable index
  • stack_follow_links: Whether to resolve the stack variable’s links
  • constant: The constant value to push onto the stack

popVariableFromStack(int32_t stack_variable_index, bool stack_follow_links, int32_t variable_index, bool follow_links)

Pops the top item from a stack and stores its value in a variable.

See Program::popVariableFromStack for the intended operator use.

Parameters
  • stack_variable_index: The stack variable index
  • stack_follow_links: Whether to resolve the stack variable’s links
  • variable_index: The variable in which to store the top stack item
  • follow_links: Whether to resolve the target variable’s links

popTopItemFromStack(int32_t stack_variable_index, bool stack_follow_links)

Removes the top item from a stack and discards it.

See Program::popTopItemFromStack for the intended operator use.

Parameters
  • stack_variable_index: The stack variable index
  • stack_follow_links: Whether to resolve the stack variable’s links

checkIfStackIsEmpty(int32_t stack_variable_index, bool stack_follow_links, int32_t variable_index, bool follow_links)

Determines whether a stack is empty, stores the result.

See Program::checkIfStackIsEmpty for the intended operator use.

If the stack at stack_variable_index is empty, the value 0x1 is stored in the target variable. Otherwise, 0x0 is stored.

Parameters
  • stack_variable_index: The stack variable index
  • stack_follow_links: Whether to resolve the stack variable’s links
  • variable_index: The variable in which to store the top stack item
  • follow_links: Whether to resolve the target variable’s links

swapVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Swaps the content of two variables.

See Program::swapVariables for the intended operator use.

Parameters
  • variable_index_a: The first variable to swap
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to swap
  • follow_links_b: Whether to resolve the second variable’s links

setVariableStringTableEntry(int32_t variable_index, bool follow_links, std::string_view string_content)

Sets the content of a string table item at a variable index.

See Program::setVariableStringTableEntry for the intended operator use.

The index at which the target string is stored in the string table is defined by the variable variable_index.

Parameters
  • variable_index: The variable containing the string table index
  • follow_links: Whether to resolve the variable’s links
  • string_content: The string to store in the string table

printVariableStringFromStringTable(int32_t variable_index, bool follow_links)

Prints a string from the string table based on a variable index.

See Program::printVariableStringFromStringTable for the intended operator use.

The string value stored in the string table at the defined index string_table_index is appended to the print buffer.

Parameters
  • variable_index: The variable index to use as string table index
  • follow_links: Whether to resolve the variable’s links

loadVariableStringItemLengthIntoVariable(int32_t string_item_variable_index, bool string_item_follow_links, int32_t variable_index, bool follow_links)

Loads the length of a variable string table item into a variable.

See Program::loadVariableStringItemLengthIntoVariable for the intended operator use.

Retrieves the length of a stored string table item and stored it in the target variable variable_index. The string table item index used is retrieved from string_item_variable_index.

See
loadStringItemLengthIntoVariable()
Parameters
  • string_item_variable_index: The variable holding the string table item index
  • string_item_follow_links: Whether to resolve the string item variable’s links
  • variable_index: The variable to store the length in
  • follow_links: Whether to resolve the target variable’s links

loadVariableStringItemIntoVariables(int32_t string_item_variable_index, bool string_item_follow_links, int32_t start_variable_index, bool follow_links)

Loads a variable string table item’s content into a number of consecutive variables.

See Program::loadVariableStringItemIntoVariables for the intended operator use.

This call is similar to loadStringItemIntoVariables with the difference that the string table index is not passed as a fixed value, but is read from the variable index string_item_variable_index.

See
loadStringItemIntoVariables()
Parameters
  • string_item_variable_index: The variable holding the string table item index
  • string_item_follow_links: Whether to resolve the string table index variable’s links
  • start_variable_index: The variable where the first character is stored
  • follow_links: Whether to resolve the start variable’s links

terminateWithVariableReturnCode(int32_t variable_index, bool follow_links)

Marks the program as terminates and sets a variable return code.

See Program::terminateWithVariableReturnCode for the intended operator use.

This call is very similar to the terminate call. Instead of setting the return value to a fixed value though, it reads the return code from the variable index variable_index.

See
terminate()
Parameters
  • variable_index: The variable to read the return code from
  • follow_links: Whether to resolve the variable’s links

variableBitShiftVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool places_follow_links)

Bit-shift a variable by a variable number of places to the left.

See Program::variableBitShiftVariableLeft for the intended operator use.

See
bitShiftVariableLeft()
Parameters
  • variable_index: The variable to bit-shift to the left
  • follow_links: Whether to resolve variable links
  • places_variable_index: The variable holding the places to shift by
  • places_follow_links: Whether to resolve the places variable’s links

variableBitShiftVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool places_follow_links)

Bit-shift a variable by a variable number of places to the right.

See Program::variableBitShiftVariableRight for the intended operator use.

See
bitShiftVariableRight()
Parameters
  • variable_index: The variable to bit-shift to the right
  • follow_links: Whether to resolve variable links
  • places_variable_index: The variable holding the places to shift by
  • places_follow_links: Whether to resolve the places variable’s links

variableRotateVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool places_follow_links)

Rotates a variable to the left by a variable amount of places.

See Program::variableRotateVariableLeft for the intended operator use.

See
rotateVariableLeft(), rotateVariableRight(), variableRotateVariableRight()
Parameters
  • variable_index: The variable to rotate to the left
  • follow_links: Whether to resolve the rotated variable’s links
  • places_variable_index: The variable holding the amount of places to rotate
  • places_follow_links: Whether to resolve the places variable’s links

variableRotateVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool places_follow_links)

Rotates a variable to the right by a variable amount of places.

See Program::variableRotateVariableRight for the intended operator use.

See
rotateVariableLeft(), rotateVariableRight(), variableRotateVariableLeft()
Parameters
  • variable_index: The variable to rotate to the right
  • follow_links: Whether to resolve the rotated variable’s links
  • places_variable_index: The variable holding the amount of places to rotate
  • places_follow_links: Whether to resolve the places variable’s links

compareIfVariableGtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Checks if a variable is larger than a constant, stores the result.

See Program::compareIfVariableGtConstant for the intended operator use.

If the variable larger than the constant, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index: The variable to compare
  • follow_links: Whether to resolve the variable’s links
  • constant: The constant to compare to
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

compareIfVariableLtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Checks if a variable is smaller than a constant, stores the result.

See Program::compareIfVariableLtConstant for the intended operator use.

If the variable smaller than the constant, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index: The variable to compare
  • follow_links: Whether to resolve the variable’s links
  • constant: The constant to compare to
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

compareIfVariableEqConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Checks if a variable has the same value as a constant, stores the result.

See Program::compareIfVariableEqConstant for the intended operator use.

If the variable has the same value as the constant, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index: The variable to compare
  • follow_links: Whether to resolve the variable’s links
  • constant: The constant to compare to
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

compareIfVariableGtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

ecks if one variable is larger than another, stores the result

See Program::compareIfVariableGtVariable for the intended operator use.

If the first variable is larger than the second, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index_a: The first variable to compare
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to compare
  • follow_links_b: Whether to resolve the second variable’s links
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

compareIfVariableLtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Checks if one variable is smaller than another, stores the result.

See Program::compareIfVariableLtVariable for the intended operator use.

If the first variable is smaller than the second, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index_a: The first variable to compare
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to compare
  • follow_links_b: Whether to resolve the second variable’s links
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

compareIfVariableEqVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Checks if two variables have the same value, stores the result.

See Program::compareIfVariableEqVariable for the intended operator use.

If the two variable values are equal, store 0x1 in the target variable. Store 0x0 otherwise.

Parameters
  • variable_index_a: The first variable to compare
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to compare
  • follow_links_b: Whether to resolve the second variable’s links
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

getMaxOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Chooses the larger of a variable and a constant value, stores the result.

See Program::getMaxOfVariableAndConstant for the intended operator use.

Parameters
  • variable_index: The variable to compare
  • follow_links: Whether to resolve the variable’s links
  • constant: The constant to compare
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

getMinOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Chooses the smaller of a variable and a constant value, stores the result.

See Program::getMinOfVariableAndConstant for the intended operator use.

Parameters
  • variable_index: The variable to compare
  • follow_links: Whether to resolve the variable’s links
  • constant: The constant to compare
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

getMaxOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Chooses the larger of two variable values, stores the result.

See Program::getMaxOfVariableAndVariable for the intended operator use.

Parameters
  • variable_index_a: The first variable to compare
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to compare
  • follow_links_b: Whether to resolve the second variable’s links
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

getMinOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Chooses the smaller of two variable values, stores the result.

See Program::getMinOfVariableAndVariable for the intended operator use.

Parameters
  • variable_index_a: The first variable to compare
  • follow_links_a: Whether to resolve the first variable’s links
  • variable_index_b: The second variable to compare
  • follow_links_b: Whether to resolve the second variable’s links
  • target_variable_index: The variable to store the result in
  • target_follow_links: Whether to resolve the target variable’s links

printVariable(int32_t variable_index, bool follow_links, bool as_char)

Prints the value of a variable.

See Program::printVariable for the intended operator use.

If as_char is false, this appends the numeric value stored at variable_index as string to the print buffer. If as_char is true, only the least significant byte of the variable’s value is appended as one character to the print buffer.

Parameters
  • variable_index: The variable to read the value from
  • follow_links: Whether to resolve the variable’s links
  • as_char: Whether to print the numeric or the char value

printStringFromStringTable(int32_t string_table_index)

Prints a string from the string table based on a fixed index.

See Program::printStringFromStringTable for the intended operator use.

The string value stored in the string table at the defined index string_table_index is appended to the print buffer.

Parameters
  • string_table_index: The string table index to read the string from

struct RuntimeStatistics

Contains statistical information and metadata about an executed program.

When a program is executed by a VirtualMachine instance, that VM is supposed to inform the session of any operators that were executed. The usage count for each operator is recorded in the session, alongside the overall number of steps executed, whether the program has terminated, whether the termination was abnormal (an exception throw), and what the program’s return code was.

See
getRuntimeStatistics(), informAboutStep(), resetRuntimeStatistics()

Public Members

uint32_t steps_executed

How many steps were executed.

bool terminated

Whether the program has terminated.

bool abnormal_exit

Whether the program execution was abnormal.

int8_t return_code

The program’s return code.

std::map<OpCode, uint32_t> operator_executions

How often which operator was executed.

std::set<uint32_t> executed_indices

Which operator indices were executed.

struct VariableDescriptor

Contains metadata about a declared variable.

For each declared variable, data about its type, intended behavior, and current behavioral state is stored. This struct describes these metadata elements.

Public Members

Program::VariableType type

The declared type of the variable.

VariableIoBehavior behavior

The intended behavior of the variable.

bool changed_since_last_interaction

Whether the value was changed since it was last written/read, based on the intended behavior