Index: doc/theses/andrew_beach_MMath/features.tex
===================================================================
--- doc/theses/andrew_beach_MMath/features.tex	(revision c6640a3f9cf4c212817d3a07110b07b9f115e5a1)
+++ doc/theses/andrew_beach_MMath/features.tex	(revision d0502a3aee721f5f4e468913c7db6c2aab56025c)
@@ -113,5 +113,5 @@
 virtual table type; which usually has a mangled name.
 % Also \CFA's trait system handles functions better than constants and doing
-% it this way
+% it this way reduce the amount of boiler plate we need.
 
 % I did have a note about how it is the programmer's responsibility to make
@@ -119,8 +119,7 @@
 % similar system I know of (except Agda's I guess) so I took it out.
 
-\section{Raise}
-\CFA provides two kinds of exception raise: termination
-\see{\VRef{s:Termination}} and resumption \see{\VRef{s:Resumption}}, which are
-specified with the following traits.
+There are two more traits for exceptions @is_termination_exception@ and
+@is_resumption_exception@. They are defined as follows:
+
 \begin{cfa}
 trait is_termination_exception(
@@ -128,10 +127,5 @@
 	void defaultTerminationHandler(exceptT &);
 };
-\end{cfa}
-The function is required to allow a termination raise, but is only called if a
-termination raise does not find an appropriate handler.
-
-Allowing a resumption raise is similar.
-\begin{cfa}
+
 trait is_resumption_exception(
 		exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
@@ -139,15 +133,24 @@
 };
 \end{cfa}
-The function is required to allow a resumption raise, but is only called if a
-resumption raise does not find an appropriate handler.
-
-Finally there are three convenience macros for referring to the these traits:
+
+In other words they make sure that a given type and virtual type is an
+exception and defines one of the two default handlers. These default handlers
+are used in the main exception handling operations \see{Exception Handling}
+and their use will be detailed there.
+
+However all three of these traits can be trickly to use directly.
+There is a bit of repetition required but
+the largest issue is that the virtual table type is mangled and not in a user
+facing way. So there are three macros that can be used to wrap these traits
+when you need to refer to the names:
 @IS_EXCEPTION@, @IS_TERMINATION_EXCEPTION@ and @IS_RESUMPTION_EXCEPTION@.
-All three traits are hard to use while naming the virtual table as it has an
-internal mangled name. These macros take the exception name as their first
-argument and do the mangling. They all take a second argument for polymorphic
-types which is the parenthesized list of polymorphic arguments. These
-arguments are passed to both the exception type and the virtual table type as
-the arguments do have to match.
+
+All take one or two arguments. The first argument is the name of the
+exception type. Its unmangled and mangled form are passed to the trait.
+The second (optional) argument is a parenthesized list of polymorphic
+arguments. This argument should only with polymorphic exceptions and the
+list will be passed to both types.
+In the current set-up the base name and the polymorphic arguments have to
+match so these macros can be used without losing flexability.
 
 For example consider a function that is polymorphic over types that have a
@@ -158,16 +161,35 @@
 \end{cfa}
 
+\section{Exception Handling}
+\CFA provides two kinds of exception handling, termination and resumption.
+These twin operations are the core of the exception handling mechanism and
+are the reason for the features of exceptions.
+This section will cover the general patterns shared by the two operations and
+then go on to cover the details each individual operation.
+
+Both operations follow the same set of steps to do their operation. They both
+start with the user preforming a throw on an exception.
+Then there is the search for a handler, if one is found than the exception
+is caught and the handler is run. After that control returns to normal
+execution.
+
+If the search fails a default handler is run and then control
+returns to normal execution immediately. That is where the default handlers
+@defaultTermiationHandler@ and @defaultResumptionHandler@ are used.
+
 \subsection{Termination}
 \label{s:Termination}
 
-Termination raise, called ``throw'', is familiar and used in most programming
-languages with exception handling. The semantics of termination is: search the
-stack for a matching handler, unwind the stack frames to the matching handler,
-execute the handler, and continue execution after the handler. Termination is
-used when execution \emph{cannot} return to the throw. To continue execution,
-the program must \emph{recover} in the handler from the failed (unwound)
-execution at the raise to safely proceed after the handler.
-
-A termination raise is started with the @throw@ statement:
+Termination handling is more familiar kind and used in most programming
+languages with exception handling.
+It is dynamic, non-local goto. If a throw is successful then the stack will
+be unwound and control will (usually) continue in a different function on
+the call stack. They are commonly used when an error has occured and recovery
+is impossible in the current function.
+
+% (usually) Control can continue in the current function but then a different
+% control flow construct should be used.
+
+A termination throw is started with the @throw@ statement:
 \begin{cfa}
 throw EXPRESSION;
@@ -180,25 +202,29 @@
 change the throw's behavior (see below).
 
-At runtime, the exception returned by the expression
-is copied into managed memory (heap) to ensure it remains in
-scope during unwinding. It is the user's responsibility to ensure the original
-exception object at the throw is freed when it goes out of scope. Being
-allocated on the stack is sufficient for this.
-
-Then the exception system searches the stack starting from the throw and
-proceeding towards the base of the stack, from callee to caller. At each stack
-frame, a check is made for termination handlers defined by the @catch@ clauses
-of a @try@ statement.
+The throw will copy the provided exception into managed memory. It is the
+user's responcibility to ensure the original exception is cleaned up if the
+stack is unwound (allocating it on the stack should be sufficient).
+
+Then the exception system searches the stack using the copied exception.
+It starts starts from the throw and proceeds to the base of the stack,
+from callee to caller.
+At each stack frame, a check is made for resumption handlers defined by the
+@catch@ clauses of a @try@ statement.
 \begin{cfa}
 try {
 	GUARDED_BLOCK
-} catch (EXCEPTION_TYPE$\(_1\)$ * NAME$\(_1\)$) { // termination handler 1
+} catch (EXCEPTION_TYPE$\(_1\)$ * NAME$\(_1\)$) {
 	HANDLER_BLOCK$\(_1\)$
-} catch (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) { // termination handler 2
+} catch (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) {
 	HANDLER_BLOCK$\(_2\)$
 }
 \end{cfa}
-The statements in the @GUARDED_BLOCK@ are executed. If those statements, or any
-functions invoked from those statements, throws an exception, and the exception
+When viewed on its own a try statement will simply exceute the statements in
+@GUARDED_BLOCK@ and when those are finished the try statement finishes.
+
+However, while the guarded statements are being executed, including any
+functions they invoke, all the handlers following the try block are now
+or any functions invoked from those
+statements, throws an exception, and the exception
 is not handled by a try statement further up the stack, the termination
 handlers are searched for a matching exception type from top to bottom.
@@ -211,26 +237,24 @@
 freed and control continues after the try statement.
 
-The default handler visible at the throw statement is used if no matching
-termination handler is found after the entire stack is searched. At that point,
-the default handler is called with a reference to the exception object
-generated at the throw. If the default handler returns, control continues
-from after the throw statement. This feature allows
-each exception type to define its own action, such as printing an informative
-error message, when an exception is not handled in the program.
-However the default handler for all exception types triggers a cancellation
-using the exception.
+If no handler is found during the search then the default handler is run.
+Through \CFA's trait system the best match at the throw sight will be used.
+This function is run and is passed the copied exception. After the default
+handler is run control continues after the throw statement.
+
+There is a global @defaultTerminationHandler@ that cancels the current stack
+with the copied exception. However it is generic over all exception types so
+new default handlers can be defined for different exception types and so
+different exception types can have different default handlers.
 
 \subsection{Resumption}
 \label{s:Resumption}
 
-Resumption raise, called ``resume'', is as old as termination
-raise~\cite{Goodenough75} but is less popular. In many ways, resumption is
-simpler and easier to understand, as it is simply a dynamic call.
-The semantics of resumption is: search the stack for a matching handler,
-execute the handler, and continue execution after the resume. Notice, the stack
-cannot be unwound because execution returns to the raise point. Resumption is
-used used when execution \emph{can} return to the resume. To continue
-execution, the program must \emph{correct} in the handler for the failed
-execution at the raise so execution can safely continue after the resume.
+Resumption exception handling is a less common form than termination but is
+just as old~\cite{Goodenough75} and is in some sense simpler.
+It is a dynamic, non-local function call. If the throw is successful a
+closure will be taken from up the stack and executed, after which the throwing
+function will continue executing.
+These are most often used when an error occured and if the error is repaired
+then the function can continue.
 
 A resumption raise is started with the @throwResume@ statement:
@@ -240,14 +264,15 @@
 The semantics of the @throwResume@ statement are like the @throw@, but the
 expression has return a reference a type that satifies the trait
-@is_resumption_exception@. Like with termination the exception system can
-use these assertions while (throwing/raising/handling) the exception.
+@is_resumption_exception@. The assertions from this trait are available to
+the exception system while handling the exception.
 
 At runtime, no copies are made. As the stack is not unwound the exception and
 any values on the stack will remain in scope while the resumption is handled.
 
-Then the exception system searches the stack starting from the resume and
-proceeding to the base of the stack, from callee to caller. At each stack
-frame, a check is made for resumption handlers defined by the @catchResume@
-clauses of a @try@ statement.
+Then the exception system searches the stack using the provided exception.
+It starts starts from the throw and proceeds to the base of the stack,
+from callee to caller.
+At each stack frame, a check is made for resumption handlers defined by the
+@catchResume@ clauses of a @try@ statement.
 \begin{cfa}
 try {
@@ -259,33 +284,64 @@
 }
 \end{cfa}
-The statements in the @GUARDED_BLOCK@ are executed. If those statements, or any
-functions invoked from those statements, resumes an exception, and the
-exception is not handled by a try statement further up the stack, the
-resumption handlers are searched for a matching exception type from top to
-bottom. (Note, termination and resumption handlers may be intermixed in a @try@
-statement but the kind of raise (throw/resume) only matches with the
-corresponding kind of handler clause.)
-
-The exception search and matching for resumption is the same as for
-termination, including exception inheritance. The difference is when control
-reaches the end of the handler: the resumption handler returns after the resume
-rather than after the try statement. The resume point assumes the handler has
-corrected the problem so execution can safely continue.
+If the handlers are not involved in a search this will simply execute the
+@GUARDED_BLOCK@ and then continue to the next statement.
+Its purpose is to add handlers onto the stack.
+(Note, termination and resumption handlers may be intermixed in a @try@
+statement but the kind of throw must be the same as the handler for it to be
+considered as a possible match.)
+
+If a search for a resumption handler reaches a try block it will check each
+@catchResume@ clause, top-to-bottom.
+At each handler if the thrown exception is or is a child type of
+@EXCEPTION_TYPE@$_i$ then the a pointer to the exception is bound to
+@NAME@$_i$ and then @HANDLER_BLOCK@$_i$ is executed. After the block is
+finished control will return to the @throwResume@ statement.
 
 Like termination, if no resumption handler is found, the default handler
-visible at the resume statement is called, and the system default action is
-executed.
-
-For resumption, the exception system uses stack marking to partition the
-resumption search. If another resumption exception is raised in a resumption
-handler, the second exception search does not start at the point of the
-original raise. (Remember the stack is not unwound and the current handler is
-at the top of the stack.) The search for the second resumption starts at the
-current point on the stack because new try statements may have been pushed by
-the handler or functions called from the handler. If there is no match back to
-the point of the current handler, the search skips\label{p:searchskip} the
-stack frames already searched by the first resume and continues after
-the try statement. The default handler always continues from default
-handler associated with the point where the exception is created.
+visible at the throw statement is called. It will use the best match at the
+call sight according to \CFA's overloading rules. The default handler is
+passed the exception given to the throw. When the default handler finishes
+execution continues after the throw statement.
+
+There is a global @defaultResumptionHandler@ is polymorphic over all
+termination exceptions and preforms a termination throw on the exception.
+The @defaultTerminationHandler@ for that throw is matched at the original
+throw statement (the resumption @throwResume@) and it can be customized by
+introducing a new or better match as well.
+
+% \subsubsection?
+
+A key difference between resumption and termination is that resumption does
+not unwind the stack. A side effect that is that when a handler is matched
+and run it's try block (the guarded statements) and every try statement
+searched before it are still on the stack. This can lead to the recursive
+resumption problem.
+
+The recursive resumption problem is any situation where a resumption handler
+ends up being called while it is running.
+Consider a trivial case:
+\begin{cfa}
+try {
+	throwResume (E &){};
+} catchResume(E *) {
+	throwResume (E &){};
+}
+\end{cfa}
+When this code is executed the guarded @throwResume@ will throw, start a
+search and match the handler in the @catchResume@ clause. This will be
+call and placed on the stack on top of the try-block. The second throw then
+throws and will seach the same try block and put call another instance of the
+same handler leading to an infinite loop.
+
+This situation is trivial and easy to avoid, but much more complex cycles
+can form with multiple handlers and different exception types.
+
+To prevent all of these cases we mask sections of the stack, or equvilantly
+the try statements on the stack, so that the resumption seach skips over
+them and continues with the next unmasked section of the stack.
+
+A section of the stack is marked when it is searched to see if it contains
+a handler for an exception and unmarked when that exception has been handled
+or the search was completed without finding a handler.
 
 % This might need a diagram. But it is an important part of the justification
@@ -306,28 +362,16 @@
 \end{verbatim}
 
-This resumption search pattern reflects the one for termination, and so
-should come naturally to most programmers.
-However, it avoids the \emph{recursive resumption} problem.
-If parts of the stack are searched multiple times, loops
-can easily form resulting in infinite recursion.
-
-Consider the trivial case:
-\begin{cfa}
-try {
-	throwResume (E &){}; // first
-} catchResume(E *) {
-	throwResume (E &){}; // second
-}
-\end{cfa}
-If this handler is ever used it will be placed on top of the stack above the
-try statement. If the stack was not masked than the @throwResume@ in the
-handler would always be caught by the handler, leading to an infinite loop.
-Masking avoids this problem and other more complex versions of it involving
-multiple handlers and exception types.
-
-Other masking stratagies could be used; such as masking the handlers that
-have caught an exception. This one was choosen because it creates a symmetry
-with termination (masked sections of the stack would be unwound with
-termination) and having only one pattern to learn is easier.
+The rules can be remembered as thinking about what would be searched in
+termination. So when a throw happens in a handler; a termination handler
+skips everything from the original throw to the original catch because that
+part of the stack has been unwound, a resumption handler skips the same
+section of stack because it has been masked.
+A throw in a default handler will preform the same search as the original
+throw because; for termination nothing has been unwound, for resumption
+the mask will be the same.
+
+The symmetry with termination is why this pattern was picked. Other patterns,
+such as marking just the handlers that caught, also work but lack the
+symmetry whih means there is more to remember.
 
 \section{Conditional Catch}
@@ -335,5 +379,5 @@
 condition to further control which exceptions they handle:
 \begin{cfa}
-catch (EXCEPTION_TYPE * NAME ; @CONDITION@)
+catch (EXCEPTION_TYPE * NAME ; CONDITION)
 \end{cfa}
 First, the same semantics is used to match the exception type. Second, if the
@@ -341,6 +385,6 @@
 reference all names in scope at the beginning of the try block and @NAME@
 introduced in the handler clause. If the condition is true, then the handler
-matches. Otherwise, the exception search continues at the next appropriate kind
-of handler clause in the try block.
+matches. Otherwise, the exception search continues as if the exception type
+did not match.
 \begin{cfa}
 try {
@@ -356,19 +400,19 @@
 remaining handlers in the current try statement.
 
-\section{Reraise}
-\color{red}{From Andrew: I recomend we talk about why the language doesn't
+\section{Rethrowing}
+\colour{red}{From Andrew: I recomend we talk about why the language doesn't
 have rethrows/reraises instead.}
 
-\label{s:Reraise}
+\label{s:Rethrowing}
 Within the handler block or functions called from the handler block, it is
 possible to reraise the most recently caught exception with @throw@ or
-@throwResume@, respective.
+@throwResume@, respectively.
 \begin{cfa}
 try {
 	...
 } catch( ... ) {
-	... throw; // rethrow
+	... throw;
 } catchResume( ... ) {
-	... throwResume; // reresume
+	... throwResume;
 }
 \end{cfa}
@@ -381,5 +425,6 @@
 
 \section{Finally Clauses}
-A @finally@ clause may be placed at the end of a @try@ statement.
+Finally clauses are used to preform unconditional clean-up when leaving a
+scope. They are placed at the end of a try statement:
 \begin{cfa}
 try {
@@ -391,8 +436,8 @@
 \end{cfa}
 The @FINALLY_BLOCK@ is executed when the try statement is removed from the
-stack, including when the @GUARDED_BLOCK@ or any handler clause finishes or
-during an unwind.
+stack, including when the @GUARDED_BLOCK@ finishes, any termination handler
+finishes or during an unwind.
 The only time the block is not executed is if the program is exited before
-that happens.
+the stack is unwound.
 
 Execution of the finally block should always finish, meaning control runs off
@@ -403,5 +448,13 @@
 @return@ that causes control to leave the finally block. Other ways to leave
 the finally block, such as a long jump or termination are much harder to check,
-and at best requiring additional run-time overhead, and so are discouraged.
+and at best requiring additional run-time overhead, and so are mearly
+discouraged.
+
+Not all languages with exceptions have finally clauses. Notably \Cpp does
+without it as descructors serve a similar role. Although destructors and
+finally clauses can be used in many of the same areas they have their own
+use cases like top-level functions and lambda functions with closures.
+Destructors take a bit more work to set up but are much easier to reuse while
+finally clauses are good for once offs and can include local information.
 
 \section{Cancellation}
@@ -413,8 +466,11 @@
 There is no special statement for starting a cancellation; instead the standard
 library function @cancel_stack@ is called passing an exception. Unlike a
-raise, this exception is not used in matching only to pass information about
+throw, this exception is not used in matching only to pass information about
 the cause of the cancellation.
-
-Handling of a cancellation depends on which stack is being cancelled.
+(This also means matching cannot fail so there is no default handler either.)
+
+After @cancel_stack@ is called the exception is copied into the exception
+handling mechanism's memory. Then the entirety of the current stack is
+unwound. After that it depends one which stack is being cancelled.
 \begin{description}
 \item[Main Stack:]
@@ -447,4 +503,6 @@
 happen in an implicate join inside a destructor. So there is an error message
 and an abort instead.
+\todo{Perhaps have a more general disucssion of unwind collisions before
+this point.}
 
 The recommended way to avoid the abort is to handle the intial resumption
@@ -455,9 +513,10 @@
 \item[Coroutine Stack:] A coroutine stack is created for a @coroutine@ object
 or object that satisfies the @is_coroutine@ trait. A coroutine only knows of
-two other coroutines, its starter and its last resumer. The last resumer has
-the tightest coupling to the coroutine it activated. Hence, cancellation of
-the active coroutine is forwarded to the last resumer after the stack is
-unwound, as the last resumer has the most precise knowledge about the current
-execution. When the resumer restarts, it resumes exception
+two other coroutines, its starter and its last resumer. Of the two the last
+resumer has the tightest coupling to the coroutine it activated and the most
+up-to-date information.
+
+Hence, cancellation of the active coroutine is forwarded to the last resumer
+after the stack is unwound. When the resumer restarts, it resumes exception
 @CoroutineCancelled@, which is polymorphic over the coroutine type and has a
 pointer to the cancelled coroutine.
Index: doc/theses/andrew_beach_MMath/uw-ethesis.tex
===================================================================
--- doc/theses/andrew_beach_MMath/uw-ethesis.tex	(revision c6640a3f9cf4c212817d3a07110b07b9f115e5a1)
+++ doc/theses/andrew_beach_MMath/uw-ethesis.tex	(revision d0502a3aee721f5f4e468913c7db6c2aab56025c)
@@ -108,4 +108,7 @@
 % Removes large sections of the document.
 \usepackage{comment}
+% Adds todos (Must be included after comment.)
+\usepackage{todonotes}
+
 
 % Hyperlinks make it very easy to navigate an electronic document.
@@ -213,4 +216,7 @@
 % Optional arguments do not work with pdf string. (Some fix-up required.)
 \pdfstringdefDisableCommands{\def\Cpp{C++}}
+
+% Colour text, formatted in LaTeX style instead of TeX style.
+\newcommand*\colour[2]{{\color{#1}#2}}
 \makeatother