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

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

#include <VM.hpp>

+ Collaboration diagram for Ark::VM:

Public Member Functions

 VM (State &state) noexcept
 Construct a new vm t object. More...
 
 VM (State *state) noexcept
 
int run () noexcept
 Run the bytecode held in the state. More...
 
Valueoperator[] (const std::string &name) noexcept
 Retrieve a value from the virtual machine, given its symbol name. More...
 
template<typename... Args>
Value call (const std::string &name, Args &&... args)
 Call a function from ArkScript, by giving it arguments. More...
 
template<typename... Args>
Value resolve (const Value *val, Args &&... args)
 Resolving a function call (called by plugins) More...
 
void exit (int code) noexcept
 Ask the VM to exit with a given exit code. More...
 
void setUserPointer (void *ptr) noexcept
 Set the User Pointer object. More...
 
void * getUserPointer () noexcept
 Retrieves the stored pointer. More...
 

Private Member Functions

int safeRun (internal::ExecutionContext &context, std::size_t untilFrameCount=0)
 Run ArkScript bytecode inside a try catch to retrieve all the exceptions and display a stack trace if needed. More...
 
void init () noexcept
 Initialize the VM according to the parameters. More...
 
uint16_t readNumber (internal::ExecutionContext &context)
 Read a 2 bytes number from the current bytecode page, starting at the current instruction. More...
 
Valuepop (internal::ExecutionContext &context)
 Pop a value from the stack. More...
 
void push (const Value &val, internal::ExecutionContext &context)
 Push a value on the stack. More...
 
void push (Value &&val, internal::ExecutionContext &context)
 Push a value on the stack. More...
 
void push (Value *valptr, internal::ExecutionContext &context)
 Push a value on the stack as a reference. More...
 
ValuepopAndResolveAsPtr (internal::ExecutionContext &context)
 Pop a value from the stack and resolve it if possible, then return it. More...
 
void swapStackForFunCall (uint16_t argc, internal::ExecutionContext &context)
 Move stack values around and invert them. More...
 
void createNewScope (internal::ExecutionContext &context) noexcept
 
ValuefindNearestVariable (uint16_t id, internal::ExecutionContext &context) noexcept
 Find the nearest variable of a given id. More...
 
void returnFromFuncCall (internal::ExecutionContext &context)
 Destroy the current frame and get back to the previous one, resuming execution. More...
 
void loadPlugin (uint16_t id, internal::ExecutionContext &context)
 Load a plugin from a constant id. More...
 
uint16_t findNearestVariableIdWithValue (const Value &value, internal::ExecutionContext &context) const noexcept
 Find the nearest variable id with a given value. More...
 
void throwVMError (const std::string &message)
 Throw a VM error message. More...
 
void backtrace (internal::ExecutionContext &context) noexcept
 Display a backtrace when the VM encounter an exception. More...
 
void call (internal::ExecutionContext &context, int16_t argc_=-1)
 Function called when the CALL instruction is met in the bytecode. More...
 

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 More...
 
uint16_t m_fc
 current frames count More...
 
bool m_running
 
std::size_t m_until_frame_count
 
std::mutex m_mutex
 
std::vector< std::shared_ptr< internal::SharedLibrary > > m_shared_lib_objects
 
Value m_no_value = internal::Builtins::nil
 
void * m_user_pointer
 needed to pass data around when binding ArkScript in a program More...
 

Friends

class Value
 
class Repl
 

Detailed Description

The ArkScript virtual machine, executing ArkScript bytecode.

Definition at line 45 of file VM.hpp.

Constructor & Destructor Documentation

◆ VM() [1/2]

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

◆ VM() [2/2]

Ark::VM::VM ( State state)
inlineexplicitnoexcept

Definition at line 55 of file VM.hpp.

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 1184 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

Referenced by safeRun().

◆ call() [2/2]

void Ark::VM::call ( internal::ExecutionContext context,
int16_t  argc_ = -1 
)
inlineprivate

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

Parameters
context
argc_number of arguments already sent, default to -1 if it needs to search for them by itself

◆ createNewScope()

void Ark::VM::createNewScope ( internal::ExecutionContext context)
inlineprivatenoexcept

Referenced by init().

◆ 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 172 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*

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

◆ getUserPointer()

void * Ark::VM::getUserPointer ( )
noexcept

Retrieves the stored pointer.

Returns
void*

Definition at line 187 of file VM.cpp.

References m_user_pointer.

◆ init()

◆ loadPlugin()

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

◆ 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 68 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*

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*

Referenced by safeRun().

◆ push() [1/3]

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

Push a value on the stack.

Parameters
val
context

Referenced by safeRun().

◆ push() [2/3]

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

Push a value on the stack.

Parameters
val
context

◆ 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

◆ readNumber()

uint16_t Ark::VM::readNumber ( internal::ExecutionContext context)
inlineprivate

Read a 2 bytes number from the current bytecode page, starting at the current instruction.

Modify the instruction pointer to point on the instruction right after the number.

Parameters
context
Returns
uint16_t

Referenced by safeRun().

◆ resolve()

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

Resolving a function call (called by plugins)

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

◆ 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

Referenced by safeRun().

◆ run()

int Ark::VM::run ( )
noexcept

Run the bytecode held in the state.

Returns
int the exit code (default to 0 if no error)

Definition at line 196 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 
)
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
Returns
int the exit code

Definition at line 211 of file VM.cpp.

References Ark::internal::ADD, Ark::internal::AND_, Ark::Any, Ark::internal::APPEND, Ark::internal::APPEND_IN_PLACE, Ark::internal::ASSERT, Ark::internal::AT, backtrace(), Ark::internal::BUILTIN, Ark::internal::Builtins::builtins, Ark::internal::CALL, call(), Ark::internal::CAPTURE, Ark::Closure, Ark::internal::CONCAT, Ark::internal::CONCAT_IN_PLACE, Ark::Value::constList(), COZ_PROGRESS_NAMED, Ark::internal::DEL, Ark::internal::DIV, Ark::internal::EMPTY, Ark::internal::EQ, Ark::internal::Builtins::falseSym, findNearestVariable(), Ark::internal::GE, Ark::types::generateError(), Ark::internal::GET_FIELD, Ark::internal::GT, Ark::internal::HALT, Ark::internal::HASFIELD, Ark::internal::HEAD, Ark::InstPtr, Ark::internal::ExecutionContext::ip, Ark::Value::isConst(), Ark::Utils::isDouble(), Ark::internal::ISNIL, Ark::internal::JUMP, Ark::internal::ExecutionContext::last_symbol, Ark::internal::LE, Ark::internal::LEN, Ark::internal::LET, Ark::internal::LIST, Ark::List, Ark::Value::list(), Ark::internal::LOAD_CONST, Ark::internal::LOAD_SYMBOL, loadPlugin(), Ark::internal::ExecutionContext::locals, Ark::internal::LT, Ark::State::m_constants, Ark::State::m_debug_level, m_exit_code, m_fc, Ark::State::m_pages, m_running, m_state, Ark::State::m_symbols, m_until_frame_count, Ark::internal::MOD, Ark::internal::MUL, Ark::internal::MUT, Ark::internal::NEQ, Ark::internal::Builtins::nil, Ark::Nil, Ark::internal::NOT, Ark::Number, Ark::Value::number(), Ark::internal::OR_, Ark::PageAddr, 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, popAndResolveAsPtr(), Ark::internal::ExecutionContext::pp, push(), Ark::Value::push_back(), readNumber(), Ark::Value::refClosure(), Ark::Reference, Ark::Value::reference(), Ark::internal::RET, returnFromFuncCall(), Ark::internal::SAVE_ENV, Ark::internal::ExecutionContext::saved_scope, Ark::internal::Closure::scope(), Ark::internal::ExecutionContext::scope_count_to_delete, Ark::Value::setConst(), Ark::internal::ExecutionContext::sp, Ark::internal::STORE, Ark::String, Ark::Value::string(), Ark::Value::stringRef(), Ark::internal::SUB, Ark::internal::TAIL, throwVMError(), Ark::internal::TO_NUM, Ark::internal::TO_STR, Ark::internal::Builtins::trueSym, Ark::internal::TYPE, Ark::types_to_str, Ark::User, Value, Ark::Value::valueType(), and Ark::VMStackSize.

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

◆ setUserPointer()

void Ark::VM::setUserPointer ( void *  ptr)
noexcept

Set the User Pointer object.

Parameters
ptrPointer to data NOT owned by the VM, to be used later

Definition at line 182 of file VM.cpp.

◆ 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

◆ throwVMError()

void Ark::VM::throwVMError ( const std::string &  message)
private

Throw a VM error message.

Parameters
message

Definition at line 1179 of file VM.cpp.

Referenced by loadPlugin(), and safeRun().

Friends And Related Function Documentation

◆ Repl

friend class Repl
friend

Definition at line 122 of file VM.hpp.

◆ Value

friend class Value
friend

Definition at line 121 of file VM.hpp.

Referenced by loadPlugin(), and safeRun().

Member Data Documentation

◆ m_execution_contexts

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

Definition at line 126 of file VM.hpp.

Referenced by init(), Ark::Repl::run(), 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 127 of file VM.hpp.

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

◆ m_fc

uint16_t Ark::VM::m_fc
private

current frames count

Definition at line 128 of file VM.hpp.

Referenced by init(), and safeRun().

◆ m_mutex

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

Definition at line 131 of file VM.hpp.

◆ m_no_value

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

Definition at line 135 of file VM.hpp.

◆ m_running

bool Ark::VM::m_running
private

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

Referenced by init(), and loadPlugin().

◆ m_state

State& Ark::VM::m_state
private

Definition at line 125 of file VM.hpp.

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

◆ m_until_frame_count

std::size_t Ark::VM::m_until_frame_count
private

Definition at line 130 of file VM.hpp.

Referenced by safeRun().

◆ m_user_pointer

void* Ark::VM::m_user_pointer
private

needed to pass data around when binding ArkScript in a program

Definition at line 137 of file VM.hpp.

Referenced by getUserPointer().


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