NAME

src/exceptions.c - Exceptions

DESCRIPTION

Define the internal interpreter exceptions.

• This is experimental code.
• The enum_class of the Exception isn't fixed.
• The interface isn't fixed.
• Much of this may change in the future.

Functions

PARROT_API PARROT_DOES_NOT_RETURN void internal_exception(int exitcode, NOTNULL(const char *format), ...)

Signal a fatal exception. This involves printing an error message to stderr, and calling Parrot_exit to invoke exit handlers and exit the process with the given exitcode. No error handlers are used, so it is not possible for Parrot bytecode to intercept a fatal error (cf. real_exception). Furthermore, no stack unwinding is done, so the exit handlers run in the current dynamic environment.

PARROT_DOES_NOT_RETURN void do_panic(NULLOK_INTERP, NULLOK(const char *message), NULLOK(const char *file), unsigned int line)

Panic handler.

PARROT_API void push_exception(PARROT_INTERP, NOTNULL(PMC *handler))

Add the exception handler on the stack.

static void run_cleanup_action(PARROT_INTERP, NOTNULL(Stack_Entry_t *e))

TODO: Not yet documented!!!

PARROT_API void Parrot_push_action(PARROT_INTERP, PMC *sub)

Push an action handler onto the dynamic environment.

PARROT_API void Parrot_push_mark(PARROT_INTERP, INTVAL mark)

Push a cleanup mark onto the dynamic environment.

PARROT_API void Parrot_pop_mark(PARROT_INTERP, INTVAL mark)

Pop items off the dynamic environment up to the mark.

PARROT_WARN_UNUSED_RESULT PARROT_CAN_RETURN_NULL static PMC *find_exception_handler(PARROT_INTERP, NOTNULL(PMC *exception))

Find the exception handler for exception.

PARROT_WARN_UNUSED_RESULT INTVAL count_exception_handlers(PARROT_INTERP)

Return the number of exception handlers on the exeception handler stack.

PARROT_WARN_UNUSED_RESULT PMC *get_exception_handler(PARROT_INTERP, INTVAL target_depth)

Return an exception handler by index into the exeception handler stack.

PARROT_WARN_UNUSED_RESULT PMC *get_all_exception_handlers(PARROT_INTERP)

Return an array of all exception handlers.

PARROT_API void pop_exception(PARROT_INTERP)

Pops the topmost exception handler off the stack.

PARROT_API PARROT_WARN_UNUSED_RESULT PMC *new_c_exception_handler(PARROT_INTERP, Parrot_exception *jb)

Generate an exception handler, that catches PASM level exceptions inside a C function. This could be a separate class too, for now just a private flag bit is set.

PARROT_API void push_new_c_exception_handler(PARROT_INTERP, Parrot_exception *jb)

Pushes an new C exception handler onto the stack.

PARROT_API PARROT_CAN_RETURN_NULL opcode_t *throw_exception(PARROT_INTERP, PMC *exception, SHIM(void *dest))

Throw the exception.

PARROT_API PARROT_WARN_UNUSED_RESULT opcode_t *rethrow_exception(PARROT_INTERP, NOTNULL(PMC *exception))

Rethrow the exception.

PARROT_DOES_NOT_RETURN void rethrow_c_exception(PARROT_INTERP)

Return back to runloop, assumes exception is still in todo (see RT#45915) and that this is called from within a handler setup with new_c_exception.

PARROT_WARN_UNUSED_RESULT static size_t dest2offset(PARROT_INTERP, NOTNULL(const opcode_t *dest))

Translate an absolute bytecode location to an offset used for resuming after an exception had occurred.

PARROT_WARN_UNUSED_RESULT static opcode_t *create_exception(PARROT_INTERP)

Create an exception.

PARROT_API size_t handle_exception(PARROT_INTERP)

Handle an exception.

PARROT_API void new_internal_exception(PARROT_INTERP)

Create a new internal exception buffer, either by allocating it or by getting one from the free list.

PARROT_API void free_internal_exception(PARROT_INTERP)

Place internal exception buffer back on the free list.

void destroy_exception_list(PARROT_INTERP)

TODO: Not yet documented!!!

void really_destroy_exception_list(NULLOK(Parrot_exception *e))

TODO: Not yet documented!!!

PARROT_API PARROT_DOES_NOT_RETURN void do_exception(PARROT_INTERP, INTVAL severity, long error)

Called from interrupt code. Does a longjmp in front of the runloop, which calls handle_exception(), returning the handler address where execution then resumes.

*/

PARROT_API PARROT_DOES_NOT_RETURN void do_exception(PARROT_INTERP, INTVAL severity, long error) { Parrot_exception * const the_exception = interp->exceptions;

    the_exception->error = error;
    the_exception->severity = severity;
    the_exception->msg = NULL;
    the_exception->resume = NULL;
    longjmp(the_exception->destination, 1);
}

/*

PARROT_API PARROT_DOES_NOT_RETURN void real_exception(PARROT_INTERP, NULLOK(void *ret_addr), int exitcode, NOTNULL(const char *format), ...)

Throws a real exception, with an error message constructed from the format string and arguments. ret_addr is the address from which to resume, if some handler decides that is appropriate, or zero to make the error non-resumable. exitcode is a exception_type_enum value.

See also internal_exception(), which signals fatal errors, and throw_exception, which calls the handler.

void Parrot_init_exceptions(PARROT_INTERP)

Create exception objects.

PARROT_API PARROT_DOES_NOT_RETURN void Parrot_confess(NOTNULL(const char *cond), NOTNULL(const char *file), unsigned int line)

A better version of assert() that gives a backtrace if possible.

void Parrot_print_backtrace(void)

TODO: Not yet documented!!!

SEE ALSO

include/parrot/exceptions.h.