Ignore:
Timestamp:
Apr 28, 2021, 4:56:50 PM (5 years ago)
Author:
Thierry Delisle <tdelisle@…>
Branches:
ADT, arm-eh, ast-experimental, enum, forall-pointer-decay, jacob/cs343-translation, master, new-ast-unique-expr, pthread-emulation, qualifiedEnum, stuck-waitfor-destruct
Children:
8d66610
Parents:
feacef9 (diff), b7fd2db6 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'master' of plg.uwaterloo.ca:software/cfa/cfa-cc

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/theses/andrew_beach_MMath/features.tex

    rfeacef9 r5407cdc  
    22
    33This chapter covers the design and user interface of the \CFA
    4 exception-handling mechanism.
     4exception-handling mechanism (EHM). % or exception system.
     5
     6We will begin with an overview of EHMs in general. It is not a strict
     7definition of all EHMs nor an exaustive list of all possible features.
     8However it does cover the most common structure and features found in them.
     9
     10% We should cover what is an exception handling mechanism and what is an
     11% exception before this. Probably in the introduction. Some of this could
     12% move there.
     13\paragraph{Raise / Handle}
     14An exception operation has two main parts: raise and handle.
     15These terms are sometimes also known as throw and catch but this work uses
     16throw/catch as a particular kind of raise/handle.
     17These are the two parts that the user will write themselves and may
     18be the only two pieces of the EHM that have any syntax in the language.
     19
     20\subparagraph{Raise}
     21The raise is the starting point for exception handling. It marks the beginning
     22of exception handling by \newterm{raising} an excepion, which passes it to
     23the EHM.
     24
     25Some well known examples include the @throw@ statements of \Cpp and Java and
     26the \codePy{raise} statement from Python. In real systems a raise may preform
     27some other work (such as memory management) but for the purposes of this
     28overview that can be ignored.
     29
     30\subparagraph{Handle}
     31The purpose of most exception operations is to run some user code to handle
     32that exception. This code is given, with some other information, in a handler.
     33
     34A handler has three common features: the previously mentioned user code, a
     35region of code they cover and an exception label/condition that matches
     36certain exceptions.
     37Only raises inside the covered region and raising exceptions that match the
     38label can be handled by a given handler.
     39Different EHMs will have different rules to pick a handler
     40if multipe handlers could be used such as ``best match" or ``first found".
     41
     42The @try@ statements of \Cpp, Java and Python are common examples. All three
     43also show another common feature of handlers, they are grouped by the covered
     44region.
     45
     46\paragraph{Propagation}
     47After an exception is raised comes what is usually the biggest step for the
     48EHM: finding and setting up the handler. The propogation from raise to
     49handler can be broken up into three different tasks: searching for a handler,
     50matching against the handler and installing the handler.
     51
     52\subparagraph{Searching}
     53The EHM begins by searching for handlers that might be used to handle
     54the exception. Searching is usually independent of the exception that was
     55thrown as it looks for handlers that have the raise site in their covered
     56region.
     57This includes handlers in the current function, as well as any in callers
     58on the stack that have the function call in their covered region.
     59
     60\subparagraph{Matching}
     61Each handler found has to be matched with the raised exception. The exception
     62label defines a condition that be use used with exception and decides if
     63there is a match or not.
     64
     65In languages where the first match is used this step is intertwined with
     66searching, a match check is preformed immediately after the search finds
     67a possible handler.
     68
     69\subparagraph{Installing}
     70After a handler is chosen it must be made ready to run.
     71The implementation can vary widely to fit with the rest of the
     72design of the EHM. The installation step might be trivial or it could be
     73the most expensive step in handling an exception. The latter tends to be the
     74case when stack unwinding is involved.
     75
     76If a matching handler is not guarantied to be found the EHM will need a
     77different course of action here in the cases where no handler matches.
     78This is only required with unchecked exceptions as checked exceptions
     79(such as in Java) can make than guaranty.
     80This different action can also be installing a handler but it is usually an
     81implicat and much more general one.
     82
     83\subparagraph{Hierarchy}
     84A common way to organize exceptions is in a hierarchical structure.
     85This is especially true in object-orientated languages where the
     86exception hierarchy is a natural extension of the object hierarchy.
     87
     88Consider the following hierarchy of exceptions:
     89\begin{center}
     90\input{exception-hierarchy}
     91\end{center}
     92
     93A handler labelled with any given exception can handle exceptions of that
     94type or any child type of that exception. The root of the exception hierarchy
     95(here \codeC{exception}) acts as a catch-all, leaf types catch single types
     96and the exceptions in the middle can be used to catch different groups of
     97related exceptions.
     98
     99This system has some notable advantages, such as multiple levels of grouping,
     100the ability for libraries to add new exception types and the isolation
     101between different sub-hierarchies.
     102This design is used in \CFA even though it is not a object-orientated
     103language using different tools to create the hierarchy.
     104
     105% Could I cite the rational for the Python IO exception rework?
     106
     107\paragraph{Completion}
     108After the handler has finished the entire exception operation has to complete
     109and continue executing somewhere else. This step is usually simple,
     110both logically and in its implementation, as the installation of the handler
     111is usually set up to do most of the work.
     112
     113The EHM can return control to many different places,
     114the most common are after the handler definition and after the raise.
     115
     116\paragraph{Communication}
     117For effective exception handling, additional information is usually passed
     118from the raise to the handler.
     119So far only communication of the exceptions' identity has been covered.
     120A common method is putting fields into the exception instance and giving the
     121handler access to them.
    5122
    6123\section{Virtuals}
    7 Virtual types and casts are not part of the exception system nor are they
    8 required for an exception system. But an object-oriented style hierarchy is a
    9 great way of organizing exceptions so a minimal virtual system has been added
    10 to \CFA.
    11 
    12 The pattern of a simple hierarchy was borrowed from object-oriented
    13 programming was chosen for several reasons.
    14 The first is that it allows new exceptions to be added in user code
    15 and in libraries independently of each other. Another is it allows for
    16 different levels of exception grouping (all exceptions, all IO exceptions or
    17 a particular IO exception). Also it also provides a simple way of passing
    18 data back and forth across the throw.
    19 
    20 Virtual types and casts are not required for a basic exception-system but are
    21 useful for advanced exception features. However, \CFA is not object-oriented so
    22 there is no obvious concept of virtuals. Hence, to create advanced exception
    23 features for this work, I needed to design and implement a virtual-like
    24 system for \CFA.
    25 
    26 % NOTE: Maybe we should but less of the rational here.
    27 Object-oriented languages often organized exceptions into a simple hierarchy,
    28 \eg Java.
    29 \begin{center}
    30 \setlength{\unitlength}{4000sp}%
    31 \begin{picture}(1605,612)(2011,-1951)
    32 \put(2100,-1411){\vector(1, 0){225}}
    33 \put(3450,-1411){\vector(1, 0){225}}
    34 \put(3550,-1411){\line(0,-1){225}}
    35 \put(3550,-1636){\vector(1, 0){150}}
    36 \put(3550,-1636){\line(0,-1){225}}
    37 \put(3550,-1861){\vector(1, 0){150}}
    38 \put(2025,-1490){\makebox(0,0)[rb]{\LstBasicStyle{exception}}}
    39 \put(2400,-1460){\makebox(0,0)[lb]{\LstBasicStyle{arithmetic}}}
    40 \put(3750,-1460){\makebox(0,0)[lb]{\LstBasicStyle{underflow}}}
    41 \put(3750,-1690){\makebox(0,0)[lb]{\LstBasicStyle{overflow}}}
    42 \put(3750,-1920){\makebox(0,0)[lb]{\LstBasicStyle{zerodivide}}}
    43 \end{picture}%
    44 \end{center}
    45 The hierarchy provides the ability to handle an exception at different degrees
    46 of specificity (left to right). Hence, it is possible to catch a more general
    47 exception-type in higher-level code where the implementation details are
    48 unknown, which reduces tight coupling to the lower-level implementation.
    49 Otherwise, low-level code changes require higher-level code changes, \eg,
    50 changing from raising @underflow@ to @overflow@ at the low level means changing
    51 the matching catch at the high level versus catching the general @arithmetic@
    52 exception. In detail, each virtual type may have a parent and can have any
    53 number of children. A type's descendants are its children and its children's
    54 descendants. A type may not be its own descendant.
    55 
    56 The exception hierarchy allows a handler (@catch@ clause) to match multiple
    57 exceptions, \eg a base-type handler catches both base and derived
    58 exception-types.
    59 \begin{cfa}
    60 try {
    61         ...
    62 } catch(arithmetic &) {
    63         ... // handle arithmetic, underflow, overflow, zerodivide
    64 }
    65 \end{cfa}
    66 Most exception mechanisms perform a linear search of the handlers and select
    67 the first matching handler, so the order of handers is now important because
    68 matching is many to one.
    69 
    70 Each virtual type needs an associated virtual table. A virtual table is a
    71 structure with fields for all the virtual members of a type. A virtual type has
    72 all the virtual members of its parent and can add more. It may also update the
    73 values of the virtual members and often does.
     124Virtual types and casts are not part of \CFA's EHM nor are they required for
     125any EHM. But \CFA uses a hierarchial system of exceptions and this feature
     126is leveraged to create that.
     127
     128% Maybe talk about why the virtual system is so minimal.
     129% Created for but not a part of the exception system.
     130
     131The virtual system supports multiple ``trees" of types. Each tree is
     132a simple hierarchy with a single root type. Each type in a tree has exactly
     133one parent -- except for the root type which has zero parents -- and any
     134number of children.
     135Any type that belongs to any of these trees is called a virtual type.
     136
     137% A type's ancestors are its parent and its parent's ancestors.
     138% The root type has no ancestors.
     139% A type's decendents are its children and its children's decendents.
     140
     141Every virtual type also has a list of virtual members. Children inherit
     142their parent's list of virtual members but may add new members to it.
     143It is important to note that these are virtual members, not virtual methods
     144of object-orientated programming, and can be of any type.
     145However, since \CFA has function pointers and they are allowed, virtual
     146members can be used to mimic virtual methods.
     147
     148Each virtual type has a unique id.
     149This unique id and all the virtual members are combined
     150into a virtual table type. Each virtual type has a pointer to a virtual table
     151as a hidden field.
     152
     153Up until this point the virtual system is similar to ones found in
     154object-orientated languages but this where \CFA diverges. Objects encapsulate a
     155single set of behaviours in each type, universally across the entire program,
     156and indeed all programs that use that type definition. In this sense the
     157types are ``closed" and cannot be altered.
     158
     159In \CFA types do not encapsulate any behaviour. Traits are local and
     160types can begin to statify a trait, stop satifying a trait or satify the same
     161trait in a different way at any lexical location in the program.
     162In this sense they are ``open" as they can change at any time. This means it
     163is implossible to pick a single set of functions that repersent the type's
     164implementation across the program.
     165
     166\CFA side-steps this issue by not having a single virtual table for each
     167type. A user can define virtual tables which are filled in at their
     168declaration and given a name. Anywhere that name is visible, even if it was
     169defined locally inside a function (although that means it will not have a
     170static lifetime), it can be used.
     171Specifically, a virtual type is ``bound" to a virtual table which
     172sets the virtual members for that object. The virtual members can be accessed
     173through the object.
    74174
    75175While much of the virtual infrastructure is created, it is currently only used
    … …  
    83183\Cpp syntax for special casts. Both the type of @EXPRESSION@ and @TYPE@ must be
    84184a pointer to a virtual type.
    85 The cast dynamically checks if the @EXPRESSION@ type is the same or a subtype
     185The cast dynamically checks if the @EXPRESSION@ type is the same or a sub-type
    86186of @TYPE@, and if true, returns a pointer to the
    87187@EXPRESSION@ object, otherwise it returns @0p@ (null pointer).
    … …  
    101201\end{cfa}
    102202The trait is defined over two types, the exception type and the virtual table
    103 type. This should be one-to-one, each exception type has only one virtual
     203type. This should be one-to-one: each exception type has only one virtual
    104204table type and vice versa. The only assertion in the trait is
    105205@get_exception_vtable@, which takes a pointer of the exception type and
    106206returns a reference to the virtual table type instance.
    107207
     208% TODO: This section, and all references to get_exception_vtable, are
     209% out-of-data. Perhaps wait until the update is finished before rewriting it.
    108210The function @get_exception_vtable@ is actually a constant function.
    109 Recardless of the value passed in (including the null pointer) it should
     211Regardless of the value passed in (including the null pointer) it should
    110212return a reference to the virtual table instance for that type.
    111213The reason it is a function instead of a constant is that it make type
    … …  
    119221% similar system I know of (except Agda's I guess) so I took it out.
    120222
    121 There are two more traits for exceptions @is_termination_exception@ and
    122 @is_resumption_exception@. They are defined as follows:
    123 
     223There are two more traits for exceptions defined as follows:
    124224\begin{cfa}
    125225trait is_termination_exception(
    … …  
    133233};
    134234\end{cfa}
    135 
    136 In other words they make sure that a given type and virtual type is an
    137 exception and defines one of the two default handlers. These default handlers
    138 are used in the main exception handling operations \see{Exception Handling}
    139 and their use will be detailed there.
    140 
    141 However all three of these traits can be trickly to use directly.
    142 There is a bit of repetition required but
     235Both traits ensure a pair of types are an exception type and its virtual table
     236and defines one of the two default handlers. The default handlers are used
     237as fallbacks and are discussed in detail in \VRef{s:ExceptionHandling}.
     238
     239However, all three of these traits can be tricky to use directly.
     240While there is a bit of repetition required,
    143241the largest issue is that the virtual table type is mangled and not in a user
    144 facing way. So there are three macros that can be used to wrap these traits
    145 when you need to refer to the names:
     242facing way. So these three macros are provided to wrap these traits to
     243simplify referring to the names:
    146244@IS_EXCEPTION@, @IS_TERMINATION_EXCEPTION@ and @IS_RESUMPTION_EXCEPTION@.
    147245
    148 All take one or two arguments. The first argument is the name of the
    149 exception type. Its unmangled and mangled form are passed to the trait.
     246All three take one or two arguments. The first argument is the name of the
     247exception type. The macro passes its unmangled and mangled form to the trait.
    150248The second (optional) argument is a parenthesized list of polymorphic
    151 arguments. This argument should only with polymorphic exceptions and the
    152 list will be passed to both types.
    153 In the current set-up the base name and the polymorphic arguments have to
    154 match so these macros can be used without losing flexability.
     249arguments. This argument is only used with polymorphic exceptions and the
     250list is be passed to both types.
     251In the current set-up, the two types always have the same polymorphic
     252arguments so these macros can be used without losing flexibility.
    155253
    156254For example consider a function that is polymorphic over types that have a
    … …  
    162260
    163261\section{Exception Handling}
    164 \CFA provides two kinds of exception handling, termination and resumption.
    165 These twin operations are the core of the exception handling mechanism and
    166 are the reason for the features of exceptions.
     262\label{s:ExceptionHandling}
     263\CFA provides two kinds of exception handling: termination and resumption.
     264These twin operations are the core of \CFA's exception handling mechanism.
    167265This section will cover the general patterns shared by the two operations and
    168266then go on to cover the details each individual operation.
    169267
    170 Both operations follow the same set of steps to do their operation. They both
    171 start with the user preforming a throw on an exception.
    172 Then there is the search for a handler, if one is found than the exception
    173 is caught and the handler is run. After that control returns to normal
    174 execution.
    175 
     268Both operations follow the same set of steps.
     269Both start with the user preforming a raise on an exception.
     270Then the exception propogates up the stack.
     271If a handler is found the exception is caught and the handler is run.
     272After that control returns to normal execution.
    176273If the search fails a default handler is run and then control
    177 returns to normal execution immediately. That is where the default handlers
    178 @defaultTermiationHandler@ and @defaultResumptionHandler@ are used.
     274returns to normal execution after the raise.
     275
     276This general description covers what the two kinds have in common.
     277Differences include how propogation is preformed, where exception continues
     278after an exception is caught and handled and which default handler is run.
    179279
    180280\subsection{Termination}
    181281\label{s:Termination}
    182 
    183 Termination handling is more familiar kind and used in most programming
     282Termination handling is the familiar kind and used in most programming
    184283languages with exception handling.
    185 It is dynamic, non-local goto. If a throw is successful then the stack will
    186 be unwound and control will (usually) continue in a different function on
    187 the call stack. They are commonly used when an error has occured and recovery
    188 is impossible in the current function.
     284It is dynamic, non-local goto. If the raised exception is matched and
     285handled the stack is unwound and control will (usually) continue the function
     286on the call stack that defined the handler.
     287Termination is commonly used when an error has occurred and recovery is
     288impossible locally.
    189289
    190290% (usually) Control can continue in the current function but then a different
    191291% control flow construct should be used.
    192292
    193 A termination throw is started with the @throw@ statement:
     293A termination raise is started with the @throw@ statement:
    194294\begin{cfa}
    195295throw EXPRESSION;
    196296\end{cfa}
    197297The expression must return a reference to a termination exception, where the
    198 termination exception is any type that satifies @is_termination_exception@
    199 at the call site.
    200 Through \CFA's trait system the functions in the traits are passed into the
    201 throw code. A new @defaultTerminationHandler@ can be defined in any scope to
     298termination exception is any type that satisfies the trait
     299@is_termination_exception@ at the call site.
     300Through \CFA's trait system the trait functions are implicity passed into the
     301throw code and the EHM.
     302A new @defaultTerminationHandler@ can be defined in any scope to
    202303change the throw's behavior (see below).
    203304
    204 The throw will copy the provided exception into managed memory. It is the
    205 user's responcibility to ensure the original exception is cleaned up if the
    206 stack is unwound (allocating it on the stack should be sufficient).
    207 
    208 Then the exception system searches the stack using the copied exception.
    209 It starts starts from the throw and proceeds to the base of the stack,
     305The throw will copy the provided exception into managed memory to ensure
     306the exception is not destroyed if the stack is unwound.
     307It is the user's responsibility to ensure the original exception is cleaned
     308up wheither the stack is unwound or not. Allocating it on the stack is
     309usually sufficient.
     310
     311Then propogation starts with the search. \CFA uses a ``first match" rule so
     312matching is preformed with the copied exception as the search continues.
     313It starts from the throwing function and proceeds to the base of the stack,
    210314from callee to caller.
    211315At each stack frame, a check is made for resumption handlers defined by the
    … …  
    214318try {
    215319        GUARDED_BLOCK
    216 } catch (EXCEPTION_TYPE$\(_1\)$ * NAME$\(_1\)$) {
     320} catch (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
    217321        HANDLER_BLOCK$\(_1\)$
    218 } catch (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) {
     322} catch (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
    219323        HANDLER_BLOCK$\(_2\)$
    220324}
    221325\end{cfa}
    222 When viewed on its own a try statement will simply exceute the statements in
    223 @GUARDED_BLOCK@ and when those are finished the try statement finishes.
     326When viewed on its own, a try statement will simply execute the statements
     327in @GUARDED_BLOCK@ and when those are finished the try statement finishes.
    224328
    225329However, while the guarded statements are being executed, including any
    226 functions they invoke, all the handlers following the try block are now
    227 or any functions invoked from those
    228 statements, throws an exception, and the exception
    229 is not handled by a try statement further up the stack, the termination
    230 handlers are searched for a matching exception type from top to bottom.
    231 
    232 Exception matching checks the representation of the thrown exception-type is
    233 the same or a descendant type of the exception types in the handler clauses. If
    234 it is the same of a descendent of @EXCEPTION_TYPE@$_i$ then @NAME@$_i$ is
     330invoked functions, all the handlers in the statement are now on the search
     331path. If a termination exception is thrown and not handled further up the
     332stack they will be matched against the exception.
     333
     334Exception matching checks the handler in each catch clause in the order
     335they appear, top to bottom. If the representation of the thrown exception type
     336is the same or a descendant of @EXCEPTION_TYPE@$_i$ then @NAME@$_i$
     337(if provided) is
    235338bound to a pointer to the exception and the statements in @HANDLER_BLOCK@$_i$
    236339are executed. If control reaches the end of the handler, the exception is
    237340freed and control continues after the try statement.
    238341
    239 If no handler is found during the search then the default handler is run.
     342If no termination handler is found during the search then the default handler
     343(@defaultTerminationHandler@) is run.
    240344Through \CFA's trait system the best match at the throw sight will be used.
    241345This function is run and is passed the copied exception. After the default
    242346handler is run control continues after the throw statement.
    243347
    244 There is a global @defaultTerminationHandler@ that cancels the current stack
    245 with the copied exception. However it is generic over all exception types so
    246 new default handlers can be defined for different exception types and so
    247 different exception types can have different default handlers.
     348There is a global @defaultTerminationHandler@ that is polymorphic over all
     349exception types. Since it is so general a more specific handler can be
     350defined and will be used for those types, effectively overriding the handler
     351for particular exception type.
     352The global default termination handler performs a cancellation
     353\see{\VRef{s:Cancellation}} on the current stack with the copied exception.
    248354
    249355\subsection{Resumption}
    250356\label{s:Resumption}
    251357
    252 Resumption exception handling is a less common form than termination but is
    253 just as old~\cite{Goodenough75} and is in some sense simpler.
    254 It is a dynamic, non-local function call. If the throw is successful a
    255 closure will be taken from up the stack and executed, after which the throwing
    256 function will continue executing.
    257 These are most often used when an error occured and if the error is repaired
     358Resumption exception handling is less common than termination but is
     359just as old~\cite{Goodenough75} and is simpler in many ways.
     360It is a dynamic, non-local function call. If the raised exception is
     361matched a closure will be taken from up the stack and executed,
     362after which the raising function will continue executing.
     363These are most often used when an error occurred and if the error is repaired
    258364then the function can continue.
    259365
    … …  
    262368throwResume EXPRESSION;
    263369\end{cfa}
    264 The semantics of the @throwResume@ statement are like the @throw@, but the
    265 expression has return a reference a type that satifies the trait
    266 @is_resumption_exception@. The assertions from this trait are available to
     370It works much the same way as the termination throw.
     371The expression must return a reference to a resumption exception,
     372where the resumption exception is any type that satisfies the trait
     373@is_resumption_exception@ at the call site.
     374The assertions from this trait are available to
    267375the exception system while handling the exception.
    268376
    269 At runtime, no copies are made. As the stack is not unwound the exception and
     377At run-time, no exception copy is made.
     378As the stack is not unwound the exception and
    270379any values on the stack will remain in scope while the resumption is handled.
    271380
    272 Then the exception system searches the stack using the provided exception.
    273 It starts starts from the throw and proceeds to the base of the stack,
    274 from callee to caller.
     381The EHM then begins propogation. The search starts from the raise in the
     382resuming function and proceeds to the base of the stack, from callee to caller.
    275383At each stack frame, a check is made for resumption handlers defined by the
    276384@catchResume@ clauses of a @try@ statement.
    … …  
    278386try {
    279387        GUARDED_BLOCK
    280 } catchResume (EXCEPTION_TYPE$\(_1\)$ * NAME$\(_1\)$) {
     388} catchResume (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
    281389        HANDLER_BLOCK$\(_1\)$
    282 } catchResume (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) {
     390} catchResume (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
    283391        HANDLER_BLOCK$\(_2\)$
    284392}
    285393\end{cfa}
    286 If the handlers are not involved in a search this will simply execute the
    287 @GUARDED_BLOCK@ and then continue to the next statement.
    288 Its purpose is to add handlers onto the stack.
    289 (Note, termination and resumption handlers may be intermixed in a @try@
    290 statement but the kind of throw must be the same as the handler for it to be
    291 considered as a possible match.)
    292 
    293 If a search for a resumption handler reaches a try block it will check each
    294 @catchResume@ clause, top-to-bottom.
    295 At each handler if the thrown exception is or is a child type of
    296 @EXCEPTION_TYPE@$_i$ then the a pointer to the exception is bound to
    297 @NAME@$_i$ and then @HANDLER_BLOCK@$_i$ is executed. After the block is
    298 finished control will return to the @throwResume@ statement.
     394% I wonder if there would be some good central place for this.
     395Note that termination handlers and resumption handlers may be used together
     396in a single try statement, intermixing @catch@ and @catchResume@ freely.
     397Each type of handler will only interact with exceptions from the matching
     398type of raise.
     399When a try statement is executed it simply executes the statements in the
     400@GUARDED_BLOCK@ and then finishes.
     401
     402However, while the guarded statements are being executed, including any
     403invoked functions, all the handlers in the statement are now on the search
     404path. If a resumption exception is reported and not handled further up the
     405stack they will be matched against the exception.
     406
     407Exception matching checks the handler in each catch clause in the order
     408they appear, top to bottom. If the representation of the thrown exception type
     409is the same or a descendant of @EXCEPTION_TYPE@$_i$ then @NAME@$_i$
     410(if provided) is bound to a pointer to the exception and the statements in
     411@HANDLER_BLOCK@$_i$ are executed.
     412If control reaches the end of the handler, execution continues after the
     413the raise statement that raised the handled exception.
    299414
    300415Like termination, if no resumption handler is found, the default handler
    … …  
    302417call sight according to \CFA's overloading rules. The default handler is
    303418passed the exception given to the throw. When the default handler finishes
    304 execution continues after the throw statement.
     419execution continues after the raise statement.
    305420
    306421There is a global @defaultResumptionHandler@ is polymorphic over all
    307422termination exceptions and preforms a termination throw on the exception.
    308 The @defaultTerminationHandler@ for that throw is matched at the original
    309 throw statement (the resumption @throwResume@) and it can be customized by
     423The @defaultTerminationHandler@ for that raise is matched at the original
     424raise statement (the resumption @throwResume@) and it can be customized by
    310425introducing a new or better match as well.
    311426
    312 % \subsubsection?
    313 
     427\subsubsection{Resumption Marking}
    314428A key difference between resumption and termination is that resumption does
    315429not unwind the stack. A side effect that is that when a handler is matched
    … …  
    331445search and match the handler in the @catchResume@ clause. This will be
    332446call and placed on the stack on top of the try-block. The second throw then
    333 throws and will seach the same try block and put call another instance of the
     447throws and will search the same try block and put call another instance of the
    334448same handler leading to an infinite loop.
    335449
    … …  
    337451can form with multiple handlers and different exception types.
    338452
    339 To prevent all of these cases we mask sections of the stack, or equvilantly
    340 the try statements on the stack, so that the resumption seach skips over
    341 them and continues with the next unmasked section of the stack.
    342 
    343 A section of the stack is marked when it is searched to see if it contains
    344 a handler for an exception and unmarked when that exception has been handled
    345 or the search was completed without finding a handler.
    346 
    347 % This might need a diagram. But it is an important part of the justification
    348 % of the design of the traversal order.
    349 \begin{verbatim}
    350        throwResume2 ----------.
    351             |                 |
    352  generated from handler       |
    353             |                 |
    354          handler              |
    355             |                 |
    356         throwResume1 -----.   :
    357             |             |   :
    358            try            |   : search skip
    359             |             |   :
    360         catchResume  <----'   :
    361             |                 |
    362 \end{verbatim}
    363 
    364 The rules can be remembered as thinking about what would be searched in
    365 termination. So when a throw happens in a handler; a termination handler
    366 skips everything from the original throw to the original catch because that
    367 part of the stack has been unwound, a resumption handler skips the same
    368 section of stack because it has been masked.
    369 A throw in a default handler will preform the same search as the original
    370 throw because; for termination nothing has been unwound, for resumption
    371 the mask will be the same.
    372 
    373 The symmetry with termination is why this pattern was picked. Other patterns,
    374 such as marking just the handlers that caught, also work but lack the
    375 symmetry whih means there is more to remember.
     453To prevent all of these cases we mark try statements on the stack.
     454A try statement is marked when a match check is preformed with it and an
     455exception. The statement will be unmarked when the handling of that exception
     456is completed or the search completes without finding a handler.
     457While a try statement is marked its handlers are never matched, effectify
     458skipping over it to the next try statement.
     459
     460\begin{center}
     461\input{stack-marking}
     462\end{center}
     463
     464These rules mirror what happens with termination.
     465When a termination throw happens in a handler the search will not look at
     466any handlers from the original throw to the original catch because that
     467part of the stack has been unwound.
     468A resumption raise in the same situation wants to search the entire stack,
     469but it will not try to match the exception with try statements in the section
     470that would have been unwound as they are marked.
     471
     472The symmetry between resumption termination is why this pattern was picked.
     473Other patterns, such as marking just the handlers that caught, also work but
     474lack the symmetry means there are less rules to remember.
    376475
    377476\section{Conditional Catch}
    … …  
    379478condition to further control which exceptions they handle:
    380479\begin{cfa}
    381 catch (EXCEPTION_TYPE * NAME ; CONDITION)
     480catch (EXCEPTION_TYPE * [NAME] ; CONDITION)
    382481\end{cfa}
    383482First, the same semantics is used to match the exception type. Second, if the
    … …  
    387486matches. Otherwise, the exception search continues as if the exception type
    388487did not match.
    389 \begin{cfa}
    390 try {
    391         f1 = open( ... );
    392         f2 = open( ... );
     488
     489The condition matching allows finer matching by allowing the match to check
     490more kinds of information than just the exception type.
     491\begin{cfa}
     492try {
     493        handle1 = open( f1, ... );
     494        handle2 = open( f2, ... );
     495        handle3 = open( f3, ... );
    393496        ...
    394497} catch( IOFailure * f ; fd( f ) == f1 ) {
    395         // only handle IO failure for f1
    396 }
    397 \end{cfa}
    398 Note, catching @IOFailure@, checking for @f1@ in the handler, and reraising the
    399 exception if not @f1@ is different because the reraise does not examine any of
    400 remaining handlers in the current try statement.
    401 
    402 \section{Rethrowing}
    403 \colour{red}{From Andrew: I recomend we talk about why the language doesn't
    404 have rethrows/reraises instead.}
    405 
    406 \label{s:Rethrowing}
     498        // Only handle IO failure for f1.
     499} catch( IOFailure * f ; fd( f ) == f3 ) {
     500        // Only handle IO failure for f3.
     501}
     502// Can't handle a failure relating to f2 here.
     503\end{cfa}
     504In this example the file that experianced the IO error is used to decide
     505which handler should be run, if any at all.
     506
     507\begin{comment}
     508% I know I actually haven't got rid of them yet, but I'm going to try
     509% to write it as if I had and see if that makes sense:
     510\section{Reraising}
     511\label{s:Reraising}
    407512Within the handler block or functions called from the handler block, it is
    408513possible to reraise the most recently caught exception with @throw@ or
    … …  
    423528is part of an unwound stack frame. To prevent this problem, a new default
    424529handler is generated that does a program-level abort.
     530\end{comment}
     531
     532\subsection{Comparison with Reraising}
     533A more popular way to allow handlers to match in more detail is to reraise
     534the exception after it has been caught if it could not be handled here.
     535On the surface these two features seem interchangable.
     536
     537If we used @throw;@ to start a termination reraise then these two statements
     538would have the same behaviour:
     539\begin{cfa}
     540try {
     541    do_work_may_throw();
     542} catch(exception_t * exc ; can_handle(exc)) {
     543    handle(exc);
     544}
     545\end{cfa}
     546
     547\begin{cfa}
     548try {
     549    do_work_may_throw();
     550} catch(exception_t * exc) {
     551    if (can_handle(exc)) {
     552        handle(exc);
     553    } else {
     554        throw;
     555    }
     556}
     557\end{cfa}
     558If there are further handlers after this handler only the first version will
     559check them. If multiple handlers on a single try block could handle the same
     560exception the translations get more complex but they are equivilantly
     561powerful.
     562
     563Until stack unwinding comes into the picture. In termination handling, a
     564conditional catch happens before the stack is unwound, but a reraise happens
     565afterwards. Normally this might only cause you to loose some debug
     566information you could get from a stack trace (and that can be side stepped
     567entirely by collecting information during the unwind). But for \CFA there is
     568another issue, if the exception isn't handled the default handler should be
     569run at the site of the original raise.
     570
     571There are two problems with this: the site of the original raise doesn't
     572exist anymore and the default handler might not exist anymore. The site will
     573always be removed as part of the unwinding, often with the entirety of the
     574function it was in. The default handler could be a stack allocated nested
     575function removed during the unwind.
     576
     577This means actually trying to pretend the catch didn't happening, continuing
     578the original raise instead of starting a new one, is infeasible.
     579That is the expected behaviour for most languages and we can't replicate
     580that behaviour.
    425581
    426582\section{Finally Clauses}
     583\label{s:FinallyClauses}
    427584Finally clauses are used to preform unconditional clean-up when leaving a
    428 scope. They are placed at the end of a try statement:
     585scope and are placed at the end of a try statement after any handler clauses:
    429586\begin{cfa}
    430587try {
    … …  
    442599
    443600Execution of the finally block should always finish, meaning control runs off
    444 the end of the block. This requirement ensures always continues as if the
    445 finally clause is not present, \ie finally is for cleanup not changing control
    446 flow. Because of this requirement, local control flow out of the finally block
     601the end of the block. This requirement ensures control always continues as if
     602the finally clause is not present, \ie finally is for cleanup not changing
     603control flow.
     604Because of this requirement, local control flow out of the finally block
    447605is forbidden. The compiler precludes any @break@, @continue@, @fallthru@ or
    448606@return@ that causes control to leave the finally block. Other ways to leave
    449607the finally block, such as a long jump or termination are much harder to check,
    450 and at best requiring additional run-time overhead, and so are mearly
     608and at best requiring additional run-time overhead, and so are only
    451609discouraged.
    452610
    453 Not all languages with exceptions have finally clauses. Notably \Cpp does
     611Not all languages with unwinding have finally clauses. Notably \Cpp does
    454612without it as descructors serve a similar role. Although destructors and
    455613finally clauses can be used in many of the same areas they have their own
    456614use cases like top-level functions and lambda functions with closures.
    457615Destructors take a bit more work to set up but are much easier to reuse while
    458 finally clauses are good for once offs and can include local information.
     616finally clauses are good for one-off uses and
     617can easily include local information.
    459618
    460619\section{Cancellation}
     620\label{s:Cancellation}
    461621Cancellation is a stack-level abort, which can be thought of as as an
    462 uncatchable termination. It unwinds the entirety of the current stack, and if
     622uncatchable termination. It unwinds the entire current stack, and if
    463623possible forwards the cancellation exception to a different stack.
    464624
    … …  
    466626There is no special statement for starting a cancellation; instead the standard
    467627library function @cancel_stack@ is called passing an exception. Unlike a
    468 throw, this exception is not used in matching only to pass information about
     628raise, this exception is not used in matching only to pass information about
    469629the cause of the cancellation.
    470 (This also means matching cannot fail so there is no default handler either.)
    471 
    472 After @cancel_stack@ is called the exception is copied into the exception
    473 handling mechanism's memory. Then the entirety of the current stack is
     630(This also means matching cannot fail so there is no default handler.)
     631
     632After @cancel_stack@ is called the exception is copied into the EHM's memory
     633and the current stack is
    474634unwound. After that it depends one which stack is being cancelled.
    475635\begin{description}
    476636\item[Main Stack:]
    477637The main stack is the one used by the program main at the start of execution,
    478 and is the only stack in a sequential program. Even in a concurrent program
    479 the main stack is only dependent on the environment that started the program.
    480 Hence, when the main stack is cancelled there is nowhere else in the program
    481 to notify. After the stack is unwound, there is a program-level abort.
     638and is the only stack in a sequential program.
     639After the main stack is unwound there is a program-level abort.
     640
     641There are two reasons for this. The first is that it obviously had to do this
     642in a sequential program as there is nothing else to notify and the simplicity
     643of keeping the same behaviour in sequential and concurrent programs is good.
     644Also, even in concurrent programs there is no stack that an innate connection
     645to, so it would have be explicitly managed.
    482646
    483647\item[Thread Stack:]
    484 A thread stack is created for a @thread@ object or object that satisfies the
    485 @is_thread@ trait. A thread only has two points of communication that must
    486 happen: start and join. As the thread must be running to perform a
    487 cancellation, it must occur after start and before join, so join is used
    488 for communication here.
    489 After the stack is unwound, the thread halts and waits for
    490 another thread to join with it. The joining thread checks for a cancellation,
    491 and if present, resumes exception @ThreadCancelled@.
    492 
    493 There is a subtle difference between the explicit join (@join@ function) and
    494 implicit join (from a destructor call). The explicit join takes the default
    495 handler (@defaultResumptionHandler@) from its calling context, which is used if
    496 the exception is not caught. The implicit join does a program abort instead.
    497 
    498 This semantics is for safety. If an unwind is triggered while another unwind
    499 is underway only one of them can proceed as they both want to ``consume'' the
    500 stack. Letting both try to proceed leads to very undefined behaviour.
    501 Both termination and cancellation involve unwinding and, since the default
    502 @defaultResumptionHandler@ preforms a termination that could more easily
    503 happen in an implicate join inside a destructor. So there is an error message
    504 and an abort instead.
    505 \todo{Perhaps have a more general disucssion of unwind collisions before
    506 this point.}
    507 
    508 The recommended way to avoid the abort is to handle the intial resumption
    509 from the implicate join. If required you may put an explicate join inside a
    510 finally clause to disable the check and use the local
    511 @defaultResumptionHandler@ instead.
    512 
    513 \item[Coroutine Stack:] A coroutine stack is created for a @coroutine@ object
    514 or object that satisfies the @is_coroutine@ trait. A coroutine only knows of
    515 two other coroutines, its starter and its last resumer. Of the two the last
    516 resumer has the tightest coupling to the coroutine it activated and the most
    517 up-to-date information.
    518 
    519 Hence, cancellation of the active coroutine is forwarded to the last resumer
    520 after the stack is unwound. When the resumer restarts, it resumes exception
    521 @CoroutineCancelled@, which is polymorphic over the coroutine type and has a
    522 pointer to the cancelled coroutine.
    523 
    524 The resume function also has an assertion that the @defaultResumptionHandler@
    525 for the exception. So it will use the default handler like a regular throw.
     648A thread stack is created for a \CFA @thread@ object or object that satisfies
     649the @is_thread@ trait.
     650After a thread stack is unwound there exception is stored until another
     651thread attempts to join with it. Then the exception @ThreadCancelled@,
     652which stores a reference to the thread and to the exception passed to the
     653cancellation, is reported from the join.
     654There is one difference between an explicit join (with the @join@ function)
     655and an implicit join (from a destructor call). The explicit join takes the
     656default handler (@defaultResumptionHandler@) from its calling context while
     657the implicit join provides its own which does a program abort if the
     658@ThreadCancelled@ exception cannot be handled.
     659
     660Communication is done at join because a thread only has to have to points of
     661communication with other threads: start and join.
     662Since a thread must be running to perform a cancellation (and cannot be
     663cancelled from another stack), the cancellation must be after start and
     664before the join. So join is the one that we will use.
     665
     666% TODO: Find somewhere to discuss unwind collisions.
     667The difference between the explicit and implicit join is for safety and
     668debugging. It helps prevent unwinding collisions by avoiding throwing from
     669a destructor and prevents cascading the error across multiple threads if
     670the user is not equipped to deal with it.
     671Also you can always add an explicit join if that is the desired behaviour.
     672
     673\item[Coroutine Stack:]
     674A coroutine stack is created for a @coroutine@ object or object that
     675satisfies the @is_coroutine@ trait.
     676After a coroutine stack is unwound control returns to the resume function
     677that most recently resumed it. The resume statement reports a
     678@CoroutineCancelled@ exception, which contains a references to the cancelled
     679coroutine and the exception used to cancel it.
     680The resume function also takes the @defaultResumptionHandler@ from the
     681caller's context and passes it to the internal report.
     682
     683A coroutine knows of two other coroutines, its starter and its last resumer.
     684The starter has a much more distant connection while the last resumer just
     685(in terms of coroutine state) called resume on this coroutine, so the message
     686is passed to the latter.
    526687\end{description}
Note: See TracChangeset for help on using the changeset viewer.