Calls and errors

Calling a script function from C, and raising and reading errors.

A call is set up on the stack: push the closure, push its this, push the arguments, then sq_call with the count. sq_call pops what it was given and pushes the result if asked for one. See Compiling and calling for the sequence.

Errors travel the same way a script throw does. A sq_throwerror from a native can be caught by a try in the script that called it. sq_getlasterror reads the value back on the C side.

SQRESULT sq_call(HSQUIRRELVM v, SQInteger params, SQBool retval, SQBool invoke_err_handler)

Calls a closure. Pops the arguments and the closure's this, and pushes the return value when retval asks for it. A VM suspended mid-call keeps both on the stack instead.

SQRESULT sq_resume(HSQUIRRELVM v, SQBool retval, SQBool invoke_err_handler)

Resumes the generator at the top position of the stack.

const char *sq_getlocal(HSQUIRRELVM v, SQUnsignedInteger level, SQUnsignedInteger idx)

Returns the name of a local in a given frame and pushes its value. Free variables are reported first, as though they sat below the real locals.

SQRESULT sq_getcallee(HSQUIRRELVM v)

Pushes onto the stack the currently running closure.

const char *sq_getfreevariable(HSQUIRRELVM v, SQInteger idx, SQUnsignedInteger nval)

Gets the value of the free variable of the closure at the position idx in the stack.

void sq_throwparamtypeerror(HSQUIRRELVM v, SQInteger nparam, SQInteger typemask, SQInteger type)

Throws the VM's own wrong-parameter-type error, so a native reports a bad argument the way the VM does.

SQRESULT sq_throwerror(HSQUIRRELVM v, const char *err)

Sets the last error in the virtual machine and returns the value that has to be returned by a native closure in order to trigger an exception in the virtual machine.

SQRESULT sq_throwobject(HSQUIRRELVM v)

Pops a value from the stack sets it as the last error in the virtual machine. Returns the value that has to be returned by a native closure in order to trigger an exception in the virtual machine (aka SQ_ERROR).

void sq_reseterror(HSQUIRRELVM v)

Reset the last error in the virtual machine to null.

void sq_getlasterror(HSQUIRRELVM v)

Pushes the last error in the stack.

SQRESULT sq_tailcall(HSQUIRRELVM v, SQInteger nparams)

Calls a closure and removes the caller function from the call stack. This function must be invoke from a native closure and he return value of sq_tailcall must be returned by the caller function(see example).