Raw object handling

Working with an HSQOBJECT handle instead of a stack slot, and reference counting.

Two different things live here. The header groups them together because both work outside the stack.

Handles. sq_getstackobj takes a handle to a value, and sq_addref / sq_release control its lifetime. This is how a host keeps a script value across frames. See Holding references from C for the sequence and its common mistakes.

Handle-direct access. The sq_obj_* family reads and writes through a handle without the stack. This saves the push and pop around a hot read.

SQRESULT sq_getstackobj(HSQUIRRELVM v, SQInteger idx, HSQOBJECT *po)

Takes a handle to the value at position idx, which can then outlive the stack slot.

void sq_pushobj(HSQUIRRELVM v, const HSQOBJECT *po)

Pushes an object handle onto the stack.

void sq_pushobject(HSQUIRRELVM v, const HSQOBJECT &o)

Pushes the value an object handle names back onto the stack.

void sq_pushobject(HSQUIRRELVM v, HSQOBJECT o)

Pushes the value an object handle names back onto the stack.

void sq_addref_refcounted(HSQUIRRELVM v, HSQOBJECT *po)

Adds a reference, assuming the object is of a reference-counted type. sq_addref checks that first.

SQBool sq_release_refcounted(HSQUIRRELVM v, HSQOBJECT *po)

Removes a reference, assuming the object is of a reference-counted type.

SQUnsignedInteger sq_getrefcount(HSQUIRRELVM v, HSQOBJECT *po)

Returns the number of references of a given object.

void sq_resetobject(HSQOBJECT *po)

Initializes an object handle. Required before the handle is used for anything else.

const char *sq_objtostring(const HSQOBJECT *o)

Returns the string value of a raw object reference.

SQBool sq_objtobool(const HSQOBJECT *o)

Returns the bool value of a raw object reference.

SQBool sq_obj_is_true(const HSQOBJECT *o)

Reports whether an object is true by the language's rules.

SQInteger sq_objtointeger(const HSQOBJECT *o)

Returns the integer value of a raw object reference.

SQFloat sq_objtofloat(const HSQOBJECT *o)

Returns the float value of a raw object reference.

SQUserPointer sq_objtouserpointer(const HSQOBJECT *o)

Returns the userpointer value of a raw object reference.

SQRESULT sq_getobjtypetag(const HSQOBJECT *o, SQUserPointer * typetag)

Gets the typetag of a raw object reference(userdata or class).

SQUnsignedInteger sq_getvmrefcount(HSQUIRRELVM v, const HSQOBJECT *po)

Returns the reference count of a VM.

const char*sq_objtypestr(SQObjectType tp)

Returns the type name of an object as a string.

SQRESULT sq_obj_get(HSQUIRRELVM v, const HSQOBJECT *obj, const HSQOBJECT *slot, HSQOBJECT *out, bool raw)

Reads a slot from an object handle without using the stack.

SQBool sq_obj_cmp(HSQUIRRELVM v, const HSQOBJECT *a, const HSQOBJECT *b, SQInteger *res)

Orders two objects, as the relational operators do.

bool sq_obj_is_equal(HSQUIRRELVM v, const HSQOBJECT *a, const HSQOBJECT *b)

Compares two objects for equality, as == does.

bool sq_fast_equal_by_value_deep(const HSQOBJECT *a, const HSQOBJECT *b, int depth)

Compares two values by content rather than by identity, following containers.

SQRESULT sq_obj_getuserdata(const HSQOBJECT *obj, SQUserPointer *p, SQUserPointer *typetag)

Returns the payload pointer of a userdata held as an object handle.

SQInteger sq_obj_getsize(const HSQOBJECT *obj)

Returns the element count of a container held as an object handle.

SQRESULT sq_obj_getinstanceup(const HSQOBJECT *obj, SQUserPointer *p, SQUserPointer typetag)

Returns the user pointer of an instance held as an object handle.

SQRESULT sq_obj_set(HSQUIRRELVM v, const HSQOBJECT *obj, const HSQOBJECT *key, const HSQOBJECT *val, bool raw)

Writes a slot of an object handle without using the stack.

SQRESULT sq_obj_newslot(HSQUIRRELVM v, const HSQOBJECT *obj, const HSQOBJECT *key, const HSQOBJECT *val, bool bstatic)

Creates a slot on an object handle without using the stack.

void sq_getregistrytableobj(HSQUIRRELVM v, HSQOBJECT *out)

Returns a handle to the registry table without going through the stack.

SQBool sq_tracevar(HSQUIRRELVM v, const HSQOBJECT * container, const HSQOBJECT * key, char * buf, int buf_size)

Records the current write to a container field, for the variable trace.

SQInteger sq_collectgarbage(HSQUIRRELVM v)

Runs the mark and sweep pass and returns how many reference cycles it freed. Nothing calls it on its own.

SQRESULT sq_resurrectunreachable(HSQUIRRELVM v)

Runs the garbage collector and pushes an array in the stack containing all unreachable object found. If no unreachable object is found, null is pushed instead. This function is meant to help debug reference cycles.

SQRESULT sq_limitthreadaccess(HSQUIRRELVM vm, int64_t tid)

Binds the VM to the calling OS thread, so a stray access from another one is caught.

bool sq_canaccessfromthisthread(HSQUIRRELVM vm)

Reports whether the calling OS thread is allowed to touch this VM.

SQAllocContext sq_getallocctx(HSQUIRRELVM v)

Returns the allocation context the VM was created with.

void sq_addref(HSQUIRRELVM v, HSQOBJECT *po)

Adds a reference to the value an object handle names, so it survives leaving the stack.

SQBool sq_release(HSQUIRRELVM v, HSQOBJECT *po)

Removes a reference added with sq_addref.