ArkScript
A small, fast, functional and scripting language for video games
Ark::VM Class Referencefinal

The ArkScript virtual machine, executing ArkScript bytecode. More...

#include <VM.hpp>

Collaboration diagram for Ark::VM:
[legend]

Public Member Functions

 VM (State &state) noexcept
 Construct a new vm t object.
 
int run (bool fail_with_exception=false)
 Run the bytecode held in the state.
 
Valueoperator[] (const std::string &name) noexcept
 Retrieve a value from the virtual machine, given its symbol name.
 
template<typename... Args>
Value call (const std::string &name, Args &&... args)
 Call a function from ArkScript, by giving it arguments.
 
Value resolve (internal::ExecutionContext *context, const std::vector< Value > &n)
 Resolves a function call (called by plugins and builtins)
 
void exit (int code) noexcept
 Ask the VM to exit with a given exit code.
 
internal::ExecutionContextgetDefaultContext ()
 Return a pointer to the first execution context, for the main thread of the app.
 
internal::ExecutionContextcreateAndGetContext ()
 Create an execution context and returns it.
 
void deleteContext (internal::ExecutionContext *ec)
 Free a given execution context.
 
internal::FuturecreateFuture (std::vector< Value > &args)
 Create a Future object from a function and its arguments and return a managed pointer to it.
 
void deleteFuture (internal::Future *f)
 Free a given future.
 
bool forceReloadPlugins () const
 Used by the REPL to force reload all the plugins and their bound methods.
 

Private Member Functions

int safeRun (internal::ExecutionContext &context, std::size_t untilFrameCount=0, bool fail_with_exception=false)
 Run ArkScript bytecode inside a try catch to retrieve all the exceptions and display a stack trace if needed.
 
void init () noexcept
 Initialize the VM according to the parameters.
 
ValueloadSymbol (uint16_t id, internal::ExecutionContext &context)
 Load a symbol by its id in the current context. Performs a lookup in the scope stack, in reverse order.
 
ValueloadSymbolFromIndex (uint16_t index, internal::ExecutionContext &context)
 Load a symbol by its (reversed) index in the current scope.
 
ValueloadConstAsPtr (uint16_t id) const
 Load a constant from the constant table by its id.
 
void store (uint16_t id, const Value *val, internal::ExecutionContext &context)
 Create a new symbol with an associated value in the current scope.
 
void setVal (uint16_t id, const Value *val, internal::ExecutionContext &context)
 Change the value of a symbol given its identifier.
 
Valuepop (internal::ExecutionContext &context)
 Pop a value from the stack.
 
void push (const Value &value, internal::ExecutionContext &context)
 Push a value on the stack.
 
void push (Value &&value, internal::ExecutionContext &context)
 Push a value on the stack.
 
void push (Value *valptr, internal::ExecutionContext &context)
 Push a value on the stack as a reference.
 
ValuepopAndResolveAsPtr (internal::ExecutionContext &context)
 Pop a value from the stack and resolve it if possible, then return it.
 
void swapStackForFunCall (uint16_t argc, internal::ExecutionContext &context)
 Move stack values around and invert them.
 
ValuefindNearestVariable (uint16_t id, internal::ExecutionContext &context) noexcept
 Find the nearest variable of a given id.
 
void returnFromFuncCall (internal::ExecutionContext &context)
 Destroy the current frame and get back to the previous one, resuming execution.
 
void loadPlugin (uint16_t id, internal::ExecutionContext &context)
 Load a plugin from a constant id.
 
uint16_t findNearestVariableIdWithValue (const Value &value, internal::ExecutionContext &context) const noexcept
 Find the nearest variable id with a given value.
 
void throwArityError (std::size_t passed_arg_count, std::size_t expected_arg_count, internal::ExecutionContext &context)
 
void showBacktraceWithException (const std::exception &e, internal::ExecutionContext &context)
 
std::optional< internal::InstLocfindSourceLocation (std::size_t ip, std::size_t pp)
 Find the nearest source location information given instruction and page pointers.
 
void backtrace (internal::ExecutionContext &context, std::ostream &os=std::cout, bool colorize=true)
 Display a backtrace when the VM encounter an exception.
 
void call (internal::ExecutionContext &context, uint16_t argc)
 Function called when the CALL instruction is met in the bytecode.
 
void callBuiltin (internal::ExecutionContext &context, const Value &builtin, uint16_t argc)
 Builtin called when the CALL_BUILTIN instruction is met in the bytecode.
 

Static Private Member Functions

static void throwVMError (internal::ErrorKind kind, const std::string &message)
 Throw a VM error message.
 

Private Attributes

Statem_state
 
std::vector< std::unique_ptr< internal::ExecutionContext > > m_execution_contexts
 
int m_exit_code
 VM exit code, defaults to 0. Can be changed through sys:exit
 
bool m_running
 
std::mutex m_mutex
 
std::vector< std::shared_ptr< internal::SharedLibrary > > m_shared_lib_objects
 
std::vector< std::unique_ptr< internal::Future > > m_futures
 Storing the promises while we are resolving them.
 
Value m_no_value = internal::Builtins::nil
 
Value m_undefined_value
 

Friends

class Value
 
class internal::Closure
 
class Repl
 

Detailed Description

The ArkScript virtual machine, executing ArkScript bytecode.

Definition at line 44 of file VM.hpp.

Constructor & Destructor Documentation

◆ VM()

Ark::VM::VM ( State & state)
explicitnoexcept

Construct a new vm t object.

Parameters
statea reference to an ArkScript state, which can be reused for multiple VMs

Definition at line 80 of file VM.cpp.

Member Function Documentation

◆ backtrace()

◆ call() [1/2]

template<typename... Args>
Value Ark::VM::call ( const std::string & name,
Args &&... args )

Call a function from ArkScript, by giving it arguments.

Template Parameters
Args
Parameters
namethe function name in the ArkScript code
argsC++ argument list, converted to internal representation
Returns
Value

Definition at line 6 of file VM.hpp.

Referenced by safeRun().

◆ call() [2/2]

void Ark::VM::call ( internal::ExecutionContext & context,
uint16_t argc )
inlineprivate

Function called when the CALL instruction is met in the bytecode.

Parameters
context
argcnumber of arguments already sent

Definition at line 263 of file VM.hpp.

◆ callBuiltin()

void Ark::VM::callBuiltin ( internal::ExecutionContext & context,
const Value & builtin,
uint16_t argc )
inlineprivate

Builtin called when the CALL_BUILTIN instruction is met in the bytecode.

Parameters
context
builtinthe builtin to call
argcnumber of arguments already sent

Definition at line 348 of file VM.hpp.

Referenced by safeRun().

◆ createAndGetContext()

ExecutionContext * Ark::VM::createAndGetContext ( )

Create an execution context and returns it.

This method is thread-safe VM wise.

Returns
internal::ExecutionContext*

Definition at line 228 of file VM.cpp.

References Ark::internal::ExecutionContext::locals, m_execution_contexts, m_mutex, Ark::internal::ExecutionContext::scopes_storage, and Ark::internal::ExecutionContext::stacked_closure_scopes.

Referenced by createFuture().

◆ createFuture()

Future * Ark::VM::createFuture ( std::vector< Value > & args)

Create a Future object from a function and its arguments and return a managed pointer to it.

This method is thread-safe VM wise.

Parameters
args
Returns
internal::Future*

Definition at line 263 of file VM.cpp.

References createAndGetContext(), Ark::internal::ExecutionContext::last_symbol, m_execution_contexts, m_futures, and m_mutex.

◆ deleteContext()

void Ark::VM::deleteContext ( internal::ExecutionContext * ec)

Free a given execution context.

This method is thread-safe VM wise.

Parameters
ec

Definition at line 249 of file VM.cpp.

References m_execution_contexts, and m_mutex.

◆ deleteFuture()

void Ark::VM::deleteFuture ( internal::Future * f)

Free a given future.

This method is thread-safe VM wise.

Parameters
f

Definition at line 278 of file VM.cpp.

References m_futures, and m_mutex.

◆ exit()

void Ark::VM::exit ( int code)
noexcept

Ask the VM to exit with a given exit code.

Parameters
codean exit code

Definition at line 222 of file VM.cpp.

◆ findNearestVariable()

Value * Ark::VM::findNearestVariable ( uint16_t id,
internal::ExecutionContext & context )
inlineprivatenoexcept

Find the nearest variable of a given id.

Parameters
idthe id to find
context
Returns
Value*

Definition at line 246 of file VM.hpp.

Referenced by safeRun().

◆ findNearestVariableIdWithValue()

uint16_t Ark::VM::findNearestVariableIdWithValue ( const Value & value,
internal::ExecutionContext & context ) const
privatenoexcept

Find the nearest variable id with a given value.

Only used to display the call stack traceback

Parameters
valuethe value to search for
context
Returns
uint16_t

Definition at line 1589 of file VM.cpp.

Referenced by backtrace().

◆ findSourceLocation()

std::optional< InstLoc > Ark::VM::findSourceLocation ( std::size_t ip,
std::size_t pp )
private

Find the nearest source location information given instruction and page pointers.

Parameters
ip
pp
Returns
std::optional<InstLoc>

Definition at line 1669 of file VM.cpp.

References Ark::State::m_inst_locations, and m_state.

Referenced by backtrace().

◆ forceReloadPlugins()

bool Ark::VM::forceReloadPlugins ( ) const
nodiscard

Used by the REPL to force reload all the plugins and their bound methods.

Returns
true on success
false if one or more plugins couldn't be reloaded

Definition at line 292 of file VM.cpp.

References m_execution_contexts, m_shared_lib_objects, m_state, Ark::State::m_symbols, and Ark::mapping::name.

Referenced by Ark::Repl::run().

◆ getDefaultContext()

internal::ExecutionContext * Ark::VM::getDefaultContext ( )
inline

Return a pointer to the first execution context, for the main thread of the app.

Returns
internal::ExecutionContext*

Definition at line 105 of file VM.hpp.

◆ init()

◆ loadConstAsPtr()

Value * Ark::VM::loadConstAsPtr ( uint16_t id) const
inlinenodiscardprivate

Load a constant from the constant table by its id.

Parameters
id
Returns
Value*

Definition at line 113 of file VM.hpp.

Referenced by safeRun().

◆ loadPlugin()

void Ark::VM::loadPlugin ( uint16_t id,
internal::ExecutionContext & context )
private

◆ loadSymbol()

Value * Ark::VM::loadSymbol ( uint16_t id,
internal::ExecutionContext & context )
inlinenodiscardprivate

Load a symbol by its id in the current context. Performs a lookup in the scope stack, in reverse order.

Parameters
idsymbol id
context
Returns
Value* nullptr if the symbol could not be loaded

Definition at line 88 of file VM.hpp.

Referenced by safeRun().

◆ loadSymbolFromIndex()

Value * Ark::VM::loadSymbolFromIndex ( uint16_t index,
internal::ExecutionContext & context )
inlinenodiscardprivate

Load a symbol by its (reversed) index in the current scope.

Parameters
indexindex of the symbol to load, starting from the end
context
Returns
Value*

Definition at line 103 of file VM.hpp.

Referenced by safeRun().

◆ operator[]()

Value & Ark::VM::operator[] ( const std::string & name)
noexcept

Retrieve a value from the virtual machine, given its symbol name.

Parameters
namethe name of the variable to retrieve
Returns
Value&

Definition at line 119 of file VM.cpp.

References Ark::internal::Builtins::nil.

◆ pop()

Value * Ark::VM::pop ( internal::ExecutionContext & context)
inlineprivate

Pop a value from the stack.

Parameters
context
Returns
Value*

Definition at line 150 of file VM.hpp.

Referenced by backtrace(), and safeRun().

◆ popAndResolveAsPtr()

Value * Ark::VM::popAndResolveAsPtr ( internal::ExecutionContext & context)
inlineprivate

Pop a value from the stack and resolve it if possible, then return it.

Parameters
context
Returns
Value*

Definition at line 181 of file VM.hpp.

Referenced by backtrace(), and safeRun().

◆ push() [1/3]

void Ark::VM::push ( const Value & value,
internal::ExecutionContext & context )
inlineprivate

Push a value on the stack.

Parameters
value
context

Definition at line 160 of file VM.hpp.

Referenced by safeRun().

◆ push() [2/3]

void Ark::VM::push ( Value && value,
internal::ExecutionContext & context )
inlineprivate

Push a value on the stack.

Parameters
value
context

Definition at line 167 of file VM.hpp.

◆ push() [3/3]

void Ark::VM::push ( Value * valptr,
internal::ExecutionContext & context )
inlineprivate

Push a value on the stack as a reference.

Parameters
valptr
context

Definition at line 174 of file VM.hpp.

◆ resolve()

Value Ark::VM::resolve ( internal::ExecutionContext * context,
const std::vector< Value > & n )
inline

Resolves a function call (called by plugins and builtins)

Parameters
contextthe execution context to use
nthe function and its arguments
Returns
Value

Definition at line 54 of file VM.hpp.

◆ returnFromFuncCall()

void Ark::VM::returnFromFuncCall ( internal::ExecutionContext & context)
inlineprivate

Destroy the current frame and get back to the previous one, resuming execution.

Doing the job nobody wants to do: cleaning after everyone has finished to play. This is a sort of primitive garbage collector

Parameters
context

Definition at line 256 of file VM.hpp.

Referenced by backtrace(), safeRun(), and throwArityError().

◆ run()

int Ark::VM::run ( bool fail_with_exception = false)

Run the bytecode held in the state.

Parameters
fail_with_exceptionthrow if true, display a stacktrace if false
Returns
int the exit code (default to 0 if no error)

Definition at line 323 of file VM.cpp.

References init(), m_execution_contexts, m_exit_code, and safeRun().

Referenced by main().

◆ safeRun()

int Ark::VM::safeRun ( internal::ExecutionContext & context,
std::size_t untilFrameCount = 0,
bool fail_with_exception = false )
private

Run ArkScript bytecode inside a try catch to retrieve all the exceptions and display a stack trace if needed.

Parameters
context
untilFrameCountthe frame count we need to reach before stopping the VM
fail_with_exceptionthrow if true, display a stacktrace if false
Returns
int the exit code

Definition at line 330 of file VM.cpp.

References Ark::internal::ADD, Ark::Any, Ark::internal::APPEND, Ark::internal::APPEND_IN_PLACE, Ark::internal::ASSERT, Ark::internal::AT, Ark::internal::AT_AT, backtrace(), Ark::internal::BUILTIN, Ark::internal::Builtins::builtins, Ark::internal::CALL, call(), Ark::internal::CALL_BUILTIN, callBuiltin(), Ark::internal::CAPTURE, Ark::Closure, Ark::internal::CONCAT, Ark::internal::CONCAT_IN_PLACE, Ark::Value::constList(), Ark::internal::CREATE_SCOPE, Ark::internal::DECREMENT, Ark::internal::DECREMENT_BY_INDEX, Ark::internal::DEL, Ark::Error::details(), DISPATCH, Ark::internal::DIV, Ark::internal::DUP, Ark::internal::EMPTY, Ark::internal::EQ, Ark::internal::Builtins::falseSym, Ark::internal::ExecutionContext::fc, findNearestVariable(), Ark::internal::GE, Ark::internal::GET_FIELD, GOTO_HALT, Ark::internal::GT, Ark::internal::HALT, Ark::internal::HASFIELD, Ark::internal::Closure::hasFieldEndingWith(), Ark::internal::HEAD, Ark::helper::head(), Ark::internal::INCREMENT, Ark::internal::INCREMENT_BY_INDEX, Ark::InstPtr, internal::Closure, Ark::internal::ExecutionContext::ip, Ark::Utils::isDouble(), Ark::Value::isIndexable(), Ark::internal::ISNIL, Ark::internal::JUMP, Ark::internal::ExecutionContext::last_symbol, Ark::internal::LE, Ark::internal::LEN, Ark::internal::LIST, Ark::List, Ark::Value::list(), Ark::internal::LOAD_CONST, Ark::internal::LOAD_CONST_LOAD_CONST, Ark::internal::LOAD_CONST_SET_VAL, Ark::internal::LOAD_CONST_STORE, Ark::internal::LOAD_SYMBOL, Ark::internal::LOAD_SYMBOL_BY_INDEX, loadConstAsPtr(), loadPlugin(), loadSymbol(), loadSymbolFromIndex(), Ark::internal::ExecutionContext::locals, Ark::internal::LT, Ark::State::m_constants, m_exit_code, Ark::State::m_pages, m_running, m_state, Ark::State::m_symbols, m_undefined_value, Ark::internal::MAKE_CLOSURE, Ark::internal::MOD, Ark::internal::MUL, Ark::internal::NEQ, Ark::internal::Builtins::nil, Ark::internal::NOP, Ark::internal::NOT, Ark::Number, Ark::Value::number(), Ark::Value::pageAddr(), Ark::internal::PLUGIN, Ark::internal::POP, pop(), Ark::internal::POP_JUMP_IF_FALSE, Ark::internal::POP_JUMP_IF_TRUE, Ark::internal::POP_LIST, Ark::internal::POP_LIST_IN_PLACE, Ark::internal::POP_SCOPE, popAndResolveAsPtr(), Ark::internal::ExecutionContext::pp, push(), Ark::Value::push_back(), Ark::Value::refClosure(), Ark::Reference, Ark::Value::reference(), Ark::internal::Closure::refScope(), Ark::internal::RESET_SCOPE, Ark::internal::RET, returnFromFuncCall(), Ark::internal::ExecutionContext::saved_scope, Ark::internal::Closure::scopePtr(), Ark::internal::ExecutionContext::scopes_storage, Ark::internal::SET_AT_2_INDEX, Ark::internal::SET_AT_INDEX, Ark::internal::SET_VAL, Ark::internal::SET_VAL_FROM, Ark::internal::SET_VAL_FROM_INDEX, Ark::internal::SET_VAL_HEAD, Ark::internal::SET_VAL_HEAD_BY_INDEX, Ark::internal::SET_VAL_TAIL, Ark::internal::SET_VAL_TAIL_BY_INDEX, setVal(), showBacktraceWithException(), Ark::internal::ExecutionContext::sp, Ark::internal::ExecutionContext::stack, Ark::internal::STORE, store(), Ark::internal::STORE_FROM, Ark::internal::STORE_FROM_INDEX, Ark::internal::STORE_HEAD, Ark::internal::STORE_HEAD_BY_INDEX, Ark::internal::STORE_TAIL, Ark::internal::STORE_TAIL_BY_INDEX, Ark::String, Ark::Value::string(), Ark::Value::stringRef(), Ark::internal::SUB, Ark::internal::TAIL, Ark::helper::tail(), TARGET, throwVMError(), Ark::internal::TO_NUM, Ark::internal::TO_STR, Ark::internal::Closure::toString(), Ark::Value::toString(), Ark::internal::Builtins::trueSym, Ark::internal::TYPE, Ark::types_to_str, UNPACK_ARGS, Ark::User, Value, Ark::Value::valueType(), and Ark::VMStackSize.

Referenced by Ark::Repl::run(), and run().

◆ setVal()

void Ark::VM::setVal ( uint16_t id,
const Value * val,
internal::ExecutionContext & context )
inlineprivate

Change the value of a symbol given its identifier.

Parameters
id
val
context

Definition at line 128 of file VM.hpp.

Referenced by safeRun().

◆ showBacktraceWithException()

void Ark::VM::showBacktraceWithException ( const std::exception & e,
internal::ExecutionContext & context )
private

Definition at line 1654 of file VM.cpp.

References backtrace(), and m_exit_code.

Referenced by safeRun().

◆ store()

void Ark::VM::store ( uint16_t id,
const Value * val,
internal::ExecutionContext & context )
inlineprivate

Create a new symbol with an associated value in the current scope.

Parameters
id
val
context

Definition at line 118 of file VM.hpp.

Referenced by safeRun().

◆ swapStackForFunCall()

void Ark::VM::swapStackForFunCall ( uint16_t argc,
internal::ExecutionContext & context )
inlineprivate

Move stack values around and invert them.

values: 1, 2, 3, _, _ wanted: pp, ip, 3, 2, 1 positions: 0, 1, 2, 3, 4

Parameters
argcnumber of arguments to swap around
context

Definition at line 189 of file VM.hpp.

◆ throwArityError()

◆ throwVMError()

void Ark::VM::throwVMError ( internal::ErrorKind kind,
const std::string & message )
staticprivate

Throw a VM error message.

Parameters
kindtype of VM error
message

Definition at line 1599 of file VM.cpp.

References Ark::internal::errorKinds.

Referenced by loadPlugin(), safeRun(), and throwArityError().

Friends And Related Symbol Documentation

◆ internal::Closure

friend class internal::Closure
friend

Definition at line 152 of file VM.hpp.

Referenced by safeRun().

◆ Repl

friend class Repl
friend

Definition at line 153 of file VM.hpp.

◆ Value

friend class Value
friend

Definition at line 151 of file VM.hpp.

Referenced by backtrace(), safeRun(), and throwArityError().

Member Data Documentation

◆ m_execution_contexts

std::vector<std::unique_ptr<internal::ExecutionContext> > Ark::VM::m_execution_contexts
private

◆ m_exit_code

int Ark::VM::m_exit_code
private

VM exit code, defaults to 0. Can be changed through sys:exit

Definition at line 158 of file VM.hpp.

Referenced by init(), run(), safeRun(), and showBacktraceWithException().

◆ m_futures

std::vector<std::unique_ptr<internal::Future> > Ark::VM::m_futures
private

Storing the promises while we are resolving them.

Definition at line 162 of file VM.hpp.

Referenced by createFuture(), and deleteFuture().

◆ m_mutex

std::mutex Ark::VM::m_mutex
private

Definition at line 160 of file VM.hpp.

Referenced by createAndGetContext(), createFuture(), deleteContext(), and deleteFuture().

◆ m_no_value

Value Ark::VM::m_no_value = internal::Builtins::nil
private

Definition at line 165 of file VM.hpp.

◆ m_running

bool Ark::VM::m_running
private

Definition at line 159 of file VM.hpp.

Referenced by safeRun().

◆ m_shared_lib_objects

std::vector<std::shared_ptr<internal::SharedLibrary> > Ark::VM::m_shared_lib_objects
private

Definition at line 161 of file VM.hpp.

Referenced by forceReloadPlugins(), init(), and loadPlugin().

◆ m_state

State& Ark::VM::m_state
private

◆ m_undefined_value

Value Ark::VM::m_undefined_value
private

Definition at line 166 of file VM.hpp.

Referenced by safeRun().


The documentation for this class was generated from the following files: