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.
 
template<typename... Args>
Value resolve (const Value *val, Args &&... args)
 Resolving a function call (called by plugins and builtins)
 
Value resolve (internal::ExecutionContext *context, 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::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)
 
ValueloadConstAsPtr (uint16_t id) const
 
void store (uint16_t id, const Value *val, internal::ExecutionContext &context)
 
void setVal (uint16_t id, const Value *val, internal::ExecutionContext &context)
 
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 backtrace (internal::ExecutionContext &context) noexcept
 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 43 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 79 of file VM.cpp.

Member Function Documentation

◆ backtrace()

void Ark::VM::backtrace ( internal::ExecutionContext & context)
privatenoexcept

Display a backtrace when the VM encounter an exception.

Parameters
context

Definition at line 1462 of file VM.cpp.

References Ark::InstPtr, Ark::internal::Scope::m_data, Ark::Value::pageAddr(), Ark::internal::Scope::size(), and Ark::Value::valueType().

Referenced by safeRun().

◆ 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 3 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 291 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 413 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 227 of file VM.cpp.

References Ark::internal::ExecutionContext::locals, m_execution_contexts, m_mutex, 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 256 of file VM.cpp.

References createAndGetContext(), 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 242 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 268 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 221 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 273 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 1447 of file VM.cpp.

◆ 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 282 of file VM.cpp.

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

◆ init()

◆ loadConstAsPtr()

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

Definition at line 140 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 )
inlineprivate

Definition at line 125 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 118 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 177 of file VM.hpp.

Referenced by 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 208 of file VM.hpp.

Referenced by 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 187 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 194 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 201 of file VM.hpp.

◆ resolve() [1/2]

template<typename... Args>
Value Ark::VM::resolve ( const Value * val,
Args &&... args )

Resolving a function call (called by plugins and builtins)

Template Parameters
Args
Parameters
valthe ArkScript function object
argsC++ argument list
Returns
Value

Definition at line 52 of file VM.hpp.

◆ resolve() [2/2]

Value Ark::VM::resolve ( internal::ExecutionContext * context,
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 91 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 283 of file VM.hpp.

Referenced by safeRun().

◆ 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 313 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 320 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::DEL, 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::types::generateError(), 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::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, loadConstAsPtr(), loadPlugin(), loadSymbol(), 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::RET, returnFromFuncCall(), Ark::internal::ExecutionContext::saved_scope, Ark::internal::Scope, Ark::internal::Closure::scopePtr(), Ark::internal::SET_AT_2_INDEX, Ark::internal::SET_AT_INDEX, Ark::internal::SET_VAL, Ark::internal::SET_VAL_FROM, Ark::internal::SET_VAL_HEAD, Ark::internal::SET_VAL_TAIL, setVal(), Ark::internal::ExecutionContext::sp, Ark::internal::ExecutionContext::stack, Ark::internal::STORE, store(), Ark::internal::STORE_FROM, Ark::internal::STORE_HEAD, Ark::internal::STORE_TAIL, 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 run().

◆ setVal()

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

Definition at line 155 of file VM.hpp.

Referenced by safeRun().

◆ store()

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

Definition at line 145 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 216 of file VM.hpp.

◆ 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 1457 of file VM.cpp.

References Ark::internal::errorKinds.

Referenced by loadPlugin(), and safeRun().

Friends And Related Symbol Documentation

◆ internal::Closure

friend class internal::Closure
friend

Definition at line 153 of file VM.hpp.

Referenced by safeRun().

◆ Repl

friend class Repl
friend

Definition at line 154 of file VM.hpp.

◆ Value

friend class Value
friend

Definition at line 152 of file VM.hpp.

Referenced by safeRun().

Member Data Documentation

◆ m_execution_contexts

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

Definition at line 158 of file VM.hpp.

Referenced by createAndGetContext(), deleteContext(), forceReloadPlugins(), init(), and run().

◆ 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 159 of file VM.hpp.

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

◆ 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 163 of file VM.hpp.

Referenced by createFuture(), and deleteFuture().

◆ m_mutex

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

Definition at line 161 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 166 of file VM.hpp.

◆ m_running

bool Ark::VM::m_running
private

Definition at line 160 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 162 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 167 of file VM.hpp.

Referenced by safeRun().


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