source: doc/theses/andrew_beach_MMath/unwinding.tex @ 2c052c0

\chapter{Unwinding in \CFA}

Stack unwinding is the process of removing things from the stack from outside
the functions there. In languages that don't provide a way to garrenty that
code will run when the program leaves a scope or finishes a function, this
can be relatively trivial. C does this with \codeC{longjmp} by setting the
stack pointer and a few other registers.

\section{libunwind Usage}

There are two primary functions that \CFA uses in libunwind that create most
of the control flow. These are \codeC{\_Unwind\_RaiseException} and
\codeC{\_Unwind\_ForcedUnwind}.

Their operation is divided amoung two phases, search and clean-up. The search
phase -- phase 1 -- is used while scanning the stack while not actually
unwinding it while the clean-up phase -- phase 2 -- is used while the actual
unwinding is under way.

% Somewhere around here I need to talk about the control structures.
% \codeC{\_Unwind\_Exception} is used to carry the API's universal data. Some
% of this is internal, other fields are used to communicate between different
% exception handling mechanisms in different runtimes.
% \codeC{\_Unwind\_Context} is an opaque data structure that is used to pass
% information to helper functions.

Raise exception can cover both phases. It starts by searching for the handler
and if it finds it preforms a clean-up phase to unwind the stack to the
hander. If not it returns allowing the program to decide what to do with all
the state and stack that were in place before the call. During both phases
the raise exception function will search down the stack, calling each
function's personality function as they are found.

Personality functions must be able to preform three tasks, although not all
of them have to be preformed in a given call. Which tasks must be preformed
are decided by the actions provided.
% Something argument something bitmask.
\begin{itemize}
\item\codeC{\_UA\_SEARCH\_PHASE} this is being called during the clean-up
phase and means search for handlers. If the hander is found the personality
function should return \codeC{\_URC\_HANDLER\_FOUND}, otherise it should
return \codeC{\_URC\_CONTINUE\_UNWIND}.
\item\codeC{\_UA\_CLEANUP\_PHASE} is passed in during the clean-up phase and
means that part or all of the stack frame is being removed. The personality
function should do whatever clean-up the language defines (such as running
destructors) and then generally returns \codeC{\_URC\_CONTINUE\_UNWIND}.
\item\codeC{\_UA\_HANDLER\_FRAME} means that the personality function must
install a handler. It is also passing in during the clean-up phase and will
be in addition to the clean-up action. Libunwind provides several helpers
for the personality function here. Once it is done the personality function
must return \codeC{\_URC\_INSTALL\_CONTEXT}.
\end{itemize}

Forced unwind only preforms the clean-up phase. It is similar to the phase 2
section of raise exception with a few changes. A simple one is that
it passes in an extra action to the personality function
\codeC{\_UA\_FORCE\_UNWIND} which means a handler cannot be installed. The
most significant is the addition of the stop function, which is passed in as
an argument to the forced unwind.

The stop function is a lot like a personality function. It takes an extra
argument, a void pointer passed into force unwind. It may return
\codeC{\_URC\_NO\_REASON} to continue unwinding or it can transfer control
out of the unwind code using its own mechanism.
% Is there a reason that NO_REASON is used instead of CONTINUE_UNWIND?
The stop function is called once on every stack frame and once at the end of
the stack. In a stack frame it is called before the personality routine with
the same arguments (except for the extra void pointer). At the end of the
stack the arguments are mostly the same, except the stack pointer stored in
the context is set to null. Because of the significance of that change both
GCC and Clang add an extra action in this case \codeC{\_UA\_END\_OF\_STACK}.
The stop function may not return at the end of the stack.

\section{\CFA Implementation}

To use libunwind \CFA provides several wrappers, its own storage, the
personality functions and a stop function.

The wrappers preform three tasks: set-up, clean-up and controlling the
unwinding. The set-up allocates a copy of the \CFA exception into the hander
so it can control its lifetime and stores it in the exception context while
clean-up -- run when control exits a catch clause and return to normal code --
frees the exception copy.
% It however does not set up the unwind exception so we can't use any inter-
% runtime/language features. Also the exception context is global.

The control code in the middle is run every time a throw or re-throw is
called. It uses raise exception to search for a hander and to run it if one
is found. Otherwise it uses forced unwind to unwind the stack, running all
destructors, before terminating the process.

The stop function is very simple, it checks the end of stack flag to see if
it is finished unwinding. If so it calls exit to end the process, otherwise
it tells the system to continue unwinding.
% Yeah, this is going to have to change.

The personality routine is much more complicated.
First because it has to get some information about the function by scanning
the LSDA (Language Specific Data Area). This allows a single personality
function to be used for multiple functions and it accounts for multiple
regions and possible handlers in a single function.
% Not that we do that yet.

However generating the LSDA is very difficult. It requires a lot of knowledge
about the location of the instruction pointer and stack layout that can be
broken by optimization. So instead for frames where there are only destructors
we use GCC's attribute cleanup and the -fexception flag to handle unwinding
without adding our own functionality.

For functions that do have handlers (defined in try statements) the function
is split into several functions. Everything outside the try statement is the
first function, which has then has only destructors to be run during
unwinding. The clauses of the try block are then converted into GCC inner
functions which can be passed around with function pointers while still having
access to the outer function's scope. \codeC{catchResume} and \codeC{finally}
clauses are handled seperately and will not be discussed here.

The \codeC{try} clause is convered to a function directly. The \codeC{catch}
clauses are combined and then create two functions. The first is the match
function which is used during the search phase to see if any of the handler
here. The second it the catch function, which is a large switch-case block
with the different handlers. All of these function do not interact with
unwinding except for running destructors and so can be handled by GCC.

These three functions are passed into \codeC{try\_terminate}, an internal
function that repersents the try statement. This is the only function with
our personality function as well as assembly statements that create the LSDA.
In normal execution all the function does is call the try block closure and
return once that has finished executing. However using libunwind its
personality function now handles exception matching and catching.

During the search phase the personality function retreaves the match function
from the stack using the saved stack pointer. The function is called, either
returning 0 for no match or the index (a positive integer) of the handler
that will handle it. The if a handler was found the personality function
reports it after saving the index to the exception context.

During the clean-up phase there is nothing for the personality function to
clean-up in \codeC{try\_terminate}. So if this is not the handler frame
unwinding continues. If this is the handler frame than control is transfered
to the catch function, giving it the exception and the handler index.