Bond::VM Class Reference

A virtual machine that executes the Bond bytecode in a CodeSegment. More...

#include <bond/vm/vm.h>

Public Member Functions
	VM (Allocator &allocator, const CodeSegment &codeSegment, size_t stackSize, InputStream *stdIn=nullptr, OutputStream *stdOut=nullptr, OutputStream *stdErr=nullptr, StreamFactory *streamFactory=nullptr)
	Constructs a VM object.
	~VM ()
	Destroys the VM and frees its stack.
Allocator &	GetAllocator () const
	Returns the memory allocator used by the VM.
const CodeSegment &	GetCodeSegment () const
	Returns the CodeSegment executed by the VM.
StackFrame *	GetStackFrame ()
	Returns a pointer to the StackFrame at the top of the call stack, which is that of the function currently being executed.
const StackFrame &	GetStackFrame () const
	Returns the StackFrame at the top of the call stack, which is that of the function currently being executed.
StackFrame &	GetCallerStackFrame ()
	Returns the StackFrame immediately below the top of the call stack, which is that of the caller of the function currently being executed.
const StackFrame &	GetCallerStackFrame () const
	Returns the StackFrame immediately below the top of the call stack, which is that of the caller of the function currently being executed.
InputStreamAdaptor &	GetStdIn ()
	Returns the adaptor wrapping the standard input stream given to the constructor.
OutputStreamAdaptor &	GetStdOut ()
	Returns the adaptor wrapping the standard output stream given to the constructor.
OutputStreamAdaptor &	GetStdErr ()
	Returns the adaptor wrapping the standard error stream given to the constructor.
StreamFactory *	GetStreamFactory ()
	Returns the StreamFactory given to the constructor, or null if there is none.
void	DumpCallStack (OutputStream &stream) const
	Writes a description of every StackFrame on the call stack, from the top down, to the given stream.
void	DumpStackFrame (OutputStream &stream, const StackFrame &frame) const
	Writes a description of the given StackFrame, consisting of the signature of its function and the values of its arguments, to the given stream.
void	RaiseError (const char *format,...) const
	Throws a Bond::Exception whose message is the formatted error message followed by a dump of the call stack.
template<typename ReturnType, typename... Args>
void	CallFunction (const QualifiedName &functionName, ReturnType *returnAddress, Args... args)
	Invokes a function that returns a value with the given arguments.
template<typename ReturnType, typename... Args>
void	CallFunction (const char *functionName, ReturnType *returnAddress, Args... args)
	Invokes a function that returns a value with the given arguments.
template<typename ReturnType, typename... Args>
void	CallFunction (const Function &function, ReturnType *returnAddress, Args... args)
	Invokes a function that returns a value with the given arguments.
template<typename... Args>
void	CallVoidFunction (const QualifiedName &functionName, Args... args)
	Invokes a function that returns void with the given arguments.
template<typename... Args>
void	CallVoidFunction (const char *functionName, Args... args)
	Invokes a function that returns void with the given arguments.
template<typename... Args>
void	CallVoidFunction (const Function &function, Args... args)
	Invokes a function that returns void with the given arguments.
VM &	operator= (const VM &other)=delete

Friends
class	InvocationStackFrame

Detailed Description

A virtual machine that executes the Bond bytecode in a CodeSegment.

A VM owns a stack of a fixed size on which the frames of invoked functions are allocated. It executes Bond functions by interpreting their bytecode and invokes native functions through their bound NativeFunction. Functions are invoked from native code with CallFunction(), CallVoidFunction() or an InvocationStackFrame. Errors detected while executing code, such as a stack overflow, are reported by throwing a Bond::Exception whose message includes a dump of the call stack.

The VM does not call the static initializers of the CodeSegment; an application typically calls CodeSegment::CallStaticInitializers() before invoking its entry point.

See also

CboLoader, CodeSegment, InvocationStackFrame, StackFrame

Constructor & Destructor Documentation

VM()

Bond::VM::VM	(	Allocator &	allocator,
		const CodeSegment &	codeSegment,
		size_t	stackSize,
		InputStream *	stdIn = nullptr,
		OutputStream *	stdOut = nullptr,
		OutputStream *	stdErr = nullptr,
		StreamFactory *	streamFactory = nullptr )

Constructs a VM object.

Parameters

allocator	The memory allocator from which the VM stack is allocated. It is also available to native functions via GetAllocator().
codeSegment	The CodeSegment containing the functions and data executed by the VM. It is not copied, so it must remain valid for the lifetime of the VM.
stackSize	The size of the VM stack in bytes.
stdIn	The stream wrapped by the adaptor returned by GetStdIn(), or null.
stdOut	The stream wrapped by the adaptor returned by GetStdOut(), or null.
stdErr	The stream wrapped by the adaptor returned by GetStdErr(), or null.
streamFactory	The factory used by the Bond Standard Library to open files, or null. None of the streams nor the factory are owned by the VM, so they must remain valid for as long as the VM uses them.

~VM()

Bond::VM::~VM

(

)

Destroys the VM and frees its stack.

Member Function Documentation

CallFunction() [1/3]

template<typename ReturnType, typename... Args>

void Bond::VM::CallFunction	(	const char *	functionName,
		ReturnType *	returnAddress,
		Args...	args )

Invokes a function that returns a value with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

functionName	The fully qualified name of the function with its elements separated by the '.' character, e.g. "Namespace.Function".
returnAddress	Pointer to where the return value is written.
args	The arguments passed to the function.

CallFunction() [2/3]

template<typename ReturnType, typename... Args>

void Bond::VM::CallFunction	(	const Function &	function,
		ReturnType *	returnAddress,
		Args...	args )

Invokes a function that returns a value with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

function	The function to be invoked. It must belong to the VM's CodeSegment.
returnAddress	Pointer to where the return value is written.
args	The arguments passed to the function.

CallFunction() [3/3]

template<typename ReturnType, typename... Args>

void Bond::VM::CallFunction	(	const QualifiedName &	functionName,
		ReturnType *	returnAddress,
		Args...	args )

Invokes a function that returns a value with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

functionName	The fully qualified name of the function.
returnAddress	Pointer to where the return value is written.
args	The arguments passed to the function.

CallVoidFunction() [1/3]

template<typename... Args>

void Bond::VM::CallVoidFunction	(	const char *	functionName,
		Args...	args )

Invokes a function that returns void with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

functionName	The fully qualified name of the function with its elements separated by the '.' character, e.g. "Namespace.Function".
args	The arguments passed to the function.

CallVoidFunction() [2/3]

template<typename... Args>

void Bond::VM::CallVoidFunction	(	const Function &	function,
		Args...	args )

Invokes a function that returns void with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

function	The function to be invoked. It must belong to the VM's CodeSegment.
args	The arguments passed to the function.

CallVoidFunction() [3/3]

template<typename... Args>

void Bond::VM::CallVoidFunction	(	const QualifiedName &	functionName,
		Args...	args )

Invokes a function that returns void with the given arguments.

Equivalent to constructing an InvocationStackFrame, pushing the arguments with InvocationStackFrame::PushArgs() and calling InvocationStackFrame::Call().

Parameters

functionName	The fully qualified name of the function.
args	The arguments passed to the function.

DumpCallStack()

void Bond::VM::DumpCallStack

(

OutputStream &

stream

)

const

Writes a description of every StackFrame on the call stack, from the top down, to the given stream.

Parameters

stream

The stream to which the call stack is written.

DumpStackFrame()

void Bond::VM::DumpStackFrame	(	OutputStream &	stream,
		const StackFrame &	frame ) const

Writes a description of the given StackFrame, consisting of the signature of its function and the values of its arguments, to the given stream.

Parameters

stream	The stream to which the stack frame is written.
frame	The StackFrame to be written. Nothing is written if it is not associated with a function.

GetAllocator()

Allocator & Bond::VM::GetAllocator ( ) const

inline

Returns the memory allocator used by the VM.

GetCallerStackFrame() [1/2]

StackFrame & Bond::VM::GetCallerStackFrame

(

)

Returns the StackFrame immediately below the top of the call stack, which is that of the caller of the function currently being executed.

Throws a Bond::Exception if there is no such frame.

GetCallerStackFrame() [2/2]

const StackFrame & Bond::VM::GetCallerStackFrame

(

)

const

Returns the StackFrame immediately below the top of the call stack, which is that of the caller of the function currently being executed.

Throws a Bond::Exception if there is no such frame.

GetCodeSegment()

const CodeSegment & Bond::VM::GetCodeSegment ( ) const

inline

Returns the CodeSegment executed by the VM.

GetStackFrame() [1/2]

StackFrame * Bond::VM::GetStackFrame ( )

inline

Returns a pointer to the StackFrame at the top of the call stack, which is that of the function currently being executed.

GetStackFrame() [2/2]

const StackFrame & Bond::VM::GetStackFrame ( ) const

inline

Returns the StackFrame at the top of the call stack, which is that of the function currently being executed.

GetStdErr()

OutputStreamAdaptor & Bond::VM::GetStdErr ( )

inline

Returns the adaptor wrapping the standard error stream given to the constructor.

GetStdIn()

InputStreamAdaptor & Bond::VM::GetStdIn ( )

inline

Returns the adaptor wrapping the standard input stream given to the constructor.

GetStdOut()

OutputStreamAdaptor & Bond::VM::GetStdOut ( )

inline

Returns the adaptor wrapping the standard output stream given to the constructor.

GetStreamFactory()

StreamFactory * Bond::VM::GetStreamFactory ( )

inline

Returns the StreamFactory given to the constructor, or null if there is none.

operator=()

VM & Bond::VM::operator= ( const VM & other )

delete

RaiseError()

void Bond::VM::RaiseError	(	const char *	format,
			... ) const

Throws a Bond::Exception whose message is the formatted error message followed by a dump of the call stack.

Parameters

format

A printf-style format string for the error message.

Friends And Related Symbol Documentation

InvocationStackFrame

friend class InvocationStackFrame

friend

---

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

• include/bond/vm/vm.h