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.
	VM (State *state) noexcept
int	run () noexcept
	Run the bytecode held in the state.
Value &	operator[] (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.
void	setUserPointer (void *ptr) noexcept
	Set the User Pointer object.
void *	getUserPointer () noexcept
	Retrieves the stored pointer.
internal::ExecutionContext *	createAndGetContext ()
	Create an execution context and returns it.
void	deleteContext (internal::ExecutionContext *ec)
	Free a given execution context.
internal::Future *	createFuture (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.

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.
void	init () noexcept
	Initialize the VM according to the parameters.
uint16_t	readNumber (internal::ExecutionContext &context)
	Read a 2 bytes number from the current bytecode page, starting at the current instruction.
Value *	pop (internal::ExecutionContext &context)
	Pop a value from the stack.
void	push (const Value &val, internal::ExecutionContext &context)
	Push a value on the stack.
void	push (Value &&val, 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.
Value *	popAndResolveAsPtr (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.
void	createNewScope (internal::ExecutionContext &context) noexcept
Value *	findNearestVariable (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	throwVMError (internal::ErrorKind kind, const std::string &message)
	Throw a VM error message.
void	backtrace (internal::ExecutionContext &context) noexcept
	Display a backtrace when the VM encounter an exception.
void	call (internal::ExecutionContext &context, int16_t argc_=-1)
	Function called when the CALL instruction is met in the bytecode.

Private Attributes
State &	m_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
void *	m_user_pointer
	needed to pass data around when binding ArkScript in a program

Friends
class	Value
class	internal::Closure
class	Repl

Detailed Description

The ArkScript virtual machine, executing ArkScript bytecode.

Definition at line 47 of file VM.hpp.

Constructor & Destructor Documentation

VM() [1/2]

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

explicitnoexcept

Construct a new vm t object.

Parameters

state

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

Definition at line 25 of file VM.cpp.

VM() [2/2]

Ark::VM::VM ( State *  state )

inlineexplicitnoexcept

Definition at line 57 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 1227 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

name	the function name in the ArkScript code
args	C++ 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

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

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

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

References createAndGetContext(), m_futures, and m_mutex.

createNewScope()

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

inlineprivatenoexcept

Referenced by init().

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

References m_execution_contexts, and m_mutex.

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

code	an exit code

Definition at line 165 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

id	the 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

value	the value to search for
context

Returns

uint16_t

Definition at line 1212 of file VM.cpp.

getUserPointer()

void * Ark::VM::getUserPointer ( )

noexcept

Retrieves the stored pointer.

Returns

void*

Definition at line 180 of file VM.cpp.

References m_user_pointer.

init()

void Ark::VM::init ( )

privatenoexcept

Initialize the VM according to the parameters.

Definition at line 33 of file VM.cpp.

References createNewScope(), Ark::internal::ExecutionContext::fc, Ark::internal::ExecutionContext::locals, Ark::State::m_binded, m_execution_contexts, m_exit_code, m_shared_lib_objects, m_state, Ark::State::m_symbols, Ark::internal::ExecutionContext::saved_scope, Ark::internal::ExecutionContext::scope_count_to_delete, and Ark::internal::ExecutionContext::sp.

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

loadPlugin()

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

private

Load a plugin from a constant id.

Parameters

id	Id of the constant
context

Definition at line 88 of file VM.cpp.

References ARK_NO_NAME_FILE, Ark::Utils::fileExists(), Ark::internal::ExecutionContext::locals, Ark::State::m_constants, Ark::State::m_filename, Ark::State::m_libenv, m_shared_lib_objects, m_state, Ark::State::m_symbols, Ark::mapping::name, throwVMError(), and Value.

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

name	the name of the variable to retrieve

Returns

Value&

Definition at line 66 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() [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

val	the ArkScript function object
args	C++ 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

context	the execution context to use
n	the 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

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 245 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
untilFrameCount	the frame count we need to reach before stopping the VM

Returns

int the exit code

Definition at line 260 of file VM.cpp.

References Ark::Any, backtrace(), Ark::internal::Builtins::builtins, call(), Ark::Closure, Ark::Value::constList(), Ark::internal::Builtins::falseSym, Ark::internal::ExecutionContext::fc, findNearestVariable(), Ark::types::generateError(), Ark::InstPtr, internal::Closure, Ark::internal::ExecutionContext::ip, Ark::Value::isConst(), Ark::Utils::isDouble(), Ark::internal::ExecutionContext::last_symbol, Ark::List, Ark::Value::list(), loadPlugin(), Ark::internal::ExecutionContext::locals, Ark::State::m_constants, Ark::State::m_debug_level, m_exit_code, Ark::State::m_pages, m_running, m_state, Ark::State::m_symbols, Ark::internal::Builtins::nil, Ark::Number, Ark::Value::number(), Ark::PageAddr, Ark::Value::pageAddr(), pop(), popAndResolveAsPtr(), Ark::internal::ExecutionContext::pp, push(), Ark::Value::push_back(), readNumber(), Ark::Value::refClosure(), Ark::Reference, Ark::Value::reference(), returnFromFuncCall(), Ark::internal::ExecutionContext::saved_scope, Ark::internal::Closure::scope(), Ark::internal::ExecutionContext::scope_count_to_delete, Ark::Value::setConst(), Ark::internal::ExecutionContext::sp, Ark::String, Ark::Value::string(), Ark::Value::stringRef(), throwVMError(), Ark::Value::toString(), Ark::internal::Builtins::trueSym, 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

ptr	Pointer to data NOT owned by the VM, to be used later

Definition at line 175 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

argc	number of arguments to swap around
context

throwVMError()

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

private

Throw a VM error message.

Parameters

kind	type of VM error
message

Definition at line 1222 of file VM.cpp.

References Ark::internal::errorKinds.

Referenced by loadPlugin(), and safeRun().

Friends And Related Function Documentation

internal::Closure

friend class internal::Closure

friend

Definition at line 166 of file VM.hpp.

Referenced by safeRun().

Repl

friend class Repl

friend

Definition at line 167 of file VM.hpp.

Value

friend class Value

friend

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

Referenced by createAndGetContext(), deleteContext(), 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 172 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 176 of file VM.hpp.

Referenced by createFuture(), and deleteFuture().

m_mutex

std::mutex Ark::VM::m_mutex

private

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

m_running

bool Ark::VM::m_running

private

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

Referenced by init(), and loadPlugin().

m_state

State& Ark::VM::m_state

private

Definition at line 170 of file VM.hpp.

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

m_undefined_value

Value Ark::VM::m_undefined_value

private

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

Referenced by getUserPointer().

---

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

• /Users/fola/Documents/ArkScript/Ark/include/Ark/VM/VM.hpp
• /Users/fola/Documents/ArkScript/Ark/src/arkreactor/VM/VM.cpp