<commit_before># Copyright (C) 2001-2007, The Perl Foundation.
# $Id$

{{ NOTE: "rethrow", and "pushaction" are removed, and "die" is different }}
{{ TODO: enable backtrace }}

=head1 NAME

docs/pdds/pdd23_exceptions.pod - Parrot Exceptions

=head1 ABSTRACT

This document defines the requirements and implementation strategy for
Parrot's exception system.

=head1 VERSION

$Revision$

=head1 DESCRIPTION

I<Exceptions> are indications by running code that something unusual -- an
"exception" to the normal processing -- has occurred.  When code detects an
exceptional condition, it I<throws> an exception object.  Before this occurs,
code can register exception I<handlers>, which are functions (or closures)
which may (but are not obligated to) I<handle> the exception.  Some exceptions
permit continued execution immediately after the I<throw>; some don't.

Exceptions transfer control to a piece of code outside the normal flow of
control.  They are mainly used for error reporting or cleanup tasks.

(A digression on terminology: In a system analysis sense, the word "exception"
usually refers to the exceptional event that requires out-of-band handling.
However, in Parrot, "exception" also refers to the object that holds all the
information describing the exceptional condition: the nature of the exception,
the error message describing it, and other ancillary information.  The
specific type (class) of an exception object indicates its category.)

=head2 Exception Opcodes

These are the opcodes relevant to exceptions and exception handlers:

=over

=item B<push_eh I<SUB_LABEL>>

=item B<push_eh I<INVOCABLE_PMC>>

Push an invocable PMC -- usually a closure or, in rarer cases, a subroutine --
onto the exception handler stack.

If a I<SUB_LABEL> is provided, Parrot automatically performs the equivalent of
a C<newclosure> operation on the given subroutine, and pushes the resulting
closure.

When an exception is thrown, Parrot walks up the stack of active exception
handlers, invoking each one in turn, but still in the dynamic context of the
exception (i.e. the call stack is I<not> unwound first).  See below for more
detail.

=item B<pop_eh>

Pop the most recently pushed exception handler off the exception handler stack.

{{ TODO: Provide exception handler stack introspection. }}<commit_msg>[docs]: * Clarify the description of push_eh slightly.<commit_after># Copyright (C) 2001-2007, The Perl Foundation.
# $Id$

{{ NOTE: "rethrow", and "pushaction" are removed, and "die" is different }}
{{ TODO: enable backtrace }}

=head1 NAME

docs/pdds/pdd23_exceptions.pod - Parrot Exceptions

=head1 ABSTRACT

This document defines the requirements and implementation strategy for
Parrot's exception system.

=head1 VERSION

$Revision$

=head1 DESCRIPTION

I<Exceptions> are indications by running code that something unusual -- an
"exception" to the normal processing -- has occurred.  When code detects an
exceptional condition, it I<throws> an exception object.  Before this occurs,
code can register exception I<handlers>, which are functions (or closures)
which may (but are not obligated to) I<handle> the exception.  Some exceptions
permit continued execution immediately after the I<throw>; some don't.

Exceptions transfer control to a piece of code outside the normal flow of
control.  They are mainly used for error reporting or cleanup tasks.

(A digression on terminology: In a system analysis sense, the word "exception"
usually refers to the exceptional event that requires out-of-band handling.
However, in Parrot, "exception" also refers to the object that holds all the
information describing the exceptional condition: the nature of the exception,
the error message describing it, and other ancillary information.  The
specific type (class) of an exception object indicates its category.)

=head2 Exception Opcodes

These are the opcodes relevant to exceptions and exception handlers:

=over

=item B<push_eh I<LABEL>>

=item B<push_eh I<INVOCABLE_PMC>>

Push an invocable PMC -- usually a closure or, in rarer cases, a subroutine --
onto the exception handler stack.

If a I<LABEL> is provided, Parrot automatically performs the equivalent of
a C<newclosure> operation on the current subroutine, and pushes the resulting
closure.

When an exception is thrown, Parrot walks up the stack of active exception
handlers, invoking each one in turn, but still in the dynamic context of the
exception (i.e. the call stack is I<not> unwound first).  See below for more
detail.

=item B<pop_eh>

Pop the most recently pushed exception handler off the exception handler stack.

{{ TODO: Provide exception handler stack introspection. }}
{'fraction_non_alphanumeric': 0.06160120197467268, 'fraction_numerical': 0.00643915003219575, 'mean_word_length': 4.891276864728193, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2861033', 'n_tokens_mistral': 1263, 'n_tokens_neox': 1213, 'n_words': 642}