3.1. Virtual Machine

void sq_close(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

releases a quirrel VM and all related friend VMs

SQPRINTFUNCTION sq_geterrorfunc(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

a pointer to a SQPRINTFUNCTION, or NULL if no function has been set.

returns the current error function of the given Virtual machine. (see sq_setprintfunc())

SQUserPointer sq_getforeignptr(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

the current VMs foreign pointer.

Returns the foreign pointer of a VM instance.

SQPRINTFUNCTION sq_getprintfunc(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

a pointer to a SQPRINTFUNCTION, or NULL if no function has been set.

returns the current print function of the given Virtual machine. (see sq_setprintfunc())

SQUserPointer sq_getsharedforeignptr(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

the current VMs shared foreign pointer

Returns the shared foreign pointer of a group of friend VMs

SQUserPointer sq_getsharedreleasehook(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

the current VMs release hook.

Returns the shared release hook of a group of friend VMs

SQUserPointer sq_getvmreleasehook(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

the current VMs release hook.

Returns the release hook of a VM instance

SQInteger sq_getvmstate(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

the state of the vm encoded as integer value. The following constants are defined: SQ_VMSTATE_IDLE, SQ_VMSTATE_RUNNING, SQ_VMSTATE_SUSPENDED.

returns the execution state of a virtual machine

void sq_move(HSQUIRRELVM dest, HSQUIRRELVM src, SQInteger idx)
Parameters

  • dest (HSQUIRRELVM) – the destination VM

  • src (HSQUIRRELVM) – the source VM

  • idx (SQInteger) – the index in the source stack of the value that has to be moved

pushes the object at the position ‘idx’ of the source vm stack in the destination vm stack

HSQUIRRELVM sq_newthread(HSQUIRRELVM friendvm, SQInteger initialstacksize)
Parameters

  • friendvm (HSQUIRRELVM) – a friend VM

  • initialstacksize (SQInteger) – the size of the stack in slots(number of objects)

Returns

a pointer to the new VM.

Remarks

By default the roottable is shared with the VM passed as first parameter. The new VM lifetime is bound to the “thread” object pushed in the stack and behave like a normal quirrel object.

creates a new vm friendvm of the one passed as first parmeter and pushes it in its stack as “thread” object.

HSQUIRRELVM sq_open(SQInteger initialstacksize)
Parameters

  • initialstacksize (SQInteger) – the size of the stack in slots(number of objects)

Returns

an handle to a quirrel vm

Remarks

the returned VM has to be released with sq_releasevm

creates a new instance of a quirrel VM that consists in a new execution stack.

void sq_pushconsttable(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

pushes the current const table in the stack

void sq_pushregistrytable(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

pushes the registry table in the stack

void sq_pushroottable(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

pushes the current root table in the stack

void sq_setconsttable(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

pops a table from the stack and set it as const table

void sq_seterrorhandler(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Remarks

the error handler is shared by friend VMs

pops from the stack a closure or native closure an sets it as runtime-error handler.

void sq_setforeignptr(HSQUIRRELVM v, SQUserPointer p)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • p (SQUserPointer) – The pointer that has to be set

Sets the foreign pointer of a certain VM instance. The foreign pointer is an arbitrary user defined pointer associated to a VM (by default is value id 0). This pointer is ignored by the VM.

void sq_setprintfunc(HSQUIRRELVM v, SQPRINTFUNCTION printfunc, SQPRINTFUNCTION errorfunc)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • printfunc (SQPRINTFUNCTION) – a pointer to the print func or NULL to disable the output.

  • errorfunc (SQPRINTFUNCTION) – a pointer to the error func or NULL to disable the output.

Remarks

the print func has the following prototype: void printfunc(HSQUIRRELVM v,const SQChar *s,…)

sets the print function of the virtual machine. This function is used by the built-in function ‘print()’ to output text.

void sq_setroottable(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

pops a table from the stack and set it as root table

void sq_setsharedforeignptr(HSQUIRRELVM v, SQUserPointer p)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • p (SQUserPointer) – The pointer that has to be set

Sets the shared foreign pointer. The foreign pointer is an arbitrary user defined pointer associated to a group of friend VMs (by default is value id 0). After a “main” VM is created using sq_open() all friend VMs created with sq_newthread share the same shared pointer.

void sq_setsharedreleasehook(HSQUIRRELVM v, SQRELESEHOOK hook)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • hook (SQRELESEHOOK) – The hook that has to be set

Sets the release hook of a certain VM group. The release hook is invoked when the last vm of the group vm is destroyed (usually when sq_close() is invoked). The userpointer passed to the function is the shared foreignpointer(see sq_getsharedforeignptr()). After a “main” VM is created using sq_open() all friend VMs created with sq_newthread() share the same shared release hook.

void sq_setvmreleasehook(HSQUIRRELVM v, SQRELESEHOOK hook)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • hook (SQRELESEHOOK) – The hook that has to be set

Sets the release hook of a certain VM instance. The release hook is invoked when the vm is destroyed. The userpointer passed to the function is the vm foreignpointer (see sq_setforeignpointer())

HRESULT sq_suspendvm(HSQUIRRELVM v)
Parameters

  • v (HSQUIRRELVM) – the target VM

Returns

an SQRESULT(that has to be returned by a C function)

Remarks

sq_result can only be called as return expression of a C function. The function will fail is the suspension is done through more C calls or in a metamethod.

Suspends the execution of the specified vm.

.eg

SQInteger suspend_vm_example(HSQUIRRELVM v)
{
    return sq_suspendvm(v);
}
HRESULT sq_wakeupvm(HSQUIRRELVM v, SQBool resumedret, SQBool retval, SQBool invoke_err_handler, SQBool throwerror)
Parameters

  • v (HSQUIRRELVM) – the target VM

  • resumedret (SQBool) – if true the function will pop a value from the stack and use it as return value for the function that has previously suspended the virtual machine.

  • retval (SQBool) – if true the function will push the return value of the function that suspend the excution or the main function one.

  • invoke_err_handler (SQBool) – if true, if a runtime error occurs during the execution of the call, the vm will invoke the error handler.

  • throwerror (SQBool) – if true, the vm will thow an exception as soon as is resumed. the exception payload must be set beforehand invoking sq_thowerror().

Returns

an HRESULT.

wake up the execution a previously suspended virtual machine