\chapter{Exception Features}

This chapter covers the design and user interface of the \CFA
exception-handling mechanism (EHM). % or exception system.

% We should cover what is an exception handling mechanism and what is an
% exception before this. Probably in the introduction. Some of this could
% move there.
\paragraph{Raise / Handle}
An exception operation has two main parts: raise and handle.
These are the two parts that the user will write themselves and so
might be the only two pieces of the EHM that have any syntax.
These terms are sometimes also known as throw and catch but this work uses
throw/catch as a particular kind of raise/handle.

\subparagraph{Raise}
The raise is the starting point for exception handling and usually how
Some well known examples include the throw statements of \Cpp and Java and
the raise statement from Python.

For this overview a raise does nothing more kick off the handling of an
exception, which is called raising the exception. This is inexact but close
enough for the broad strokes of the overview.

\subparagraph{Handle}
The purpose of most exception operations is to run some sort of handler that
contains user code.
The try statement of \Cpp illistrates the common features
Handlers have three common features: a region of code they apply to, an
exception label that describes what exceptions they handle and code to run
when they handle an exception.
Each handler can handle exceptions raised in that region that match their
exception label. Different EHMs will have different rules to pick a handler
if multipe handlers could be used such as ``best match" or ``first found".

\paragraph{Propagation}
After an exception is raised comes what is usually the biggest step for the
EHM, finding and setting up the handler. This can be broken up into three
different tasks: searching for a handler, matching against the handler and
installing the handler.

First the EHM must search for possible handlers that could be used to handle
the exception. Searching is usually independent of the exception that was
thrown and instead depends on the call stack, the current function, its caller
and repeating down the stack.

Second it much match the exception with each handler to see which one is the
best match and hence which one should be used to handle the exception.
In languages where the best match is the first match these two are often
intertwined, a match check is preformed immediately after the search finds
a possible handler.

Third, after a handler is chosen it must be made ready to run.
What this actually involves can vary widely to fit with the rest of the
design of the EHM. The installation step might be trivial or it could be
the most expensive step in handling an exception. The latter tends to be the
case when stack unwinding is involved.

As an alternate third step if no appropriate handler is found then some sort
of recovery has to be preformed. This is only required with unchecked
exceptions as checked exceptions can promise that a handler is found. It also
is also installing a handler but it is a special default that may be
installed differently.

\subparagraph{Hierarchy}
In \CFA the EHM uses a hierarchial system to organise its exceptions.
This stratagy is borrowed from object-orientated languages where the
exception hierarchy is a natural extension of the object hierarchy.

Consider the following hierarchy of exceptions:
\begin{center}
\setlength{\unitlength}{4000sp}%
\begin{picture}(1605,612)(2011,-1951)
\put(2100,-1411){\vector(1, 0){225}}
\put(3450,-1411){\vector(1, 0){225}}
\put(3550,-1411){\line(0,-1){225}}
\put(3550,-1636){\vector(1, 0){150}}
\put(3550,-1636){\line(0,-1){225}}
\put(3550,-1861){\vector(1, 0){150}}
\put(2025,-1490){\makebox(0,0)[rb]{\LstBasicStyle{exception}}}
\put(2400,-1460){\makebox(0,0)[lb]{\LstBasicStyle{arithmetic}}}
\put(3750,-1460){\makebox(0,0)[lb]{\LstBasicStyle{underflow}}}
\put(3750,-1690){\makebox(0,0)[lb]{\LstBasicStyle{overflow}}}
\put(3750,-1920){\makebox(0,0)[lb]{\LstBasicStyle{zerodivide}}}
\end{picture}%
\end{center}

A handler labelled with any given exception can handle exceptions of that
type or any child type of that exception. The root of the exception hierarchy
(here \texttt{exception}) acts as a catch-all, leaf types catch single types
and the exceptions in the middle can be used to catch different groups of
related exceptions.

This system has some notable advantages, such as multiple levels of grouping,
the ability for libraries to add new exception types and the isolation
between different sub-hierarchies. So the design was adapted for a
non-object-orientated language.

% Could I cite the rational for the Python IO exception rework?

\paragraph{Completion}
After the handler has finished the entire exception operation has to complete
and continue executing somewhere else. This step is usually very simple
both logically and in its implementation as the installation of the handler
usually does the heavy lifting.

The EHM can return control to many different places.
However, the most common is after the handler definition and the next most
common is after the raise.

\paragraph{Communication}
For effective exception handling, additional information is usually required
as this base model only communicates the exception's identity. Common
additional methods of communication are putting fields on an exception and
allowing a handler to access the lexical scope it is defined in (usually
a function's local variables).

\paragraph{Other Features}
Any given exception handling mechanism is free at add other features on top
of this. This is an overview of the base that all EHMs use but it is not an
exaustive list of everything an EHM can do.

\section{Virtuals}
Virtual types and casts are not part of the exception system nor are they
required for an exception system. But an object-oriented style hierarchy is a
great way of organizing exceptions so a minimal virtual system has been added
to \CFA.

The virtual system supports multiple ``trees" of types. Each tree is
a simple hierarchy with a single root type. Each type in a tree has exactly
one parent - except for the root type which has zero parents - and any
number of children.
Any type that belongs to any of these trees is called a virtual type.

% A type's ancestors are its parent and its parent's ancestors.
% The root type has no ancestors.
% A type's decendents are its children and its children's decendents.

Every virtual type also has a list of virtual members. Children inherit
their parent's list of virtual members but may add new members to it.
It is important to note that these are virtual members, not virtual methods.
However as function pointers are allowed they can be used to mimic virtual
methods as well.

The unique id for the virtual type and all the virtual members are combined
into a virtual table type. Each virtual type has a pointer to a virtual table
as a hidden field.

Up until this point the virtual system is a lot like ones found in object-
orientated languages but this where they diverge. Objects encapsulate a
single set of behaviours in each type, universally across the entire program,
and indeed all programs that use that type definition. In this sense the
types are ``closed" and cannot be altered.

However in \CFA types do not encapsulate any behaviour. Traits are local and
types can begin to statify a trait, stop satifying a trait or satify the same
trait in a different way with each new definition. In this sense they are
``open" as they can change at any time. This means it is implossible to pick
a single set of functions that repersent the type.

So we don't try to have a single value. The user can define virtual tables
which are filled in at their declaration and given a name. Anywhere you can
see that name you can use that virtual table; even if it is defined locally
inside a function, although in that case you must respect its lifetime.

An object of a virtual type is ``bound" to a virtual table instance which
sets the virtual members for that object. The virtual members can be accessed
through the object.

While much of the virtual infrastructure is created, it is currently only used
internally for exception handling. The only user-level feature is the virtual
cast, which is the same as the \Cpp \lstinline[language=C++]|dynamic_cast|.
\label{p:VirtualCast}
\begin{cfa}
(virtual TYPE)EXPRESSION
\end{cfa}
Note, the syntax and semantics matches a C-cast, rather than the function-like
\Cpp syntax for special casts. Both the type of @EXPRESSION@ and @TYPE@ must be
a pointer to a virtual type.
The cast dynamically checks if the @EXPRESSION@ type is the same or a sub-type
of @TYPE@, and if true, returns a pointer to the
@EXPRESSION@ object, otherwise it returns @0p@ (null pointer).

\section{Exception}
% Leaving until later, hopefully it can talk about actual syntax instead
% of my many strange macros. Syntax aside I will also have to talk about the
% features all exceptions support.

Exceptions are defined by the trait system; there are a series of traits, and
if a type satisfies them, then it can be used as an exception. The following
is the base trait all exceptions need to match.
\begin{cfa}
trait is_exception(exceptT &, virtualT &) {
	virtualT const & get_exception_vtable(exceptT *);
};
\end{cfa}
The trait is defined over two types, the exception type and the virtual table
type. This should be one-to-one, each exception type has only one virtual
table type and vice versa. The only assertion in the trait is
@get_exception_vtable@, which takes a pointer of the exception type and
returns a reference to the virtual table type instance.

The function @get_exception_vtable@ is actually a constant function.
Regardless of the value passed in (including the null pointer) it should
return a reference to the virtual table instance for that type.
The reason it is a function instead of a constant is that it make type
annotations easier to write as you can use the exception type instead of the
virtual table type; which usually has a mangled name.
% Also \CFA's trait system handles functions better than constants and doing
% 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
% sure the function is implemented correctly. But this is true of every
% similar system I know of (except Agda's I guess) so I took it out.

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(
		exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
	void defaultTerminationHandler(exceptT &);
};

trait is_resumption_exception(
		exceptT &, virtualT & | is_exception(exceptT, virtualT)) {
	void defaultResumptionHandler(exceptT &);
};
\end{cfa}

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 tricky 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 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 flexibility.

For example consider a function that is polymorphic over types that have a
defined arithmetic exception:
\begin{cfa}
forall(Num | IS_EXCEPTION(Arithmetic, (Num)))
void some_math_function(Num & left, Num & right);
\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 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 occurred 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;
\end{cfa}
The expression must return a reference to a termination exception, where the
termination exception is any type that satisfies @is_termination_exception@
at the call site.
Through \CFA's trait system the functions in the traits are passed into the
throw code. A new @defaultTerminationHandler@ can be defined in any scope to
change the throw's behavior (see below).

The throw will copy the provided exception into managed memory. It is the
user's responsibility 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\)$) {
	HANDLER_BLOCK$\(_1\)$
} catch (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) {
	HANDLER_BLOCK$\(_2\)$
}
\end{cfa}
When viewed on its own a try statement will simply execute 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.

Exception matching checks the representation of the thrown exception-type is
the same or a descendant type of the exception types in the handler clauses. If
it is the same of a descendant of @EXCEPTION_TYPE@$_i$ then @NAME@$_i$ is
bound to a pointer to the exception and the statements in @HANDLER_BLOCK@$_i$
are executed. If control reaches the end of the handler, the exception is
freed and control continues after the try statement.

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 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 occurred and if the error is repaired
then the function can continue.

A resumption raise is started with the @throwResume@ statement:
\begin{cfa}
throwResume EXPRESSION;
\end{cfa}
The semantics of the @throwResume@ statement are like the @throw@, but the
expression has return a reference a type that satisfies the trait
@is_resumption_exception@. The assertions from this trait are available to
the exception system while handling the exception.

At run-time, 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 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 {
	GUARDED_BLOCK
} catchResume (EXCEPTION_TYPE$\(_1\)$ * NAME$\(_1\)$) {
	HANDLER_BLOCK$\(_1\)$
} catchResume (EXCEPTION_TYPE$\(_2\)$ * NAME$\(_2\)$) {
	HANDLER_BLOCK$\(_2\)$
}
\end{cfa}
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 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 search 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 equivalently
the try statements on the stack, so that the resumption search 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
% of the design of the traversal order.
\begin{verbatim}
       throwResume2 ----------.
            |                 |
 generated from handler       |
            |                 |
         handler              |
            |                 |
        throwResume1 -----.   :
            |             |   :
           try            |   : search skip
            |             |   :
        catchResume  <----'   :
            |                 |
\end{verbatim}

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 which means there is more to remember.

\section{Conditional Catch}
Both termination and resumption handler clauses can be given an additional
condition to further control which exceptions they handle:
\begin{cfa}
catch (EXCEPTION_TYPE * NAME ; CONDITION)
\end{cfa}
First, the same semantics is used to match the exception type. Second, if the
exception matches, @CONDITION@ is executed. The condition expression may
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 as if the exception type
did not match.
\begin{cfa}
try {
	f1 = open( ... );
	f2 = open( ... );
	...
} catch( IOFailure * f ; fd( f ) == f1 ) {
	// only handle IO failure for f1
}
\end{cfa}
Note, catching @IOFailure@, checking for @f1@ in the handler, and re-raising the
exception if not @f1@ is different because the re-raise does not examine any of
remaining handlers in the current try statement.

\section{Rethrowing}
\colour{red}{From Andrew: I recomend we talk about why the language doesn't
have rethrows/reraises instead.}

\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@, respectively.
\begin{cfa}
try {
	...
} catch( ... ) {
	... throw;
} catchResume( ... ) {
	... throwResume;
}
\end{cfa}
The only difference between a raise and a reraise is that reraise does not
create a new exception; instead it continues using the current exception, \ie
no allocation and copy. However the default handler is still set to the one
visible at the raise point, and hence, for termination could refer to data that
is part of an unwound stack frame. To prevent this problem, a new default
handler is generated that does a program-level abort.

\section{Finally Clauses}
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 {
	GUARDED_BLOCK
} ... // any number or kind of handler clauses
... finally {
	FINALLY_BLOCK
}
\end{cfa}
The @FINALLY_BLOCK@ is executed when the try statement is removed from the
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
the stack is unwound.

Execution of the finally block should always finish, meaning control runs off
the end of the block. This requirement ensures always continues as if the
finally clause is not present, \ie finally is for cleanup not changing control
flow. Because of this requirement, local control flow out of the finally block
is forbidden. The compiler precludes any @break@, @continue@, @fallthru@ or
@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 mealy
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}
Cancellation is a stack-level abort, which can be thought of as as an
uncatchable termination. It unwinds the entirety of the current stack, and if
possible forwards the cancellation exception to a different stack.

Cancellation is not an exception operation like termination or resumption.
There is no special statement for starting a cancellation; instead the standard
library function @cancel_stack@ is called passing an exception. Unlike a
throw, this exception is not used in matching only to pass information about
the cause of the cancellation.
(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:]
The main stack is the one used by the program main at the start of execution,
and is the only stack in a sequential program. Even in a concurrent program
the main stack is only dependent on the environment that started the program.
Hence, when the main stack is cancelled there is nowhere else in the program
to notify. After the stack is unwound, there is a program-level abort.

\item[Thread Stack:]
A thread stack is created for a @thread@ object or object that satisfies the
@is_thread@ trait. A thread only has two points of communication that must
happen: start and join. As the thread must be running to perform a
cancellation, it must occur after start and before join, so join is used
for communication here.
After the stack is unwound, the thread halts and waits for
another thread to join with it. The joining thread checks for a cancellation,
and if present, resumes exception @ThreadCancelled@.

There is a subtle difference between the explicit join (@join@ function) and
implicit join (from a destructor call). The explicit join takes the default
handler (@defaultResumptionHandler@) from its calling context, which is used if
the exception is not caught. The implicit join does a program abort instead.

This semantics is for safety. If an unwind is triggered while another unwind
is underway only one of them can proceed as they both want to ``consume'' the
stack. Letting both try to proceed leads to very undefined behaviour.
Both termination and cancellation involve unwinding and, since the default
@defaultResumptionHandler@ preforms a termination that could more easily
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 initial resumption
from the implicate join. If required you may put an explicate join inside a
finally clause to disable the check and use the local
@defaultResumptionHandler@ instead.

\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. 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.

The resume function also has an assertion that the @defaultResumptionHandler@
for the exception. So it will use the default handler like a regular throw.
\end{description}