Runtime class

A Runtime is a virtual machine instance that executes EVC bytecode.

It can be created from a Program or from EVC bytecode, using the Runtime.ofProgram constructor or the Runtime constructor respectively. When possible, the Runtime.ofProgram constructor should be preferred as it avoids overhead of loading bytecode.

After creating a Runtime, register bridge functions using registerBridgeFunc or addPlugin.

Once setup is complete, call executeLib to execute a function in the program.

By default, a Runtime has no permissions to access resources like the file system or network. Permissions can be granted using grant and revoked using revoke. Clients of the permission system such as bridge classes should check permissions using checkPermission or assertPermission.

Constructors

Runtime.new(ByteData _evc): Construct a runtime from EVC bytecode. When possible, use the Runtime.ofProgram constructor instead to reduce loading time.
Runtime.ofProgram(Program program): Create a Runtime from a Program. This constructor should be preferred where possible as it avoids overhead of loading bytecode.

Properties

args ↔ List<Object?>: Arguments to the current function.
getter/setter pair
bridgeEnumMappings ↔ Map<int, Map<String, Map<String, int>>>: latefinal
bridgeFuncMappings ↔ Map<int, Map<String, int>>: latefinal
callStack → List<int>: The program's call stack. If a function returns it will pop the last element from this stack and set _prOffset to the popped value.
final
catchControlFlowOutcome ↔ int: 0 = throw, 1 = return, 2 = break, 3 = continue
getter/setter pair
catchStack → List<List<int>>: The program's catch stack. If a function throws it will pop the last element from this stack and set _prOffset to the popped value.
final
constantPool → List<Object>: final
declarations ↔ Map<int, Map<String, int>>: getter/setter pair
declaredClasses → Map<int, Map<String, EvalClass>>: final
frame ↔ List<Object?>: The current frame (usually stack.last)
getter/setter pair
frameOffset ↔ int: Offset in the current stack frame
getter/setter pair
frameOffsetStack → List<int>: frameOffsets for each stack frame
final
globalInitializers ↔ List<int>: getter/setter pair
globals → List<Object?>: final
hashCode → int: The hash code for this object.
no setteroverride
id → int: final
inCatch ↔ bool: getter/setter pair
overrideMap ↔ Map<String, OverrideSpec>: getter/setter pair
pr → List<EvcOp>: The decoded program bytecode
final
rethrowException ↔ Object?: The exception to be rethrown
getter/setter pair
returnFromCatch ↔ Object?: Last return value from a catch block
getter/setter pair
returnValue ↔ Object?: The most recent return value
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
runtimeTypes ↔ List<RuntimeTypeSet>: latefinal
scopeNameStack → List<String>: Scope name stack
final
stack → List<List<Object?>>: The program's value stack
final
typeIds ↔ Map<int, Map<String, int>>: latefinal
typeTypes ↔ List<Set<int>>: latefinal

Methods

$throw(dynamic exception) → void: Throw an exception from the VM. This will unwind the stack until a catch block is found.
addPlugin(EvalPlugin plugin) → void: Add a plugin to the runtime, which can register bridge functions.
addTypeAutowrapper(TypeAutowrapper wrapper) → void: Add a type autowrapper to the runtime. Type autowrappers are used to automatically wrap values of a certain type into a $Value. They should be used sparingly due to their high performance overhead.
assertPermission(String domain, [Object? data]) → void: Check if a permission is granted, otherwise throw an exception.
bridgeCall(int $offset) → void: Run the VM in a 'sub-state' of a parent invocation of the VM. Used for bridge calls. For performance reasons, avoid making excessive use of this pattern, despite its convenience
checkPermission(String domain, [Object? data]) → bool: Check if a permission is granted.
execute(int entrypoint) → dynamic: Start program execution at a specific bytecode offset. Users should use executeLib instead.
executeLib(String library, String name, [List? args]) → dynamic: Execute a function in the current runtime, from a passed library URI and function name, with optional args.
grant(Permission permission) → void: Grant a permission to the runtime.
loadGlobalOverrides() → void: Sets this runtime as the global runtime, and loads its overrides globally.
lookupType(BridgeTypeSpec spec) → int: Lookup a type ID from a BridgeTypeSpec
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
printOpcodes() → void: Print the program's bytecode in a readable format
registerBridgeEnumValues(String library, String name, Map<String, $Value> values) → void: Register bridged runtime enum values.
registerBridgeFunc(String library, String name, EvalCallableFunc fn, {bool isBridge = false}) → void: Register a bridged runtime top-level/static function or class constructor.
revoke(Permission permission) → void: Revoke a permission from the runtime.
setup() → void: No longer needed, runtime is automatically setup by executeLib
toString() → String: A string representation of this object.
inherited
valueToString($Value? value) → String
wrap(dynamic value, {bool recursive = false}) → $Value: Attempt to wrap a Dart value into a $Value, and throw if unsuccessful.
wrapAlways(dynamic value, {bool recursive = false}) → $Value: Attempt to wrap a Dart value into a $Value, falling back to wrapping in an $Object
wrapPrimitive(dynamic value) → $Value?: Attempt to wrap a Dart primitive value into a $Value. This is needed because Dart primitives cannot be implemented or extended, so creating a bimodal wrapper is impossible.
wrapRecursive(dynamic value) → $Value

Operators

operator ==(Object other) → bool: The equality operator.
override

Static Properties

bridgeData → Expando<BridgeData>: Stores the BridgeData for each bridge class in the program.
final

Static Methods

opcodeFrom(EvcOp op) → List<int>: Write an EvcOp bytecode to a list of bytes.

Constants

versionCode → const int: The current runtime version code