\chapter{Features}

This chapter covers the design and user interface of the \CFA exception
handling mechanism.

\section{Virtual Casts}

Virtual casts and virtual types are not truly part of the exception system but
they did not exist in \CFA and are useful in exceptions. So a minimal version
of they virtual system was designed and implemented.

Virtual types are organized in simple hierarchies. Each virtual type may have
a parent and can have any number of children. A type's descendants are its
children and its children's descendants. A type may not be its own descendant.

Each virtual type has an associated virtual table type. A virtual table is a
structure that has fields for all the virtual members of a type. A virtual
type has all the virtual members of its parent and can add more. It may also
update the values of the virtual members and should in many cases.

Except for virtual casts, this is only used internally in the exception
system. There is no general purpose interface for the other features. A
a virtual cast has the following syntax:

\begin{lstlisting}
(virtual TYPE)EXPRESSION
\end{lstlisting}

This has the same precedence as a traditional C-cast and can be used in the
same places. This will convert the result of EXPRESSION to the type TYPE. Both
the type of EXPRESSION and TYPE must be pointers to virtual types.

The cast is checked and will either return the original value or null, based
on the result of the check. The check is does the object pointed at have a
type that is a descendant of the target type. If it is the result is the
pointer, otherwise the result is null.

\section{Exceptions}
% 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.

\subsection{Exception Traits}
Exceptions are defined by the trait system; there are a series of traits and
if a type satisfies them then they can be used as exceptions.

\begin{lstlisting}
trait is_exception(dtype exceptT, dtype virtualT) {
    virtualT const & get_exception_vtable(exceptT *);
};
\end{lstlisting}
This is the base trait that all exceptions need to match.
The single function takes any pointer (including the null pointer) and
returns a reference to the virtual table instance. Defining this function
also establishes the virtual type and virtual table pair to the resolver
and promises that @exceptT@ is a virtual type and a child of the
base exception type.

One odd thing about @get_exception_vtable@ is that it should always
be a constant function, returning the same value regardless of its argument.
A pointer or reference to the virtual table instance could be used instead,
however using a function has some ease of implementation advantages and
allows for easier disambiguation because the virtual type name (or the
address of an instance that is in scope) can be used instead of the mangled
virtual table name.

Also note the use of the word ``promise" in the trait description. \CFA
cannot currently check to see if either @exceptT@ or
@virtualT@ match the layout requirements. Currently this is
considered part of @get_exception_vtable@'s correct implementation.

\begin{lstlisting}
trait is_termination_exception(
        dtype exceptT, dtype virtualT | is_exception(exceptT, virtualT)) {
    void defaultTerminationHandler(exceptT &);
};
\end{lstlisting}
The only additional function required to make the exception usable with
termination is a default handler. This function is called whenever a
termination throw on an exception of this type is preformed and no handler
is found.

\begin{lstlisting}
trait is_resumption_exception(
        dtype exceptT, dtype virtualT | is_exception(exceptT, virtualT)) {
    void defaultResumptionHandler(exceptT &);
};
\end{lstlisting}
Creating a resumption exception is exactly the same except for resumption.
The name change reflects that and the function is called when a resumption
throw on an exception of this type is preformed and no handler is found.

Finally there are three additional macros that can be used to refer to the
these traits. They are @IS_EXCEPTION@,
@IS_TERMINATION_EXCEPTION@ and @IS_RESUMPTION_EXCEPTION@.
Each takes the virtual type's name and, for polymorphic types only, the
parenthesized list of polymorphic arguments. These do the name mangling to
get the virtual table name and provide the arguments to both sides.

\section{Termination}

Termination exception throws are likely the most familiar kind, as they are
used in several popular programming languages. A termination will throw an
exception, search the stack for a handler, unwind the stack to where the
handler is defined, execute the handler and then continue execution after
the handler. They are used when execution cannot continue here.

Termination has two pieces of syntax it uses. The first is the throw:
\begin{lstlisting}
throw EXPRESSION;
\end{lstlisting}

The expression must evaluate to a reference to a termination exception. A
termination exception is any exception with a
@void defaultTerminationHandler(T &);@ (the default handler) defined
on it. The handler is taken from the call sight with \CFA's trait system and
passed into the exception system along with the exception itself.

The exception passed into the system is then copied into managed memory.
This is to ensure it remains in scope during unwinding. It is the user's
responsibility to make sure the original exception is freed when it goes out
of scope. Being allocated on the stack is sufficient for this.

Then the exception system will search the stack starting from the throw and
proceeding towards the base of the stack, from callee to caller. As it goes
it will check any termination handlers it finds:

\begin{lstlisting}
try {
    TRY_BLOCK
} catch (EXCEPTION_TYPE * NAME) {
    HANDLER
}
\end{lstlisting}

This shows a try statement with a single termination handler. The statements
in TRY\_BLOCK will be executed when control reaches this statement. While
those statements are being executed if a termination exception is thrown and
it is not handled by a try statement further up the stack the EHM will check
all of the terminations handlers attached to the try block, top to bottom.

At each handler the EHM will check to see if the thrown exception is a
descendant of EXCEPTION\_TYPE. If it is the pointer to the exception is
bound to NAME and the statements in HANDLER are executed. If control reaches
the end of the handler then it exits the block, the exception is freed and
control continues after the try statement.

The default handler is only used if no handler for the exception is found
after the entire stack is searched. When that happens the default handler
is called with a reference to the exception as its only argument. If the
handler returns control continues from after the throw statement.

\paragraph{Conditional Catches}

Catch clauses may also be written as:
\begin{lstlisting}
catch (EXCEPTION_TYPE * NAME ; CONDITION)
\end{lstlisting}
This has the same behaviour as a regular catch clause except that if the
exception matches the given type the condition is also run. If the result is
true only then is this considered a matching handler. If the result is false
then the handler does not match and the search continues with the next clause
in the try block.

The condition considers all names in scope at the beginning of the try block
to be in scope along with the name introduce in the catch clause itself.

\paragraph{Re-Throwing}

You can also re-throw the most recent termination exception with
@throw;@. % This is terrible and you should never do it.
This can be done in a handler or any function that could be called from a
handler.

This will start another termination throw reusing the exception, meaning it
does not copy the exception or allocated any more memory for it. However the
default handler is still at the original through and could refer to data that
was on the unwound section of the stack. So instead a new default handler that
does a program level abort is used.

\section{Resumption}

Resumption exceptions are less popular then termination but in many
regards are simpler and easier to understand. A resumption throws an exception,
searches for a handler on the stack, executes that handler on top of the stack
and then continues execution from the throw. These are used when a problem
needs to be fixed before execution continues.

A resumption is thrown with a throw resume statement:
\begin{lstlisting}
throwResume EXPRESSION;
\end{lstlisting}
The result of EXPRESSION must be a resumption exception type. A resumption
exception type is any type that satisfies the assertion
@void defaultResumptionHandler(T &);@ (the default handler). When the
statement is executed the expression is evaluated and the result is thrown.

Handlers are declared using clauses in try statements:
\begin{lstlisting}
try {
    TRY_BLOCK
} catchResume (EXCEPTION_TYPE * NAME) {
    HANDLER
}
\end{lstlisting}
This is a simple example with the try block and a single resumption handler.
Multiple resumption handlers can be put in a try statement and they can be
mixed with termination handlers.

When a resumption begins it will start searching the stack starting from
the throw statement and working its way to the callers. In each try statement
handlers will be tried top to bottom. Each handler is checked by seeing if
the thrown exception is a descendant of EXCEPTION\_TYPE. If not the search
continues. Otherwise NAME is bound to a pointer to the exception and the
HANDLER statements are executed. After they are finished executing control
continues from the throw statement.

If no appropriate handler is found then the default handler is called. The
throw statement acts as a regular function call passing the exception to
the default handler and after the handler finishes executing control continues
from the throw statement.

The exception system also tracks the position of a search on the stack. If
another resumption exception is thrown while a resumption handler is running
it will first check handlers pushed to the stack by the handler and any
functions it called, then it will continue from the try statement that the
handler is a part of; except for the default handler where it continues from
the throw the default handler was passed to.

This makes the search pattern for resumption reflect the one for termination,
which is what most users expect.

% This might need a diagram. But it is an important part of the justification
% of the design of the traversal order.
It also avoids the recursive resumption problem. If the entire stack is
searched loops of resumption can form. Consider a handler that handles an
exception of type A by resuming an exception of type B and on the same stack,
later in the search path, is a second handler that handles B by resuming A.

Assuming no other handlers on the stack handle A or B then in either traversal
system an A resumed from the top of the stack will be handled by the first
handler. A B resumed from the top or from the first handler it will be handled
by the second handler. The only difference is when A is thrown from the second
handler. The entire stack search will call the first handler again, creating a
loop. Starting from the position in the stack though will break this loop.

\paragraph{Conditional Catches}

Resumption supports conditional catch clauses like termination does. They
use the same syntax except the keyword is changed:
\begin{lstlisting}
catchResume (EXCEPTION_TYPE * NAME ; CONDITION)  
\end{lstlisting}

It also has the same behaviour, after the exception type has been matched
with the EXCEPTION\_TYPE the CONDITION is evaluated with NAME in scope. If
the result is true then the handler is run, otherwise the search continues
just as if there had been a type mismatch.

\paragraph{Re-Throwing}

You may also re-throw resumptions with a @throwResume;@ statement.
This can only be done from inside of a @catchResume@ block.

Outside of any side effects of any code already run in the handler this will
have the same effect as if the exception had not been caught in the first
place.

\section{Finally Clauses}

A @finally@ clause may be placed at the end of a try statement after
all the handler clauses. In the simply case, with no handlers, it looks like
this:

\begin{lstlisting}
try {
    TRY_BLOCK
} finally {
    FINAL_STATEMENTS
}
\end{lstlisting}

Any number of termination handlers and resumption handlers may proceed the
finally clause.

The FINAL\_STATEMENTS, the finally block, are executed whenever the try
statement is removed from the stack. This includes: the TRY\_BLOCK finishes
executing, a termination exception finishes executing and the stack unwinds.

Execution of the finally block should finish by letting control run off
the end of the block. This is because after the finally block is complete
control will continue to where ever it would if the finally clause was not
present.

Because of this local control flow out of the finally block is forbidden.
The compiler rejects uses of @break@, @continue@,
@fallthru@ and @return@ that would cause 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, at best requiring additional
run-time overhead, and so are merely discouraged.

\section{Cancellation}

Cancellation can be thought of as a stack-level abort or as an uncatchable
termination. It unwinds the entirety of the current exception and if possible
passes an exception to a different stack as a message.

There is no special statement for starting a cancellation, instead you call
the standard library function @cancel\_stack@ which takes an exception.
Unlike in a throw this exception is not used in control flow but is just there
to pass information about why the cancellation happened.

The handler is decided entirely by which stack is being canceled. There are
three handlers that apply to three different groups of stacks:
\begin{itemize}
\item Main Stack:
The main stack is the one on which the program main is called at the beginning
of your program. It is also the only stack you have without the libcfathreads.

Because of this there is no other stack ``above" (or possibly at all) for main
to notify when a cancellation occurs. So after the stack is unwound we do a
program level abort.

\item Thread Stack:
Thread stacks are those created @thread@ or otherwise satisfy the
@is\_thread@ trait.

Threads only have two structural points of communication that must happen,
start and join. As the thread must be running to preform a cancellation it
will be after start and before join, so join is one cancellation uses.

After the stack is unwound the thread will halt as if had completed normally
and wait for another thread to join with it. The other thread, when it joins,
checks for a cancellation. If so it will throw the resumption exception
@ThreadCancelled@.

There is a difference here in how explicate joins (with the @join@
function) and implicate joins (from a destructor call). Explicate joins will
take the default handler (@defaultResumptionHandler@) from the context
and use like a regular through does if the exception is not caught. The
implicate join does a program abort instead.

This is for safety. One of the big problems in exceptions is you cannot handle
two terminations or cancellations on the same stack as either can destroy the
context required for the other. This can happen with join but as the
destructors will always be run when the stack is being unwound and one
termination/cancellation is already active. Also since they are implicit they
are easier to forget about.

\item Coroutine Stack:
Coroutine stacks are those created with @coroutine@ or otherwise
satisfy the @is\_coroutine@ trait.

A coroutine knows of two other coroutines, its starter and its last resumer.
The last resumer is ``closer" so that is the one notified.

After the stack is unwound control goes to the last resumer.
Resume will resume throw a @CoroutineCancelled@ exception, which is
polymorphic over the coroutine type and has a pointer to the coroutine being
canceled and the canceling exception. 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{itemize}