
@c Extracted automatically from ../jit/jit-except.c - DO NOT EDIT


@cindex jit-except.h


@deftypefun {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 @code{libjit}
is concerned, an exception is just a pointer.  The precise meaning of the
data at the pointer is determined by the front end.
@end deftypefun

@deftypefun {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 @code{jit_exception_get_last} and @code{jit_exception_clear_last}.
@end deftypefun

@deftypefun void jit_exception_set_last (void *@var{object})
Set the last exception object that occurred on this thread, so that
it can be retrieved by a later call to @code{jit_exception_get_last}.
This is normally used by @code{jit_function_apply} to save the
exception object before returning to regular code.
@end deftypefun

@deftypefun void jit_exception_clear_last (void)
Clear the last exception object that occurred on this thread.
This is equivalent to calling @code{jit_exception_set_last}
with a parameter of NULL.
@end deftypefun

@deftypefun void jit_exception_throw (void *@var{object})
Throw an exception object within the current thread.  As far as
@code{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.
@end deftypefun

@deftypefun void jit_exception_builtin (int @var{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 @code{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:

@table @code
@vindex JIT_RESULT_OK
@item JIT_RESULT_OK
The operation was performed successfully (value is 1).

@vindex JIT_RESULT_OVERFLOW
@item JIT_RESULT_OVERFLOW
The operation resulted in an overflow exception (value is 0).

@vindex JIT_RESULT_ARITHMETIC
@item 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).

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

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

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

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

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

@vindex JIT_RESULT_CALLED_NESTED
@item JIT_RESULT_CALLED_NESTED
An attempt was made to call a nested function from a non-nested context
(value is -7).
@end table
@end deftypefun

@deftypefun jit_exception_func jit_exception_set_handler (jit_exception_func @var{handler})
Set the builtin exception handler for the current thread.
Returns the previous exception handler.
@end deftypefun

@deftypefun jit_exception_func jit_exception_get_handler (void)
Get the builtin exception handler for the current thread.
@end deftypefun

@deftypefun 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.
@end deftypefun

@deftypefun {unsigned int} jit_stack_trace_get_size (jit_stack_trace_t @var{trace})
Get the size of a stack trace.
@end deftypefun

@deftypefun jit_function_t jit_stack_trace_get_function (jit_context_t @var{context}, jit_stack_trace_t @var{trace}, unsigned int @var{posn})
Get the function that is at position @var{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
@var{posn} within the stack trace.
@end deftypefun

@deftypefun {void *} jit_stack_trace_get_pc (jit_stack_trace_t @var{trace}, unsigned int @var{posn})
Get the program counter that corresponds to position @var{posn}
within a stack trace.  This is the point within the function
where execution had reached at the time of the trace.
@end deftypefun

@deftypefun {unsigned int} jit_stack_trace_get_offset (jit_stack_trace_t @var{trace}, unsigned int @var{posn})
Get the bytecode offset that is recorded for position @var{posn}
within a stack trace.  This will be @code{JIT_NO_OFFSET} if there
is no bytecode offset associated with @var{posn}.
@end deftypefun

@deftypefun void jit_stack_trace_free (jit_stack_trace_t @var{trace})
Free the memory associated with a stack trace.
@end deftypefun

