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

ADTarm-ehast-experimentalenumforall-pointer-decayjacob/cs343-translationnew-ast-unique-exprpthread-emulationqualifiedEnum
Last change on this file since edc6ea2 was df24d37, checked in by Andrew Beach <ajbeach@…>, 3 years ago

Andrew MMath: Switch from common.tex to cfalab.sty. Still work to do but it is almost everything I had before.

  • Property mode set to 100644
File size: 31.0 KB
Line 
1\chapter{Exception Features}
2
3This chapter covers the design and user interface of the \CFA
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 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.
122
123\section{Virtuals}
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.
174
175While much of the virtual infrastructure is created, it is currently only used
176internally for exception handling. The only user-level feature is the virtual
177cast, which is the same as the \Cpp \lstinline[language=C++]|dynamic_cast|.
178\label{p:VirtualCast}
179\begin{cfa}
180(virtual TYPE)EXPRESSION
181\end{cfa}
182Note, the syntax and semantics matches a C-cast, rather than the function-like
183\Cpp syntax for special casts. Both the type of @EXPRESSION@ and @TYPE@ must be
184a pointer to a virtual type.
185The cast dynamically checks if the @EXPRESSION@ type is the same or a sub-type
186of @TYPE@, and if true, returns a pointer to the
187@EXPRESSION@ object, otherwise it returns @0p@ (null pointer).
188
189\section{Exception}
190% Leaving until later, hopefully it can talk about actual syntax instead
191% of my many strange macros. Syntax aside I will also have to talk about the
192% features all exceptions support.
193
194Exceptions are defined by the trait system; there are a series of traits, and
195if a type satisfies them, then it can be used as an exception. The following
196is the base trait all exceptions need to match.
197\begin{cfa}
198trait is_exception(exceptT &, virtualT &) {
199        virtualT const & get_exception_vtable(exceptT *);
200};
201\end{cfa}
202The trait is defined over two types, the exception type and the virtual table
203type. This should be one-to-one: each exception type has only one virtual
204table type and vice versa. The only assertion in the trait is
205@get_exception_vtable@, which takes a pointer of the exception type and
206returns a reference to the virtual table type instance.
207
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.
210The function @get_exception_vtable@ is actually a constant function.
211Regardless of the value passed in (including the null pointer) it should
212return a reference to the virtual table instance for that type.
213The reason it is a function instead of a constant is that it make type
214annotations easier to write as you can use the exception type instead of the
215virtual table type; which usually has a mangled name.
216% Also \CFA's trait system handles functions better than constants and doing
217% it this way reduce the amount of boiler plate we need.
218
219% I did have a note about how it is the programmer's responsibility to make
220% sure the function is implemented correctly. But this is true of every
221% similar system I know of (except Agda's I guess) so I took it out.
222
223There are two more traits for exceptions defined as follows:
224\begin{cfa}
225trait is_termination_exception(
226                exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
227        void defaultTerminationHandler(exceptT &);
228};
229
230trait is_resumption_exception(
231                exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
232        void defaultResumptionHandler(exceptT &);
233};
234\end{cfa}
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,
241the largest issue is that the virtual table type is mangled and not in a user
242facing way. So these three macros are provided to wrap these traits to
243simplify referring to the names:
244@IS_EXCEPTION@, @IS_TERMINATION_EXCEPTION@ and @IS_RESUMPTION_EXCEPTION@.
245
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.
248The second (optional) argument is a parenthesized list of polymorphic
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.
253
254For example consider a function that is polymorphic over types that have a
255defined arithmetic exception:
256\begin{cfa}
257forall(Num | IS_EXCEPTION(Arithmetic, (Num)))
258void some_math_function(Num & left, Num & right);
259\end{cfa}
260
261\section{Exception Handling}
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.
265This section will cover the general patterns shared by the two operations and
266then go on to cover the details each individual operation.
267
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.
273If the search fails a default handler is run and then control
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.
279
280\subsection{Termination}
281\label{s:Termination}
282Termination handling is the familiar kind and used in most programming
283languages with exception handling.
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.
289
290% (usually) Control can continue in the current function but then a different
291% control flow construct should be used.
292
293A termination raise is started with the @throw@ statement:
294\begin{cfa}
295throw EXPRESSION;
296\end{cfa}
297The expression must return a reference to a termination exception, where the
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
303change the throw's behavior (see below).
304
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,
314from callee to caller.
315At each stack frame, a check is made for resumption handlers defined by the
316@catch@ clauses of a @try@ statement.
317\begin{cfa}
318try {
319        GUARDED_BLOCK
320} catch (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
321        HANDLER_BLOCK$\(_1\)$
322} catch (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
323        HANDLER_BLOCK$\(_2\)$
324}
325\end{cfa}
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.
328
329However, while the guarded statements are being executed, including any
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
338bound to a pointer to the exception and the statements in @HANDLER_BLOCK@$_i$
339are executed. If control reaches the end of the handler, the exception is
340freed and control continues after the try statement.
341
342If no termination handler is found during the search then the default handler
343(@defaultTerminationHandler@) is run.
344Through \CFA's trait system the best match at the throw sight will be used.
345This function is run and is passed the copied exception. After the default
346handler is run control continues after the throw statement.
347
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.
354
355\subsection{Resumption}
356\label{s:Resumption}
357
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
364then the function can continue.
365
366A resumption raise is started with the @throwResume@ statement:
367\begin{cfa}
368throwResume EXPRESSION;
369\end{cfa}
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
375the exception system while handling the exception.
376
377At run-time, no exception copy is made.
378As the stack is not unwound the exception and
379any values on the stack will remain in scope while the resumption is handled.
380
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.
383At each stack frame, a check is made for resumption handlers defined by the
384@catchResume@ clauses of a @try@ statement.
385\begin{cfa}
386try {
387        GUARDED_BLOCK
388} catchResume (EXCEPTION_TYPE$\(_1\)$ * [NAME$\(_1\)$]) {
389        HANDLER_BLOCK$\(_1\)$
390} catchResume (EXCEPTION_TYPE$\(_2\)$ * [NAME$\(_2\)$]) {
391        HANDLER_BLOCK$\(_2\)$
392}
393\end{cfa}
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.
414
415Like termination, if no resumption handler is found, the default handler
416visible at the throw statement is called. It will use the best match at the
417call sight according to \CFA's overloading rules. The default handler is
418passed the exception given to the throw. When the default handler finishes
419execution continues after the raise statement.
420
421There is a global @defaultResumptionHandler@ is polymorphic over all
422termination exceptions and preforms a termination throw on the exception.
423The @defaultTerminationHandler@ for that raise is matched at the original
424raise statement (the resumption @throwResume@) and it can be customized by
425introducing a new or better match as well.
426
427\subsubsection{Resumption Marking}
428\label{s:ResumptionMarking}
429A key difference between resumption and termination is that resumption does
430not unwind the stack. A side effect that is that when a handler is matched
431and run it's try block (the guarded statements) and every try statement
432searched before it are still on the stack. This can lead to the recursive
433resumption problem.
434
435The recursive resumption problem is any situation where a resumption handler
436ends up being called while it is running.
437Consider a trivial case:
438\begin{cfa}
439try {
440        throwResume (E &){};
441} catchResume(E *) {
442        throwResume (E &){};
443}
444\end{cfa}
445When this code is executed the guarded @throwResume@ will throw, start a
446search and match the handler in the @catchResume@ clause. This will be
447call and placed on the stack on top of the try-block. The second throw then
448throws and will search the same try block and put call another instance of the
449same handler leading to an infinite loop.
450
451This situation is trivial and easy to avoid, but much more complex cycles
452can form with multiple handlers and different exception types.
453
454To prevent all of these cases we mark try statements on the stack.
455A try statement is marked when a match check is preformed with it and an
456exception. The statement will be unmarked when the handling of that exception
457is completed or the search completes without finding a handler.
458While a try statement is marked its handlers are never matched, effectify
459skipping over it to the next try statement.
460
461\begin{center}
462\input{stack-marking}
463\end{center}
464
465These rules mirror what happens with termination.
466When a termination throw happens in a handler the search will not look at
467any handlers from the original throw to the original catch because that
468part of the stack has been unwound.
469A resumption raise in the same situation wants to search the entire stack,
470but it will not try to match the exception with try statements in the section
471that would have been unwound as they are marked.
472
473The symmetry between resumption termination is why this pattern was picked.
474Other patterns, such as marking just the handlers that caught, also work but
475lack the symmetry means there are less rules to remember.
476
477\section{Conditional Catch}
478Both termination and resumption handler clauses can be given an additional
479condition to further control which exceptions they handle:
480\begin{cfa}
481catch (EXCEPTION_TYPE * [NAME] ; CONDITION)
482\end{cfa}
483First, the same semantics is used to match the exception type. Second, if the
484exception matches, @CONDITION@ is executed. The condition expression may
485reference all names in scope at the beginning of the try block and @NAME@
486introduced in the handler clause. If the condition is true, then the handler
487matches. Otherwise, the exception search continues as if the exception type
488did not match.
489
490The condition matching allows finer matching by allowing the match to check
491more kinds of information than just the exception type.
492\begin{cfa}
493try {
494        handle1 = open( f1, ... );
495        handle2 = open( f2, ... );
496        handle3 = open( f3, ... );
497        ...
498} catch( IOFailure * f ; fd( f ) == f1 ) {
499        // Only handle IO failure for f1.
500} catch( IOFailure * f ; fd( f ) == f3 ) {
501        // Only handle IO failure for f3.
502}
503// Can't handle a failure relating to f2 here.
504\end{cfa}
505In this example the file that experianced the IO error is used to decide
506which handler should be run, if any at all.
507
508\begin{comment}
509% I know I actually haven't got rid of them yet, but I'm going to try
510% to write it as if I had and see if that makes sense:
511\section{Reraising}
512\label{s:Reraising}
513Within the handler block or functions called from the handler block, it is
514possible to reraise the most recently caught exception with @throw@ or
515@throwResume@, respectively.
516\begin{cfa}
517try {
518        ...
519} catch( ... ) {
520        ... throw;
521} catchResume( ... ) {
522        ... throwResume;
523}
524\end{cfa}
525The only difference between a raise and a reraise is that reraise does not
526create a new exception; instead it continues using the current exception, \ie
527no allocation and copy. However the default handler is still set to the one
528visible at the raise point, and hence, for termination could refer to data that
529is part of an unwound stack frame. To prevent this problem, a new default
530handler is generated that does a program-level abort.
531\end{comment}
532
533\subsection{Comparison with Reraising}
534A more popular way to allow handlers to match in more detail is to reraise
535the exception after it has been caught if it could not be handled here.
536On the surface these two features seem interchangable.
537
538If we used @throw;@ to start a termination reraise then these two statements
539would have the same behaviour:
540\begin{cfa}
541try {
542    do_work_may_throw();
543} catch(exception_t * exc ; can_handle(exc)) {
544    handle(exc);
545}
546\end{cfa}
547
548\begin{cfa}
549try {
550    do_work_may_throw();
551} catch(exception_t * exc) {
552    if (can_handle(exc)) {
553        handle(exc);
554    } else {
555        throw;
556    }
557}
558\end{cfa}
559If there are further handlers after this handler only the first version will
560check them. If multiple handlers on a single try block could handle the same
561exception the translations get more complex but they are equivilantly
562powerful.
563
564Until stack unwinding comes into the picture. In termination handling, a
565conditional catch happens before the stack is unwound, but a reraise happens
566afterwards. Normally this might only cause you to loose some debug
567information you could get from a stack trace (and that can be side stepped
568entirely by collecting information during the unwind). But for \CFA there is
569another issue, if the exception isn't handled the default handler should be
570run at the site of the original raise.
571
572There are two problems with this: the site of the original raise doesn't
573exist anymore and the default handler might not exist anymore. The site will
574always be removed as part of the unwinding, often with the entirety of the
575function it was in. The default handler could be a stack allocated nested
576function removed during the unwind.
577
578This means actually trying to pretend the catch didn't happening, continuing
579the original raise instead of starting a new one, is infeasible.
580That is the expected behaviour for most languages and we can't replicate
581that behaviour.
582
583\section{Finally Clauses}
584\label{s:FinallyClauses}
585Finally clauses are used to preform unconditional clean-up when leaving a
586scope and are placed at the end of a try statement after any handler clauses:
587\begin{cfa}
588try {
589        GUARDED_BLOCK
590} ... // any number or kind of handler clauses
591... finally {
592        FINALLY_BLOCK
593}
594\end{cfa}
595The @FINALLY_BLOCK@ is executed when the try statement is removed from the
596stack, including when the @GUARDED_BLOCK@ finishes, any termination handler
597finishes or during an unwind.
598The only time the block is not executed is if the program is exited before
599the stack is unwound.
600
601Execution of the finally block should always finish, meaning control runs off
602the end of the block. This requirement ensures control always continues as if
603the finally clause is not present, \ie finally is for cleanup not changing
604control flow.
605Because of this requirement, local control flow out of the finally block
606is forbidden. The compiler precludes any @break@, @continue@, @fallthru@ or
607@return@ that causes control to leave the finally block. Other ways to leave
608the finally block, such as a long jump or termination are much harder to check,
609and at best requiring additional run-time overhead, and so are only
610discouraged.
611
612Not all languages with unwinding have finally clauses. Notably \Cpp does
613without it as descructors serve a similar role. Although destructors and
614finally clauses can be used in many of the same areas they have their own
615use cases like top-level functions and lambda functions with closures.
616Destructors take a bit more work to set up but are much easier to reuse while
617finally clauses are good for one-off uses and
618can easily include local information.
619
620\section{Cancellation}
621\label{s:Cancellation}
622Cancellation is a stack-level abort, which can be thought of as as an
623uncatchable termination. It unwinds the entire current stack, and if
624possible forwards the cancellation exception to a different stack.
625
626Cancellation is not an exception operation like termination or resumption.
627There is no special statement for starting a cancellation; instead the standard
628library function @cancel_stack@ is called passing an exception. Unlike a
629raise, this exception is not used in matching only to pass information about
630the cause of the cancellation.
631(This also means matching cannot fail so there is no default handler.)
632
633After @cancel_stack@ is called the exception is copied into the EHM's memory
634and the current stack is
635unwound. After that it depends one which stack is being cancelled.
636\begin{description}
637\item[Main Stack:]
638The main stack is the one used by the program main at the start of execution,
639and is the only stack in a sequential program.
640After the main stack is unwound there is a program-level abort.
641
642There are two reasons for this. The first is that it obviously had to do this
643in a sequential program as there is nothing else to notify and the simplicity
644of keeping the same behaviour in sequential and concurrent programs is good.
645Also, even in concurrent programs there is no stack that an innate connection
646to, so it would have be explicitly managed.
647
648\item[Thread Stack:]
649A thread stack is created for a \CFA @thread@ object or object that satisfies
650the @is_thread@ trait.
651After a thread stack is unwound there exception is stored until another
652thread attempts to join with it. Then the exception @ThreadCancelled@,
653which stores a reference to the thread and to the exception passed to the
654cancellation, is reported from the join.
655There is one difference between an explicit join (with the @join@ function)
656and an implicit join (from a destructor call). The explicit join takes the
657default handler (@defaultResumptionHandler@) from its calling context while
658the implicit join provides its own which does a program abort if the
659@ThreadCancelled@ exception cannot be handled.
660
661Communication is done at join because a thread only has to have to points of
662communication with other threads: start and join.
663Since a thread must be running to perform a cancellation (and cannot be
664cancelled from another stack), the cancellation must be after start and
665before the join. So join is the one that we will use.
666
667% TODO: Find somewhere to discuss unwind collisions.
668The difference between the explicit and implicit join is for safety and
669debugging. It helps prevent unwinding collisions by avoiding throwing from
670a destructor and prevents cascading the error across multiple threads if
671the user is not equipped to deal with it.
672Also you can always add an explicit join if that is the desired behaviour.
673
674\item[Coroutine Stack:]
675A coroutine stack is created for a @coroutine@ object or object that
676satisfies the @is_coroutine@ trait.
677After a coroutine stack is unwound control returns to the resume function
678that most recently resumed it. The resume statement reports a
679@CoroutineCancelled@ exception, which contains a references to the cancelled
680coroutine and the exception used to cancel it.
681The resume function also takes the @defaultResumptionHandler@ from the
682caller's context and passes it to the internal report.
683
684A coroutine knows of two other coroutines, its starter and its last resumer.
685The starter has a much more distant connection while the last resumer just
686(in terms of coroutine state) called resume on this coroutine, so the message
687is passed to the latter.
688\end{description}
Note: See TracBrowser for help on using the repository browser.