11. Handling exceptions

Function: void * jit_exception_get_last (void)

Get the last exception object that occurred on this thread, or NULL if there is no exception object on this thread. As far as libjit is concerned, an exception is just a pointer. The precise meaning of the data at the pointer is determined by the front end.

Function: void * jit_exception_get_last_and_clear (void)

Get the last exception object that occurred on this thread and also clear the exception state to NULL. This combines the effect of both jit_exception_get_last and jit_exception_clear_last.

Function: void jit_exception_set_last (void *object)

Set the last exception object that occurred on this thread, so that it can be retrieved by a later call to jit_exception_get_last. This is normally used by jit_function_apply to save the exception object before returning to regular code.

Function: void jit_exception_clear_last (void)

Clear the last exception object that occurred on this thread. This is equivalent to calling jit_exception_set_last with a parameter of NULL.

Function: void jit_exception_throw (void *object)

Throw an exception object within the current thread. As far as libjit is concerned, the exception object is just a pointer. The precise meaning of the data at the pointer is determined by the front end.

Note: as an exception object works its way back up the stack, it may be temporarily stored in memory that is not normally visible to a garbage collector. The front-end is responsible for taking steps to "pin" the object so that it is uncollectable until explicitly copied back into a location that is visible to the collector once more.

Function: void jit_exception_builtin (int exception_type)

This function is called to report a builtin exception. The JIT will automatically embed calls to this function wherever a builtin exception needs to be reported.

When a builtin exception occurs, the current thread's exception handler is called to construct an appropriate object, which is then thrown.

If there is no exception handler set, or the handler returns NULL, then libjit will print an error message to stderr and cause the program to exit with a status of 1. You normally don't want this behavior and you should override it if possible.

The following builtin exception types are currently supported:

JIT_RESULT_OK

The operation was performed successfully (value is 1).

JIT_RESULT_OVERFLOW

The operation resulted in an overflow exception (value is 0).

JIT_RESULT_ARITHMETIC

The operation resulted in an arithmetic exception. i.e. an attempt was made to divide the minimum integer value by -1 (value is -1).

JIT_RESULT_DIVISION_BY_ZERO

The operation resulted in a division by zero exception (value is -2).

JIT_RESULT_COMPILE_ERROR

An error occurred when attempting to dynamically compile a function (value is -3).

JIT_RESULT_OUT_OF_MEMORY

The system ran out of memory while performing an operation (value is -4).

JIT_RESULT_NULL_REFERENCE

An attempt was made to dereference a NULL pointer (value is -5).

JIT_RESULT_NULL_FUNCTION

An attempt was made to call a function with a NULL function pointer (value is -6).

JIT_RESULT_CALLED_NESTED

An attempt was made to call a nested function from a non-nested context (value is -7).

Function: jit_exception_func jit_exception_set_handler (jit_exception_func handler)

Set the builtin exception handler for the current thread. Returns the previous exception handler.

Function: jit_exception_func jit_exception_get_handler (void)

Get the builtin exception handler for the current thread.

Function: jit_stack_trace_t jit_exception_get_stack_trace (void)

Create an object that represents the current call stack. This is normally used to indicate the location of an exception. Returns NULL if a stack trace is not available, or there is insufficient memory to create it.

Function: unsigned int jit_stack_trace_get_size (jit_stack_trace_t trace)

Get the size of a stack trace.

Function: jit_function_t jit_stack_trace_get_function (jit_context_t context, jit_stack_trace_t trace, unsigned int posn)

Get the function that is at position posn within a stack trace. Position 0 is the function that created the stack trace. If this returns NULL, then it indicates that there is a native callout at posn within the stack trace.

Function: void * jit_stack_trace_get_pc (jit_stack_trace_t trace, unsigned int posn)

Get the program counter that corresponds to position posn within a stack trace. This is the point within the function where execution had reached at the time of the trace.

Function: unsigned int jit_stack_trace_get_offset (jit_stack_trace_t trace, unsigned int posn)

Get the bytecode offset that is recorded for position posn within a stack trace. This will be JIT_NO_OFFSET if there is no bytecode offset associated with posn.

Function: void jit_stack_trace_free (jit_stack_trace_t trace)

Free the memory associated with a stack trace.

This document was generated by Klaus Treichel on May, 11 2008 using texi2html 1.78.