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 and builtins) More...
 
Value resolve (internal::ExecutionContext *context, std::vector< Value > &n)
 Resolves a function call (called by plugins and builtins) 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...
 
internal::ExecutionContextcreateAndGetContext ()
 Create an execution context and returns it. More...
 
void deleteContext (internal::ExecutionContext *ec)
 Free a given execution context. More...
 
internal::FuturecreateFuture (std::vector< Value > &args)
 Create a Future object from a function and its arguments and return a managed pointer to it. More...
 
void deleteFuture (internal::Future *f)
 Free a given future. 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...
 
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. More...
 
Value m_no_value = internal::Builtins::nil
 
Value m_undefined_value
 
void * m_user_pointer
 needed to pass data around when binding ArkScript in a program More...
 

Friends

class Value
 
class internal::Closure
 
class Repl
 

Detailed Description

The ArkScript virtual machine, executing ArkScript bytecode.

Definition at line 46 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 56 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 1238 of file VM.cpp.

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

◆ 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

◆ 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

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

References Ark::internal::ExecutionContext::locals, and Ark::internal::ExecutionContext::scope_count_to_delete.

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

◆ createNewScope()

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

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

Referenced by Ark::internal::Future::resolve().

◆ deleteFuture()

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

Free a given future.

This method is thread-safe VM wise.

Parameters
f

Definition at line 235 of file VM.cpp.

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

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

◆ getUserPointer()

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

Retrieves the stored pointer.

Returns
void*

Definition at line 187 of file VM.cpp.

◆ init()

void Ark::VM::init ( )
privatenoexcept

◆ loadPlugin()

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

Load a plugin from a constant id.

Parameters
idId of the constant
context

Definition at line 90 of file VM.cpp.

References ARK_NO_NAME_FILE, Ark::Utils::fileExists(), Ark::internal::ExecutionContext::locals, and mapping::name.

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

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

◆ push() [1/3]

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

Push a value on the stack.

Parameters
val
context

◆ 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

◆ 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

Referenced by Ark::internal::Future::Future().

◆ 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

◆ 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

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

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 267 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, Ark::internal::BUILTIN, Ark::internal::Builtins::builtins, Ark::internal::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, Ark::internal::ExecutionContext::fc, 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, Ark::internal::ExecutionContext::locals, Ark::internal::LT, 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, Ark::internal::POP_JUMP_IF_FALSE, Ark::internal::POP_JUMP_IF_TRUE, Ark::internal::POP_LIST, Ark::internal::POP_LIST_IN_PLACE, Ark::internal::ExecutionContext::pp, Ark::Value::push_back(), Ark::Value::refClosure(), Ark::Reference, Ark::Value::reference(), Ark::internal::RET, 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, Ark::internal::TO_NUM, Ark::internal::TO_STR, Ark::Value::toString(), Ark::internal::Builtins::trueSym, Ark::internal::TYPE, Ark::types_to_str, Ark::User, Ark::Value::valueType(), and Ark::VMStackSize.

Referenced by Ark::Repl::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 1233 of file VM.cpp.

Friends And Related Function Documentation

◆ internal::Closure

friend class internal::Closure
friend

Definition at line 165 of file VM.hpp.

◆ Repl

friend class Repl
friend

Definition at line 166 of file VM.hpp.

◆ Value

friend class Value
friend

Definition at line 164 of file VM.hpp.

Member Data Documentation

◆ m_execution_contexts

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

Definition at line 170 of file VM.hpp.

Referenced by Ark::Repl::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 171 of file VM.hpp.

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

◆ m_mutex

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

Definition at line 173 of file VM.hpp.

◆ m_no_value

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

Definition at line 178 of file VM.hpp.

◆ m_running

bool Ark::VM::m_running
private

Definition at line 172 of file VM.hpp.

◆ m_shared_lib_objects

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

Definition at line 174 of file VM.hpp.

◆ m_state

State& Ark::VM::m_state
private

Definition at line 169 of file VM.hpp.

◆ m_undefined_value

Value Ark::VM::m_undefined_value
private

Definition at line 179 of file VM.hpp.

◆ m_user_pointer

void* Ark::VM::m_user_pointer
private

needed to pass data around when binding ArkScript in a program

Definition at line 181 of file VM.hpp.


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