VM, memory and watchdog

Creating a VM, its allocator, and the watchdog that stops a runaway script.

Virtual machine

A host may hold any number of VMs. Each one made with sq_open must be closed with sq_close. sq_newthread makes a friend VM that shares the parent's globals and registry; see Embedding Quirrel.

HSQUIRRELVM sq_open(SQInteger initialstacksize)

Creates a VM with its own execution stack, globals and registry.

HSQUIRRELVM sq_newthread(HSQUIRRELVM friendvm, SQInteger initialstacksize)

Creates a friend VM that shares the given VM's globals and registry, and pushes it as a thread object. This is what a script thread is.

void sq_seterrorhandler(HSQUIRRELVM v)

Pops a closure or native closure from the stack and sets it as the runtime error handler.

HSQOBJECT sq_geterrorhandler(HSQUIRRELVM v)

Returns a handle to the VM's current error handler.

void sq_close(HSQUIRRELVM v)

Releases a Quirrel VM and all related friend VMs.

void sq_setforeignptr(HSQUIRRELVM v, SQUserPointer p)

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.

SQUserPointer sq_getforeignptr(HSQUIRRELVM v)

Returns the foreign pointer of a VM instance.

void sq_setsharedforeignptr(HSQUIRRELVM v, SQUserPointer p)

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.

SQUserPointer sq_getsharedforeignptr(HSQUIRRELVM v)

Returns the shared foreign pointer of a group of friend VMs.

void sq_setvmreleasehook(HSQUIRRELVM v, SQRELEASEHOOK hook)

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()).

SQRELEASEHOOK sq_getvmreleasehook(HSQUIRRELVM v)

Returns the release hook of a VM instance.

void sq_setsharedreleasehook(HSQUIRRELVM v, SQRELEASEHOOK hook)

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.

SQRELEASEHOOK sq_getsharedreleasehook(HSQUIRRELVM v)

Returns the shared release hook of a group of friend VMs.

void sq_setprintfunc(HSQUIRRELVM v, SQPRINTFUNCTION printfunc, SQPRINTFUNCTION errfunc)

Sets the print function of the virtual machine. This function is used by the built-in function 'print()' to output text.

SQPRINTFUNCTION sq_getprintfunc(HSQUIRRELVM v)

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

SQPRINTFUNCTION sq_geterrorfunc(HSQUIRRELVM v)

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

SQRESULT sq_suspendvm(HSQUIRRELVM v)

Suspends the execution of the specified VM.

SQRESULT sq_wakeupvm(HSQUIRRELVM v, SQBool resumedret, SQBool retval, SQBool invoke_err_handler, SQBool throwerror)

Wake up the execution a previously suspended virtual machine.

SQInteger sq_getvmstate(HSQUIRRELVM v)

Returns the execution state of a virtual machine.

SQRESULT sq_registerbaselib(HSQUIRRELVM v)

Registers the base library into the VM's root table.

SQRESULT sq_registertypeslib(HSQUIRRELVM v)

Registers the built-in type classes, which is what gives every value its methods.

Memory allocation

The VM routes its allocations through these functions. A host with its own heap can supply one at build time and account for what the scripts use.

void *sq_malloc(SQAllocContext ctx, SQUnsignedInteger size)

Allocates through the VM's allocator.

void *sq_realloc(SQAllocContext ctx, void* p, SQUnsignedInteger oldsize, SQUnsignedInteger newsize)

Resizes a block allocated through the VM's allocator.

void sq_free(SQAllocContext ctx, void *p, SQUnsignedInteger size)

Frees a block allocated through the VM's allocator.

Watchdog

The watchdog makes an untrusted or buggy script safe to run. The interpreter loop asks the hook periodically whether it may continue, and stops the script when the answer is no. It needs no second thread.

A hook of your own outranks a timeout the script itself can move. The sandbox on this site relies on this.

SQWATCHDOGHOOK sq_set_watchdog_hook(HSQUIRRELVM v, SQWATCHDOGHOOK hook)

Installs the callback the VM asks whether the running script may continue. Returns the previous one.

void sq_kick_watchdog(HSQUIRRELVM v)

Restarts the watchdog's clock, for a native that is legitimately slow.

SQInteger sq_set_watchdog_timeout_msec(HSQUIRRELVM v, SQInteger timeout)

Sets how long a script may run before the watchdog stops it.