NAME

src/exceptions.c - Exceptions

DESCRIPTION

Define the the core subsystem for exceptions.

Exception Functions

PMC *Parrot_ex_build_exception

Constructs a new exception object from the passed in arguments.

static PMC *find_exception_handler

Find the exception handler for exception.

void Parrot_ex_add_c_handler

Adds a new exception handler (defined in C) to the concurrency scheduler. Since the exception handler is C code, it stores a runloop jump point to the start of the handler code.

opcode_t *Parrot_ex_throw_from_op

Runs the exception handler.

void Parrot_ex_throw_from_c

Throws an exception object.

See also exit_fatal(), which signals fatal errors, and Parrot_ex_throw_from_op.

The 'invoke' vtable function doesn't actually execute a sub/continuation/handler, it only sets up the environment for invocation and returns the address of the start of the sub's code. That address then becomes the next op in the runloop.

Exceptions thrown from C and caught by a continuation-based handler are resumable at the level of a C instruction. When handled, they return the exception object. Any values returned from the handler to the C code that threw the exception can be stored in the exception's payload.

void Parrot_ex_throw_from_c_args

Throws an exception, with an error message constructed from a 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 Parrot_ex_throw_from_c, Parrot_ex_throw_from_op, and exit_fatal().

opcode_t *Parrot_ex_rethrow_from_op

Rethrow the exception.

void Parrot_ex_rethrow_from_c

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.

void Parrot_ex_mark_unhandled

Mark an exception as unhandled, as part of rethrowing it.

size_t Parrot_ex_calc_handler_offset

Retrieve an exception from the concurrency scheduler, prepare a call to the handler, and return the offset to the handler so it can become the next op in the runloop.

Error Functions

void Parrot_assert

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

void Parrot_confess

Prints a backtrace and message for a failed assertion.

void Parrot_print_backtrace

Displays the primrose path to disaster, (the stack frames leading up to the abort). Used by Parrot_confess.

void exit_fatal

Signal a fatal error condition. This should only be used with dire errors that cannot throw an exception (because no interpreter is available, or the nature of the error would interfere with the exception system).

This involves printing an error message to stderr, and calling exit to exit the process with the given exitcode. It is not possible for Parrot bytecode to intercept a fatal error (for that, use Parrot_ex_throw_from_c_args). exit_fatal does not call Parrot_exit to invoke exit handlers (that would require an interpreter).

void do_panic

Panic handler.

SEE ALSO

include/parrot/exceptions.h.