Exceptions

Functions
word_t	croc_eh_throw (CrocThread *t)
word_t	croc_eh_rethrow (CrocThread *t)
word_t	croc_eh_pushStd (CrocThread *t, const char *exName)
word_t	croc_eh_throwStd (CrocThread *t, const char *exName, const char *fmt,...)
word_t	croc_eh_vthrowStd (CrocThread *t, const char *exName, const char *fmt, va_list args)
word_t	croc_eh_pushLocationClass (CrocThread *t)
word_t	croc_eh_pushLocationObject (CrocThread *t, const char *file, int line, int col)
void	croc_eh_setUnhandledExHandler (CrocThread *t)

Detailed Description

Throwing exceptions, and more.

Function Documentation

word_t croc_eh_throw

(

CrocThread *

t

)

Throws the value on top of the stack as an exception.

It must be an instance to be throwable.

Returns

a dummy value (this function doesn't actually return) so that you can use it like so:

if(blah blah)
    return 1;
else
    return croc_eh_throw(t);

This can avoid having to put dummy returns in native functions that end by throwing an exception.

word_t croc_eh_rethrow

(

CrocThread *

t

)

Rethrows the value on top of the stack as an exception.

The only difference between this and croc_eh_throw is that this will not modify the exception's traceback info (if any).

You will most likely use this after catching an exception with croc_tryCall or croc_tryMethodCall, like so:

// do some stuff here which needs to be cleaned up
result = croc_tryCall(t, 3, 1);
// do some stuff here to clean up

if(result < 0)
    croc_eh_rethrow(t);

In this way, you can imitate the behavior of "finally" blocks in native code.

Returns

a dummy value like croc_eh_throw.

word_t croc_eh_pushStd	(	CrocThread *	t,
		const char *	exName
	)

Pushes one of the standard exception classes (as defined in the Croc exceptions module) onto the stack.

Parameters

exName

is the name of the class you want.

Returns

the stack index of the newly-pushed class.

word_t croc_eh_throwStd	(	CrocThread *	t,
		const char *	exName,
		const char *	fmt,
			...
	)

A convenience function for throwing one of the standard exception types.

This basically pushes the standard exception class, pushes the formatted parameters, instantiates the class, and throws the resulting instance. For example:

croc_eh_throwStd(t, "RangeError", "The value '%d' must be between 0 and 100", val);

Parameters

exName	is the name of the standard exception class that you want to throw.
fmt	is the format string. This works just like printf and will call croc_vpushFormat internally.

Returns

a dummy value like croc_eh_throw.

word_t croc_eh_vthrowStd	(	CrocThread *	t,
		const char *	exName,
		const char *	fmt,
		va_list	args
	)

Just like croc_eh_throwStd but takes a va_list instead of variadic arguments.

Returns

a dummy value like croc_eh_throw.

word_t croc_eh_pushLocationClass

(

CrocThread *

t

)

Pushes the Location class as defined in the Croc exceptions module.

Returns

the stack index of the newly-pushed class.

word_t croc_eh_pushLocationObject	(	CrocThread *	t,
		const char *	file,
		int	line,
		int	col
	)

Pushes an instance of the Location class, passing the given values to the constructor.

Parameters

file	is the location's filename.
line	is the line number, or 0 to mean a line couldn't be determined.
col	is either > 0 to mean the column number in a compiler location, or <= 0 to mean something else. The values of the CrocLocation enum can be used for this.

Returns

the stack index of the newly-pushed instance.

void croc_eh_setUnhandledExHandler

(

CrocThread *

t

)

Sets the function which will be called if an exception is thrown outside of any exception handling frame.

This can occur if an error occurs in native code outside any EH frames, such as at the top level of your program. For example, this would cause an unhandled exception:

CrocThread* t = croc_vm_openDefault();
croc_cat(t, 10); // throws an ApiError, but there is no EH frame to catch it!

When an unhandled exception occurs, all threads that were running or waiting will be dead, and the unhandled exception handler will be called on the main thread with the offending exception as its only parameter. When the unhandled exception handler returns, the C abort() function is called. If you don't want this to happen, you'll have to set your own unhandled exception handler which uses longjmp to jump somewhere else. Better yet, set up an EH frame around the top level of your code using croc_tryCall so you can handle exceptions properly.

By default there is a handler set up which simply prints out the offending exception and traceback.

This function expects the new handler function to be on top of the stack. It will set this function as the unhandled exception handler, and will replace the value on top of the stack with the previous handler.