source: doc/theses/andrew_beach_MMath/features.tex @ b041f11

Last change on this file since b041f11 was b041f11, checked in by Andrew Beach <ajbeach@…>, 2 years ago

Andrew MMath: Saved and reverting updates on the new syntax.

  • Property mode set to 100644
File size: 36.5 KB
1\chapter{Exception Features}
4This chapter covers the design and user interface of the \CFA EHM
5and begins with a general overview of EHMs. It is not a strict
6definition of all EHMs nor an exhaustive list of all possible features.
7However it does cover the most common structure and features found in them.
9\section{Overview of EHMs}
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\subsection{Raise / Handle}
14An exception operation has two main parts: raise and handle.
15These terms are sometimes 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 writes and may
18be the only two pieces of the EHM that have any syntax in a language.
21The raise is the starting point for exception handling,
22by raising an exception, which passes it to
23the EHM.
25Some well known examples include the @throw@ statements of \Cpp and Java and
26the \code{Python}{raise} statement of Python. In real systems, a raise may
27perform some other work (such as memory management) but for the
28purposes of this overview that can be ignored.
31The primary purpose of an EHM is to run some user code to handle a raised
32exception. This code is given, along with some other information,
33in a handler.
35A handler has three common features: the previously mentioned user code, a
36region of code it guards and an exception label/condition that matches
37against the raised exception.
38Only raises inside the guarded region and raising exceptions that match the
39label can be handled by a given handler.
40If multiple handlers could can handle an exception,
41EHMs define a rule to pick one, such as ``best match" or ``first found".
43The @try@ statements of \Cpp, Java and Python are common examples. All three
44also show another common feature of handlers, they are grouped by the guarded
48After an exception is raised comes what is usually the biggest step for the
49EHM: finding and setting up the handler for execution.
50The propagation from raise to
51handler can be broken up into three different tasks: searching for a handler,
52matching against the handler and installing the handler.
55The EHM begins by searching for handlers that might be used to handle
56the exception.
57The search will find handlers that have the raise site in their guarded
59The search includes handlers in the current function, as well as any in
60callers on the stack that have the function call in their guarded region.
63Each handler found is with the raised exception. The exception
64label defines a condition that is used with the exception and decides if
65there is a match or not.
67In languages where the first match is used, this step is intertwined with
68searching; a match check is performed immediately after the search finds
69a handler.
72After a handler is chosen, it must be made ready to run.
73The implementation can vary widely to fit with the rest of the
74design of the EHM. The installation step might be trivial or it could be
75the most expensive step in handling an exception. The latter tends to be the
76case when stack unwinding is involved.
78If a matching handler is not guaranteed to be found, the EHM needs a
79different course of action for this case.
80This situation only occurs with unchecked exceptions as checked exceptions
81(such as in Java) can make the guarantee.
82The unhandled action is usually very general, such as aborting the program.
85A common way to organize exceptions is in a hierarchical structure.
86This pattern comes from object-orientated languages where the
87exception hierarchy is a natural extension of the object hierarchy.
89Consider the following exception hierarchy:
93A handler labeled 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 \code{C}{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.
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; so different tools are used to create the hierarchy.
105% Could I cite the rational for the Python IO exception rework?
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.
113The EHM can return control to many different places, where
114the most common are after the handler definition (termination)
115and after the raise (resumption).
118For effective exception handling, additional information is often passed
119from the raise to the handler and back again.
120So far, only communication of the exceptions' identity is covered.
121A common communication method for adding information to an exception
122is putting fields into the exception instance
123and giving the handler access to them.
124% You can either have pointers/references in the exception, or have p/rs to
125% the exception when it doesn't have to be copied.
126Passing references or pointers allows data at the raise location to be
127updated, passing information in both directions.
131Virtual types and casts are not part of \CFA's EHM nor are they required for
132an EHM.
133However, one of the best ways to support an exception hierarchy
134is via a virtual hierarchy and dispatch system.
135Ideally, the virtual system would have been part of \CFA before the work
136on exception handling began, but unfortunately it was not.
137Hence, only the features and framework needed for the EHM were
138designed and implemented for this thesis.
139Other features were considered to ensure that
140the structure could accommodate other desirable features in the future
141but are not implemented.
142The rest of this section only discusses the implemented subset of the
143virtual system design.
145The virtual system supports multiple ``trees" of types. Each tree is
146a simple hierarchy with a single root type. Each type in a tree has exactly
147one parent -- except for the root type which has zero parents -- and any
148number of children.
149Any type that belongs to any of these trees is called a virtual type.
150% A type's ancestors are its parent and its parent's ancestors.
151% The root type has no ancestors.
152% A type's descendants are its children and its children's descendants.
154For the purposes of illistration, a proposed -- but unimplemented syntax --
155will be used. Each virtual type is repersented by a trait with an annotation
156that makes it a virtual type. This annotation is empty for a root type, which
157creates a new tree:
159trait root_type(T) virtual() {}
161The annotation may also refer to any existing virtual type to make this new
162type a child of that type and part of the same tree. The parent may itself
163be a child or a root type and may have any number of existing children.
165trait child_a(T) virtual(root_type) {}
166trait grandchild(T) virtual(child_a) {}
167trait child_b(T) virtual(root_type) {}
169\todo{Update the diagram in vtable.fig to show the new type tree.}
171Every virtual type also has a list of virtual members and a unique id,
172both are stored in a virtual table.
173Every instance of a virtual type also has a pointer to a virtual table stored
174in it, although there is no per-type virtual table as in many other languages.
176The list of virtual members is built up down the tree. Every virtual type
177inherits the list of virtual members from its parent and may add more
178virtual members to the end of the list which are passed on to its children.
179Again, using the unimplemented syntax this might look like:
181trait root_type(T) virtual() {
182        const char * to_string(T const & this);
183        unsigned int size;
186trait child_type(T) virtual(root_type) {
187        char * irrelevant_function(int, char);
190% Consider adding a diagram, but we might be good with the explanation.
192As @child_type@ is a child of @root_type@ it has the virtual members of
193@root_type@ (@to_string@ and @size@) as well as the one it declared
196It is important to note that these are virtual members, and may contain   
197arbitrary fields, functions or otherwise.
198The names ``size" and ``align" are reserved for the size and alignment of the
199virtual type, and are always automatically initialized as such.
200The other special case are uses of the trait's polymorphic argument
201(@T@ in the example), which are always updated to refer to the current
202virtual type. This allows functions that refer to to polymorphic argument
203to act as traditional virtual methods (@to_string@ in the example), as the
204object can always be passed to a virtual method in its virtual table.
206Up until this point the virtual system is similar to ones found in
207object-oriented languages but this is where \CFA diverges.
208Objects encapsulate a single set of methods in each type,
209universally across the entire program,
210and indeed all programs that use that type definition.
211The only way to change any method is to inherit and define a new type with
212its own universal implementation. In this sense,
213these object-oriented types are ``closed" and cannot be altered.
214% Because really they are class oriented.
216In \CFA, types do not encapsulate any code.
217Whether or not satisfies any given assertion, and hence any trait, is
218context sensitive. Types can begin to satisfy a trait, stop satisfying it or
219satisfy the same trait at any lexical location in the program.
220In this sense, an type's implementation in the set of functions and variables
221that allow it to satisfy a trait is ``open" and can change
222throughout the program.
223This capability means it is impossible to pick a single set of functions
224that represent a type's implementation across a program.
226\CFA side-steps this issue by not having a single virtual table for each
227type. A user can define virtual tables that are filled in at their
228declaration and given a name. Anywhere that name is visible, even if it is
229defined locally inside a function (although in this case the user must ensure
230it outlives any objects that use it), it can be used.
231Specifically, a virtual type is ``bound" to a virtual table that
232sets the virtual members for that object. The virtual members can be accessed
233through the object.
235This means virtual tables are declared and named in \CFA.
236They are declared as variables, using the type
237@vtable(VIRTUAL_TYPE)@ and any valid name. For example:
239vtable(virtual_type_name) table_name;
242Like any variable they may be forward declared with the @extern@ keyword.
243Forward declaring virtual tables is relatively common.
244Many virtual types have an ``obvious" implementation that works in most
246A pattern that has appeared in the early work using virtuals is to
247implement a virtual table with the the obvious definition and place a forward
248declaration of it in the header beside the definition of the virtual type.
250Even on the full declaration, no initializer should be used.
251Initialization is automatic.
252The type id and special virtual members ``size" and ``align" only depend on
253the virtual type, which is fixed given the type of the virtual table and
254so the compiler fills in a fixed value.
255The other virtual members are resolved, using the best match to the member's
256name and type, in the same context as the virtual table is declared using
257\CFA's normal resolution rules.
259While much of the virtual infrastructure is created, it is currently only used
260internally for exception handling. The only user-level feature is the virtual
261cast, which is the same as the \Cpp \code{C++}{dynamic_cast}.
266Note, the syntax and semantics matches a C-cast, rather than the function-like
267\Cpp syntax for special casts. Both the type of @EXPRESSION@ and @TYPE@ must be
268a pointer to a virtual type.
269The cast dynamically checks if the @EXPRESSION@ type is the same or a sub-type
270of @TYPE@, and if true, returns a pointer to the
271@EXPRESSION@ object, otherwise it returns @0p@ (null pointer).
275The syntax for declaring an exception is the same as declaring a structure
276except the keyword that is swapped out:
278exception TYPE_NAME {
279        FIELDS
283Fields are filled in the same way as a structure as well. However an extra
284field is added, this field contains the pointer to the virtual table.
285It must be explicitly initialised by the user when the exception is
288Here is an example of declaring an exception type along with a virtual table,
289assuming the exception has an ``obvious" implementation and a default
290virtual table makes sense.
295exception Example {
296        int data;
299extern vtable(Example)
300        example_base_vtable;
306vtable(Example) example_base_vtable
311%\subsection{Exception Details}
312If one is only raising and handling exceptions, that is the only interface
313that is needed. However it is actually a short hand for a more complex
314trait based interface.
316The language views exceptions through a series of traits,
317if a type satisfies them, then it can be used as an exception. The following
318is the base trait all exceptions need to match.
320trait is_exception(exceptT &, virtualT &) {
321        // Numerous imaginary assertions.
324The trait is defined over two types, the exception type and the virtual table
325type. Each exception type should have a single virtual table type.
326There are no actual assertions in this trait because the trait system
327cannot express them yet (adding such assertions would be part of
328completing the virtual system). The imaginary assertions would probably come
329from a trait defined by the virtual system, and state that the exception type
330is a virtual type, is a descendant of @exception_t@ (the base exception type)
331and allow the user to find the virtual table type.
333% I did have a note about how it is the programmer's responsibility to make
334% sure the function is implemented correctly. But this is true of every
335% similar system I know of (except Agda's I guess) so I took it out.
337There are two more traits for exceptions defined as follows:
339trait is_termination_exception(
340                exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
341        void defaultTerminationHandler(exceptT &);
344trait is_resumption_exception(
345                exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
346        void defaultResumptionHandler(exceptT &);
349Both traits ensure a pair of types are an exception type, its virtual table
351and defines one of the two default handlers. The default handlers are used
352as fallbacks and are discussed in detail in \vref{s:ExceptionHandling}.
354However, all three of these traits can be tricky to use directly.
355While there is a bit of repetition required,
356the largest issue is that the virtual table type is mangled and not in a user
357facing way. So these three macros are provided to wrap these traits to
358simplify referring to the names:
361All three take one or two arguments. The first argument is the name of the
362exception type. The macro passes its unmangled and mangled form to the trait.
363The second (optional) argument is a parenthesized list of polymorphic
364arguments. This argument is only used with polymorphic exceptions and the
365list is be passed to both types.
366In the current set-up, the two types always have the same polymorphic
367arguments so these macros can be used without losing flexibility.
369For example consider a function that is polymorphic over types that have a
370defined arithmetic exception:
372forall(Num | IS_EXCEPTION(Arithmetic, (Num)))
373void some_math_function(Num & left, Num & right);
376\section{Exception Handling}
378As stated,
379\CFA provides two kinds of exception handling: termination and resumption.
380These twin operations are the core of \CFA's exception handling mechanism.
381This section covers the general patterns shared by the two operations and
382then goes on to cover the details each individual operation.
384Both operations follow the same set of steps.
385First, a user raises an exception.
386Second, the exception propagates up the stack, searching for a handler.
387Third, if a handler is found, the exception is caught and the handler is run.
388After that control continues at a raise-dependent location.
389As an alternate to the third step,
390if a handler is not found, a default handler is run and, if it returns,
391then control
392continues after the raise.
394The differences between the two operations include how propagation is
395performed, where excecution after an exception is handler
396and which default handler is run.
400Termination handling is the familiar kind of handling
401and used in most programming
402languages with exception handling.
403It is a dynamic, non-local goto. If the raised exception is matched and
404handled, the stack is unwound and control (usually) continues in the function
405on the call stack that defined the handler.
406Termination is commonly used when an error has occurred and recovery is
407impossible locally.
409% (usually) Control can continue in the current function but then a different
410% control flow construct should be used.
412A termination raise is started with the @throw@ statement:
414throw EXPRESSION;
416The expression must return a reference to a termination exception, where the
417termination exception is any type that satisfies the trait
418@is_termination_exception@ at the call site.
419Through \CFA's trait system, the trait functions are implicitly passed into the
420throw code for use by the EHM.
421A new @defaultTerminationHandler@ can be defined in any scope to
422change the throw's behaviour when a handler is not found (see below).
424The throw copies the provided exception into managed memory to ensure
425the exception is not destroyed if the stack is unwound.
426It is the user's responsibility to ensure the original exception is cleaned
427up whether the stack is unwound or not. Allocating it on the stack is
428usually sufficient.
430% How to say propagation starts, its first sub-step is the search.
431Then propagation starts with the search. \CFA uses a ``first match" rule so
432matching is performed with the copied exception as the search key.
433It starts from the raise site and proceeds towards base of the stack,
434from callee to caller.
435At each stack frame, a check is made for termination handlers defined by the
436@catch@ clauses of a @try@ statement.
438try {
439        GUARDED_BLOCK
440} catch (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
441        HANDLER_BLOCK$\(_1\)$
442} catch (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
443        HANDLER_BLOCK$\(_2\)$
446When viewed on its own, a try statement simply executes the statements
447in the \snake{GUARDED_BLOCK} and when those are finished,
448the try statement finishes.
450However, while the guarded statements are being executed, including any
451invoked functions, all the handlers in these statements are included in the
452search path.
453Hence, if a termination exception is raised, these handlers may be matched
454against the exception and may handle it.
456Exception matching checks the handler in each catch clause in the order
457they appear, top to bottom. If the representation of the raised exception type
458is the same or a descendant of @EXCEPTION_TYPE@$_i$, then @NAME@$_i$
459(if provided) is
460bound to a pointer to the exception and the statements in @HANDLER_BLOCK@$_i$
461are executed. If control reaches the end of the handler, the exception is
462freed and control continues after the try statement.
464If no termination handler is found during the search, then the default handler
465(\defaultTerminationHandler) visible at the raise statement is called.
466Through \CFA's trait system the best match at the raise statement is used.
467This function is run and is passed the copied exception.
468If the default handler finishes, control continues after the raise statement.
470There is a global @defaultTerminationHandler@ that is polymorphic over all
471termination exception types.
472The global default termination handler performs a cancellation
473(as described in \vref{s:Cancellation})
474on the current stack with the copied exception.
475Since it is so general, a more specific handler can be defined,
476overriding the default behaviour for the specific exception types.
481Resumption exception handling is less familar form of exception handling,
482but is
483just as old~\cite{Goodenough75} and is simpler in many ways.
484It is a dynamic, non-local function call. If the raised exception is
485matched, a closure is taken from up the stack and executed,
486after which the raising function continues executing.
487The common uses for resumption exceptions include
488potentially repairable errors, where execution can continue in the same
489function once the error is corrected, and
490ignorable events, such as logging where nothing needs to happen and control
491should always continue from the raise site.
493Except for the changes to fit into that pattern, resumption exception
494handling is symmetric with termination exception handling, by design
495(see \autoref{s:Termination}).
497A resumption raise is started with the @throwResume@ statement:
499throwResume EXPRESSION;
501\todo{Decide on a final set of keywords and use them everywhere.}
502It works much the same way as the termination raise, except the
503type must satisfy the \snake{is_resumption_exception} that uses the
504default handler: \defaultResumptionHandler.
505This can be specialized for particular exception types.
507At run-time, no exception copy is made. Since
508resumption does not unwind the stack nor otherwise remove values from the
509current scope, there is no need to manage memory to keep the exception
512Then propagation starts with the search,
513following the same search path as termination,
514from the raise site to the base of stack and top of try statement to bottom.
515However, the handlers on try statements are defined by @catchResume@ clauses.
517try {
518        GUARDED_BLOCK
519} catchResume (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
520        HANDLER_BLOCK$\(_1\)$
521} catchResume (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
522        HANDLER_BLOCK$\(_2\)$
525Note that termination handlers and resumption handlers may be used together
526in a single try statement, intermixing @catch@ and @catchResume@ freely.
527Each type of handler only interacts with exceptions from the matching
528kind of raise.
529Like @catch@ clauses, @catchResume@ clauses have no effect if an exception
530is not raised.
532The matching rules are exactly the same as well.
533The first major difference here is that after
534@EXCEPTION_TYPE@$_i$ is matched and @NAME@$_i$ is bound to the exception,
535@HANDLER_BLOCK@$_i$ is executed right away without first unwinding the stack.
536After the block has finished running control jumps to the raise site, where
537the just handled exception came from, and continues executing after it,
538not after the try statement.
540\subsubsection{Resumption Marking}
542A key difference between resumption and termination is that resumption does
543not unwind the stack. A side effect is that, when a handler is matched
544and run, its try block (the guarded statements) and every try statement
545searched before it are still on the stack. There presence can lead to
546the recursive resumption problem.
547\todo{Is there a citation for the recursive resumption problem?}
549The recursive resumption problem is any situation where a resumption handler
550ends up being called while it is running.
551Consider a trivial case:
553try {
554        throwResume (E &){};
555} catchResume(E *) {
556        throwResume (E &){};
559When this code is executed, the guarded @throwResume@ starts a
560search and matches the handler in the @catchResume@ clause. This
561call is placed on the stack above the try-block.
562Now the second raise in the handler searches the same try block,
563matches again and then puts another instance of the
564same handler on the stack leading to infinite recursion.
566While this situation is trivial and easy to avoid, much more complex cycles
567can form with multiple handlers and different exception types.
568To prevent all of these cases, each try statement is ``marked" from the
569time the exception search reaches it to either when a handler completes
570handling that exception or when the search reaches the base
571of the stack.
572While a try statement is marked, its handlers are never matched, effectively
573skipping over it to the next try statement.
579There are other sets of marking rules that could be used,
580for instance, marking just the handlers that caught the exception,
581would also prevent recursive resumption.
582However, the rules selected mirrors what happens with termination,
583so this reduces the amount of rules and patterns a programmer has to know.
585The marked try statements are the ones that would be removed from
586the stack for a termination exception, \ie those on the stack
587between the handler and the raise statement.
588This symmetry applies to the default handler as well, as both kinds of
589default handlers are run at the raise statement, rather than (physically
590or logically) at the bottom of the stack.
591% In early development having the default handler happen after
592% unmarking was just more useful. We assume that will continue.
594\section{Conditional Catch}
595Both termination and resumption handler clauses can be given an additional
596condition to further control which exceptions they handle:
600First, the same semantics is used to match the exception type. Second, if the
601exception matches, @CONDITION@ is executed. The condition expression may
602reference all names in scope at the beginning of the try block and @NAME@
603introduced in the handler clause. If the condition is true, then the handler
604matches. Otherwise, the exception search continues as if the exception type
605did not match.
607The condition matching allows finer matching by checking
608more kinds of information than just the exception type.
610try {
611        handle1 = open( f1, ... );
612        handle2 = open( f2, ... );
613        handle3 = open( f3, ... );
614        ...
615} catch( IOFailure * f ; fd( f ) == f1 ) {
616        // Only handle IO failure for f1.
617} catch( IOFailure * f ; fd( f ) == f3 ) {
618        // Only handle IO failure for f3.
620// Handle a failure relating to f2 further down the stack.
622In this example the file that experienced the IO error is used to decide
623which handler should be run, if any at all.
626% I know I actually haven't got rid of them yet, but I'm going to try
627% to write it as if I had and see if that makes sense:
630Within the handler block or functions called from the handler block, it is
631possible to reraise the most recently caught exception with @throw@ or
632@throwResume@, respectively.
634try {
635        ...
636} catch( ... ) {
637        ... throw;
638} catchResume( ... ) {
639        ... throwResume;
642The only difference between a raise and a reraise is that reraise does not
643create a new exception; instead it continues using the current exception, \ie
644no allocation and copy. However the default handler is still set to the one
645visible at the raise point, and hence, for termination could refer to data that
646is part of an unwound stack frame. To prevent this problem, a new default
647handler is generated that does a program-level abort.
650\subsection{Comparison with Reraising}
651In languages without conditional catch, that is no ability to match an
652exception based on something other than its type, it can be mimicked
653by matching all exceptions of the right type, checking any additional
654conditions inside the handler and re-raising the exception if it does not
655match those.
657Here is a minimal example comparing both patterns, using @throw;@
658(no argument) to start a re-raise.
660\begin{tabular}{l r}
662try {
663    do_work_may_throw();
664} catch(exception_t * exc ;
665                can_handle(exc)) {
666    handle(exc);
674try {
675    do_work_may_throw();
676} catch(exception_t * exc) {
677    if (can_handle(exc)) {
678        handle(exc);
679    } else {
680        throw;
681    }
686At first glance catch-and-reraise may appear to just be a quality of life
687feature, but there are some significant differences between the two
690A simple difference that is more important for \CFA than many other languages
691is that the raise site changes, with a re-raise but does not with a
692conditional catch.
693This is important in \CFA because control returns to the raise site to run
694the per-site default handler. Because of this only a conditional catch can
695allow the original raise to continue.
697The more complex issue comes from the difference in how conditional
698catches and re-raises handle multiple handlers attached to a single try
699statement. A conditional catch will continue checking later handlers while
700a re-raise will skip them.
701If the different handlers could handle some of the same exceptions,
702translating a try statement that uses one to use the other can quickly
703become non-trivial:
706Original, with conditional catch:
709} catch (an_exception * e ; check_a(e)) {
710        handle_a(e);
711} catch (exception_t * e ; check_b(e)) {
712        handle_b(e);
715Translated, with re-raise:
718} catch (exception_t * e) {
719        an_exception * an_e = (virtual an_exception *)e;
720        if (an_e && check_a(an_e)) {
721                handle_a(an_e);
722        } else if (check_b(e)) {
723                handle_b(e);
724        } else {
725                throw;
726        }
729(There is a simpler solution if @handle_a@ never raises exceptions,
730using nested try statements.)
732% } catch (an_exception * e ; check_a(e)) {
733%     handle_a(e);
734% } catch (exception_t * e ; !(virtual an_exception *)e && check_b(e)) {
735%     handle_b(e);
736% }
738% } catch (an_exception * e)
739%   if (check_a(e)) {
740%     handle_a(e);
741%   } else throw;
742% } catch (exception_t * e)
743%   if (check_b(e)) {
744%     handle_b(e);
745%   } else throw;
746% }
747In similar simple examples translating from re-raise to conditional catch
748takes less code but it does not have a general trivial solution either.
750So, given that the two patterns do not trivially translate into each other,
751it becomes a matter of which on should be encouraged and made the default.
752From the premise that if a handler that could handle an exception then it
753should, it follows that checking as many handlers as possible is preferred.
754So conditional catch and checking later handlers is a good default.
756\section{Finally Clauses}
758Finally clauses are used to preform unconditional clean-up when leaving a
759scope and are placed at the end of a try statement after any handler clauses:
761try {
762        GUARDED_BLOCK
763} ... // any number or kind of handler clauses
764... finally {
765        FINALLY_BLOCK
768The @FINALLY_BLOCK@ is executed when the try statement is removed from the
769stack, including when the @GUARDED_BLOCK@ finishes, any termination handler
770finishes or during an unwind.
771The only time the block is not executed is if the program is exited before
772the stack is unwound.
774Execution of the finally block should always finish, meaning control runs off
775the end of the block. This requirement ensures control always continues as if
776the finally clause is not present, \ie finally is for cleanup not changing
777control flow.
778Because of this requirement, local control flow out of the finally block
779is forbidden. The compiler precludes any @break@, @continue@, @fallthru@ or
780@return@ that causes control to leave the finally block. Other ways to leave
781the finally block, such as a long jump or termination are much harder to check,
782and at best requiring additional run-time overhead, and so are only
785Not all languages with unwinding have finally clauses. Notably \Cpp does
786without it as destructors, and the RAII design pattern, serve a similar role.
787Although destructors and finally clauses can be used for the same cases,
788they have their own strengths, similar to top-level function and lambda
789functions with closures.
790Destructors take more work to create, but if there is clean-up code
791that needs to be run every time a type is used, they are much easier
792to set-up for each use. % It's automatic.
793On the other hand finally clauses capture the local context, so is easy to
794use when the clean-up is not dependent on the type of a variable or requires
795information from multiple variables.
799Cancellation is a stack-level abort, which can be thought of as as an
800uncatchable termination. It unwinds the entire current stack, and if
801possible forwards the cancellation exception to a different stack.
803Cancellation is not an exception operation like termination or resumption.
804There is no special statement for starting a cancellation; instead the standard
805library function @cancel_stack@ is called passing an exception. Unlike a
806raise, this exception is not used in matching only to pass information about
807the cause of the cancellation.
808Finally, as no handler is provided, there is no default handler.
810After @cancel_stack@ is called the exception is copied into the EHM's memory
811and the current stack is unwound.
812The behaviour after that depends on the kind of stack being cancelled.
814\paragraph{Main Stack}
815The main stack is the one used by the program main at the start of execution,
816and is the only stack in a sequential program.
817After the main stack is unwound there is a program-level abort.
819The first reason for this behaviour is for sequential programs where there
820is only one stack, and hence to stack to pass information to.
821Second, even in concurrent programs, the main stack has no dependency
822on another stack and no reliable way to find another living stack.
823Finally, keeping the same behaviour in both sequential and concurrent
824programs is simple and easy to understand.
826\paragraph{Thread Stack}
827A thread stack is created for a \CFA @thread@ object or object that satisfies
828the @is_thread@ trait.
829After a thread stack is unwound, the exception is stored until another
830thread attempts to join with it. Then the exception @ThreadCancelled@,
831which stores a reference to the thread and to the exception passed to the
832cancellation, is reported from the join to the joining thread.
833There is one difference between an explicit join (with the @join@ function)
834and an implicit join (from a destructor call). The explicit join takes the
835default handler (@defaultResumptionHandler@) from its calling context while
836the implicit join provides its own; which does a program abort if the
837@ThreadCancelled@ exception cannot be handled.
839The communication and synchronization are done here because threads only have
840two structural points (not dependent on user-code) where
841communication/synchronization happens: start and join.
842Since a thread must be running to perform a cancellation (and cannot be
843cancelled from another stack), the cancellation must be after start and
844before the join, so join is used.
846% TODO: Find somewhere to discuss unwind collisions.
847The difference between the explicit and implicit join is for safety and
848debugging. It helps prevent unwinding collisions by avoiding throwing from
849a destructor and prevents cascading the error across multiple threads if
850the user is not equipped to deal with it.
851It is always possible to add an explicit join if that is the desired behaviour.
853With explicit join and a default handler that triggers a cancellation, it is
854possible to cascade an error across any number of threads,
855alternating between the resumption (possibly termination) and cancellation,
856cleaning up each
857in turn, until the error is handled or the main thread is reached.
859\paragraph{Coroutine Stack}
860A coroutine stack is created for a @coroutine@ object or object that
861satisfies the @is_coroutine@ trait.
862After a coroutine stack is unwound, control returns to the @resume@ function
863that most recently resumed it. @resume@ reports a
864@CoroutineCancelled@ exception, which contains a references to the cancelled
865coroutine and the exception used to cancel it.
866The @resume@ function also takes the \defaultResumptionHandler{} from the
867caller's context and passes it to the internal report.
869A coroutine only knows of two other coroutines,
870its starter and its last resumer.
871The starter has a much more distant connection, while the last resumer just
872(in terms of coroutine state) called resume on this coroutine, so the message
873is passed to the latter.
875With a default handler that triggers a cancellation, it is possible to
876cascade an error across any number of coroutines,
877alternating between the resumption (possibly termination) and cancellation,
878cleaning up each in turn,
879until the error is handled or a thread stack is reached.
Note: See TracBrowser for help on using the repository browser.