-/* An exception is an event that can be signaled from within a
- function. This event can then be "caught" or "trapped" by the
- callers of this function. This potentially allows program flow to
- be transferred to any arbitrary code associated with a function call
- several levels up the stack.
-
- The intended use for this mechanism is for signaling "exceptional
- events" in an out-of-band fashion, hence its name. The C++ language
- (and many other OO-styled or functional languages) practically
- requires such a mechanism, as otherwise it becomes very difficult
- or even impossible to signal failure conditions in complex
- situations. The traditional C++ example is when an error occurs in
- the process of constructing an object; without such a mechanism, it
- is impossible to signal that the error occurs without adding global
- state variables and error checks around every object construction.
-
- The act of causing this event to occur is referred to as "throwing
- an exception". (Alternate terms include "raising an exception" or
- "signaling an exception".) The term "throw" is used because control
- is returned to the callers of the function that is signaling the
- exception, and thus there is the concept of "throwing" the
- exception up the call stack.
-
- [ Add updated documentation on how to use this. ] */
+/* An exception is an event that can be "thrown" from within a
+ function. This event can then be "caught" by the callers of
+ the function.
+
+ The representation of exceptions changes several times during
+ the compilation process:
+
+ In the beginning, in the front end, we have the GENERIC trees
+ TRY_CATCH_EXPR, TRY_FINALLY_EXPR, WITH_CLEANUP_EXPR,
+ CLEANUP_POINT_EXPR, CATCH_EXPR, and EH_FILTER_EXPR.
+
+ During initial gimplification (gimplify.c) these are lowered
+ to the GIMPLE_TRY, GIMPLE_CATCH, and GIMPLE_EH_FILTER nodes.
+ The WITH_CLEANUP_EXPR and CLEANUP_POINT_EXPR nodes are converted
+ into GIMPLE_TRY_FINALLY nodes; the others are a more direct 1-1
+ conversion.
+
+ During pass_lower_eh (tree-eh.c) we record the nested structure
+ of the TRY nodes in EH_REGION nodes in CFUN->EH->REGION_TREE.
+ We expand the eh_protect_cleanup_actions langhook into MUST_NOT_THROW
+ regions at this time. We can then flatten the statements within
+ the TRY nodes to straight-line code. Statements that had been within
+ TRY nodes that can throw are recorded within CFUN->EH->THROW_STMT_TABLE,
+ so that we may remember what action is supposed to be taken if
+ a given statement does throw. During this lowering process,
+ we create an EH_LANDING_PAD node for each EH_REGION that has
+ some code within the function that needs to be executed if a
+ throw does happen. We also create RESX statements that are
+ used to transfer control from an inner EH_REGION to an outer
+ EH_REGION. We also create EH_DISPATCH statements as placeholders
+ for a runtime type comparison that should be made in order to
+ select the action to perform among different CATCH and EH_FILTER
+ regions.
+
+ During pass_lower_eh_dispatch (tree-eh.c), which is run after
+ all inlining is complete, we are able to run assign_filter_values,
+ which allows us to map the set of types manipulated by all of the
+ CATCH and EH_FILTER regions to a set of integers. This set of integers
+ will be how the exception runtime communicates with the code generated
+ within the function. We then expand the GIMPLE_EH_DISPATCH statements
+ to a switch or conditional branches that use the argument provided by
+ the runtime (__builtin_eh_filter) and the set of integers we computed
+ in assign_filter_values.
+
+ During pass_lower_resx (tree-eh.c), which is run near the end
+ of optimization, we expand RESX statements. If the eh region
+ that is outer to the RESX statement is a MUST_NOT_THROW, then
+ the RESX expands to some form of abort statement. If the eh
+ region that is outer to the RESX statement is within the current
+ function, then the RESX expands to a bookkeeping call
+ (__builtin_eh_copy_values) and a goto. Otherwise, the next
+ handler for the exception must be within a function somewhere
+ up the call chain, so we call back into the exception runtime
+ (__builtin_unwind_resume).
+
+ During pass_expand (cfgexpand.c), we generate REG_EH_REGION notes
+ that create an rtl to eh_region mapping that corresponds to the
+ gimple to eh_region mapping that had been recorded in the
+ THROW_STMT_TABLE.
+
+ During pass_rtl_eh (except.c), we generate the real landing pads
+ to which the runtime will actually transfer control. These new
+ landing pads perform whatever bookkeeping is needed by the target
+ backend in order to resume execution within the current function.
+ Each of these new landing pads falls through into the post_landing_pad
+ label which had been used within the CFG up to this point. All
+ exception edges within the CFG are redirected to the new landing pads.
+ If the target uses setjmp to implement exceptions, the various extra
+ calls into the runtime to register and unregister the current stack
+ frame are emitted at this time.
+
+ During pass_convert_to_eh_region_ranges (except.c), we transform
+ the REG_EH_REGION notes attached to individual insns into
+ non-overlapping ranges of insns bounded by NOTE_INSN_EH_REGION_BEG
+ and NOTE_INSN_EH_REGION_END. Each insn within such ranges has the
+ same associated action within the exception region tree, meaning
+ that (1) the exception is caught by the same landing pad within the
+ current function, (2) the exception is blocked by the runtime with
+ a MUST_NOT_THROW region, or (3) the exception is not handled at all
+ within the current function.
+
+ Finally, during assembly generation, we call
+ output_function_exception_table (except.c) to emit the tables with
+ which the exception runtime can determine if a given stack frame
+ handles a given exception, and if so what filter value to provide
+ to the function when the non-local control transfer is effected.
+ If the target uses dwarf2 unwinding to implement exceptions, then
+ output_call_frame_info (dwarf2out.c) emits the required unwind data. */