Changeset f28fdee


Ignore:
Timestamp:
Jan 20, 2021, 5:27:42 PM (8 months ago)
Author:
Peter A. Buhr <pabuhr@…>
Branches:
arm-eh, jacob/cs343-translation, master, new-ast-unique-expr
Children:
09ee131
Parents:
79e261b7
Message:

incorporate uw-thesis macros and CFA common macros

Location:
doc/theses/andrew_beach_MMath
Files:
3 added
6 edited

Legend:

Unmodified
Added
Removed
  • doc/theses/andrew_beach_MMath/Makefile

    r79e261b7 rf28fdee  
    11### Makefile for Andrew Beach's Masters Thesis
    22
    3 DOC=thesis.pdf
     3DOC=uw-thesis.pdf
    44BUILD=out
    55TEXSRC=$(wildcard *.tex)
     
    77STYSRC=$(wildcard *.sty)
    88CLSSRC=$(wildcard *.cls)
    9 TEXLIB= .:${BUILD}:
     9TEXLIB= .:../../LaTeXmacros:${BUILD}:
    1010BIBLIB= .:../../bibliography
    1111
     
    2929        ${LATEX} ${BASE}
    3030        ${BIBTEX} ${BUILD}/${BASE}
     31        ${LATEX} ${BASE}
    3132        ${GLOSSARY} ${BUILD}/${BASE}
    3233        ${LATEX} ${BASE}
  • doc/theses/andrew_beach_MMath/existing.tex

    r79e261b7 rf28fdee  
    1 \chapter{\CFA{} Existing Features}
     1\chapter{\CFA Existing Features}
     2
     3\CFA (C-for-all)~\cite{Cforall} is an open-source project extending ISO C with modern safety and productivity features, while still ensuring backwards compatibility with C and its programmers.
     4\CFA is designed to have an orthogonal feature-set based closely on the C programming paradigm (non-object-oriented) and these features can be added incrementally to an existing C code-base allowing programmers to learn \CFA on an as-needed basis.
    25
    36\section{Overloading and extern}
    47Cforall has overloading, allowing multiple definitions of the same name to
    5 be defined.
     8be defined.~\cite{Moss18}
    69
    710This also adds name mangling so that the assembly symbols are unique for
     
    1114
    1215The syntax for disabling mangling is:
    13 \begin{lstlisting}
     16\begin{cfa}
    1417extern "C" {
    1518    ...
    1619}
    17 \end{lstlisting}
     20\end{cfa}
    1821
    1922To re-enable mangling once it is disabled the syntax is:
    20 \begin{lstlisting}
     23\begin{cfa}
    2124extern "Cforall" {
    2225    ...
    2326}
    24 \end{lstlisting}
     27\end{cfa}
    2528
    2629Both should occur at the declaration level and effect all the declarations
    27 in \texttt{...}. Neither care about the state of mangling when they begin
     30in @...@. Neither care about the state of mangling when they begin
    2831and will return to that state after the group is finished. So re-enabling
    2932is only used to nest areas of mangled and unmangled declarations.
     
    3134\section{References}
    3235\CFA adds references to C. These are auto-dereferencing pointers and use the
    33 same syntax as pointers except they use ampersand (\codeCFA{\&}) instead of
    34 the asterisk (\codeCFA{*}). They can also be constaint or mutable, if they
     36same syntax as pointers except they use ampersand (@&@) instead of
     37the asterisk (@*@). They can also be constaint or mutable, if they
    3538are mutable they may be assigned to by using the address-of operator
    36 (\codeCFA\&) which converts them into a pointer.
     39(@&@) which converts them into a pointer.
    3740
    3841\section{Constructors and Destructors}
     
    4144functions with special names. The special names are used to define them and
    4245may be used to call the functions expicately. The \CFA special names are
    43 constructed by taking the tokens in the operators and putting \texttt{?} where
    44 the arguments would go. So multiplication is \texttt{?*?} while dereference
    45 is \texttt{*?}. This also make it easy to tell the difference between
    46 pre-fix operations (such as \texttt{++?}) and post-fix operations
    47 (\texttt{?++}).
    48 
    49 The special name for contructors is \texttt{?\{\}}, which comes from the
     46constructed by taking the tokens in the operators and putting @?@ where
     47the arguments would go. So multiplication is @?*?@ while dereference
     48is @*?@. This also make it easy to tell the difference between
     49pre-fix operations (such as @++?@) and post-fix operations
     50(@?++@).
     51
     52The special name for contructors is @?{}@, which comes from the
    5053initialization syntax in C. The special name for destructors is
    51 \texttt{\^{}?\{\}}. % I don't like the \^{} symbol but $^\wedge$ isn't better.
     54@^{}@. % I don't like the \^{} symbol but $^\wedge$ isn't better.
    5255
    5356Any time a type T goes out of scope the destructor matching
    54 \codeCFA{void ^?\{\}(T \&);} is called. In theory this is also true of
    55 primitive types such as \codeCFA{int}, but in practice those are no-ops and
     57@void ^?{}(T &);@ is called. In theory this is also true of
     58primitive types such as @int@, but in practice those are no-ops and
    5659are usually omitted for optimization.
    5760
    5861\section{Polymorphism}
    5962\CFA uses polymorphism to create functions and types that are defined over
    60 different types. \CFA polymorphic declarations serve the same role as \CPP
     63different types. \CFA polymorphic declarations serve the same role as \CC
    6164templates or Java generics.
    6265
     
    6568except that you may use the names introduced by the forall clause in them.
    6669
    67 Forall clauses are written \codeCFA{forall( ... )} where \codeCFA{...} becomes
     70Forall clauses are written @forall( ... )@ where @...@ becomes
    6871the list of polymorphic variables (local type names) and assertions, which
    6972repersent required operations on those types.
    7073
    71 \begin{lstlisting}
     74\begin{cfa}
    7275forall(dtype T | { void do_once(T &); })
    7376void do_twice(T & value) {
     
    7578    do_once(value);
    7679}
    77 \end{lstlisting}
     80\end{cfa}
    7881
    7982A polymorphic function can be used in the same way normal functions are.
     
    8386the the call site.
    8487
    85 As an example, even if no function named \codeCFA{do_once} is not defined
    86 near the definition of \codeCFA{do_twice} the following code will work.
    87 \begin{lstlisting}
     88As an example, even if no function named @do_once@ is not defined
     89near the definition of @do_twice@ the following code will work.
     90\begin{cfa}
    8891int quadruple(int x) {
    8992    void do_once(int & y) {
     
    9396    return x;
    9497}
    95 \end{lstlisting}
     98\end{cfa}
    9699This is not the recommended way to implement a quadruple function but it
    97 does work. The complier will deduce that \codeCFA{do_twice}'s T is an
     100does work. The complier will deduce that @do_twice@'s T is an
    98101integer from the argument. It will then look for a definition matching the
    99 assertion which is the \codeCFA{do_once} defined within the function. That
    100 function will be passed in as a function pointer to \codeCFA{do_twice} and
     102assertion which is the @do_once@ defined within the function. That
     103function will be passed in as a function pointer to @do_twice@ and
    101104called within it.
    102105
     
    104107traits which collect assertions into convenent packages that can then be used
    105108in assertion lists instead of all of their components.
    106 \begin{lstlisting}
     109\begin{cfa}
    107110trait done_once(dtype T) {
    108111    void do_once(T &);
    109112}
    110 \end{lstlisting}
     113\end{cfa}
    111114
    112115After this the forall list in the previous example could instead be written
    113116with the trait instead of the assertion itself.
    114 \begin{lstlisting}
     117\begin{cfa}
    115118forall(dtype T | done_once(T))
    116 \end{lstlisting}
     119\end{cfa}
    117120
    118121Traits can have arbitrary number of assertions in them and are usually used to
     
    124127are now used in field declaractions instead of parameters and local variables.
    125128
    126 \begin{lstlisting}
     129\begin{cfa}
    127130forall(dtype T)
    128131struct node {
     
    130133    T * data;
    131134}
    132 \end{lstlisting}
    133 
    134 The \codeCFA{node(T)} is a use of a polymorphic structure. Polymorphic types
     135\end{cfa}
     136
     137The @node(T)@ is a use of a polymorphic structure. Polymorphic types
    135138must be provided their polymorphic parameters.
    136139
     
    140143\section{Concurrency}
    141144
    142 \CFA has a number of concurrency features, \codeCFA{thread}s,
    143 \codeCFA{monitor}s and \codeCFA{mutex} parameters, \codeCFA{coroutine}s and
    144 \codeCFA{generator}s. The two features that interact with the exception system
    145 are \codeCFA{thread}s and \codeCFA{coroutine}s; they and their supporting
     145\CFA has a number of concurrency features, @thread@s,
     146@monitor@s and @mutex@ parameters, @coroutine@s and
     147@generator@s. The two features that interact with the exception system
     148are @thread@s and @coroutine@s; they and their supporting
    146149constructs will be described here.
    147150
     
    154157library.
    155158
    156 In \CFA coroutines are created using the \codeCFA{coroutine} keyword which
    157 works just like \codeCFA{struct} except that the created structure will be
    158 modified by the compiler to satify the \codeCFA{is_coroutine} trait.
     159In \CFA coroutines are created using the @coroutine@ keyword which
     160works just like @struct@ except that the created structure will be
     161modified by the compiler to satify the @is_coroutine@ trait.
    159162
    160163These structures act as the interface between callers and the coroutine,
    161164the fields are used to pass information in and out. Here is a simple example
    162165where the single field is used to pass the next number in a sequence out.
    163 \begin{lstlisting}
     166\begin{cfa}
    164167coroutine CountUp {
    165168    unsigned int next;
    166169}
    167 \end{lstlisting}
     170\end{cfa}
    168171
    169172The routine part of the coroutine is a main function for the coroutine. It
     
    173176function it continue from that same suspend statement instead of at the top
    174177of the function.
    175 \begin{lstlisting}
     178\begin{cfa}
    176179void main(CountUp & this) {
    177180    unsigned int next = 0;
     
    182185    }
    183186}
    184 \end{lstlisting}
     187\end{cfa}
    185188
    186189Control is passed to the coroutine with the resume function. This includes the
     
    189192return value is for easy access to communication variables. For example the
    190193next value from a count-up can be generated and collected in a single
    191 expression: \codeCFA{resume(count).next}.
     194expression: @resume(count).next@.
    192195
    193196\subsection{Monitors and Mutex}
     
    198201parameters.
    199202
    200 Function parameters can have the \codeCFA{mutex} qualifiers on reference
    201 arguments, for example \codeCFA{void example(a_monitor & mutex arg);}. When the
     203Function parameters can have the @mutex@ qualifiers on reference
     204arguments, for example @void example(a_monitor & mutex arg);@. When the
    202205function is called it will acquire the lock on all of the mutex parameters.
    203206
     
    214217
    215218Threads are created like coroutines except the keyword is changed:
    216 \begin{lstlisting}
     219\begin{cfa}
    217220thread StringWorker {
    218221    const char * input;
     
    225228    this.result = result;
    226229}
    227 \end{lstlisting}
     230\end{cfa}
    228231The main function will start executing after the fork operation and continue
    229232executing until it is finished. If another thread joins with this one it will
     
    233236From the outside this is the creation and destruction of the thread object.
    234237Fork happens after the constructor is run and join happens before the
    235 destructor runs. Join also happens during the \codeCFA{join} function which
     238destructor runs. Join also happens during the @join@ function which
    236239can be used to join a thread earlier. If it is used the destructor does not
    237240join as that has already been completed.
  • doc/theses/andrew_beach_MMath/features.tex

    r79e261b7 rf28fdee  
    5454returns a reference to the virtual table instance. Defining this function
    5555also establishes the virtual type and virtual table pair to the resolver
    56 and promises that \codeCFA{exceptT} is a virtual type and a child of the
     56and promises that @exceptT@ is a virtual type and a child of the
    5757base exception type.
    5858
    59 One odd thing about \codeCFA{get_exception_vtable} is that it should always
     59One odd thing about @get_exception_vtable@ is that it should always
    6060be a constant function, returning the same value regardless of its argument.
    6161A pointer or reference to the virtual table instance could be used instead,
     
    6666
    6767Also note the use of the word ``promise" in the trait description. \CFA
    68 cannot currently check to see if either \codeCFA{exceptT} or
    69 \codeCFA{virtualT} match the layout requirements. Currently this is
    70 considered part of \codeCFA{get_exception_vtable}'s correct implementation.
     68cannot currently check to see if either @exceptT@ or
     69@virtualT@ match the layout requirements. Currently this is
     70considered part of @get_exception_vtable@'s correct implementation.
    7171
    7272\begin{lstlisting}
     
    9292
    9393Finally there are three additional macros that can be used to refer to the
    94 these traits. They are \codeCFA{IS_EXCEPTION},
    95 \codeCFA{IS_TERMINATION_EXCEPTION} and \codeCFA{IS_RESUMPTION_EXCEPTION}.
     94these traits. They are @IS_EXCEPTION@,
     95@IS_TERMINATION_EXCEPTION@ and @IS_RESUMPTION_EXCEPTION@.
    9696Each takes the virtual type's name and, for polymorphic types only, the
    9797parenthesized list of polymorphic arguments. These do the name mangling to
     
    113113The expression must evaluate to a reference to a termination exception. A
    114114termination exception is any exception with a
    115 \codeCFA{void defaultTerminationHandler(T &);} (the default handler) defined
     115@void defaultTerminationHandler(T &);@ (the default handler) defined
    116116on it. The handler is taken from the call sight with \CFA's trait system and
    117117passed into the exception system along with the exception itself.
     
    169169
    170170You can also re-throw the most recent termination exception with
    171 \codeCFA{throw;}. % This is terrible and you should never do it.
     171@throw;@. % This is terrible and you should never do it.
    172172This can be done in a handler or any function that could be called from a
    173173handler.
     
    193193The result of EXPRESSION must be a resumption exception type. A resumption
    194194exception type is any type that satisfies the assertion
    195 \codeCFA{void defaultResumptionHandler(T &);} (the default handler). When the
     195@void defaultResumptionHandler(T &);@ (the default handler). When the
    196196statement is executed the expression is evaluated and the result is thrown.
    197197
     
    260260\paragraph{Re-Throwing}
    261261
    262 You may also re-throw resumptions with a \codeCFA{throwResume;} statement.
    263 This can only be done from inside of a \codeCFA{catchResume} block.
     262You may also re-throw resumptions with a @throwResume;@ statement.
     263This can only be done from inside of a @catchResume@ block.
    264264
    265265Outside of any side effects of any code already run in the handler this will
     
    269269\section{Finally Clauses}
    270270
    271 A \codeCFA{finally} clause may be placed at the end of a try statement after
     271A @finally@ clause may be placed at the end of a try statement after
    272272all the handler clauses. In the simply case, with no handlers, it looks like
    273273this:
     
    294294
    295295Because of this local control flow out of the finally block is forbidden.
    296 The compiler rejects uses of \codeCFA{break}, \codeCFA{continue},
    297 \codeCFA{fallthru} and \codeCFA{return} that would cause control to leave
     296The compiler rejects uses of @break@, @continue@,
     297@fallthru@ and @return@ that would cause control to leave
    298298the finally block. Other ways to leave the finally block - such as a long
    299299jump or termination - are much harder to check, at best requiring additional
     
    307307
    308308There is no special statement for starting a cancellation, instead you call
    309 the standard library function \codeCFA{cancel\_stack} which takes an exception.
     309the standard library function @cancel\_stack@ which takes an exception.
    310310Unlike in a throw this exception is not used in control flow but is just there
    311311to pass information about why the cancellation happened.
     
    323323
    324324\item Thread Stack:
    325 Thread stacks are those created \codeCFA{thread} or otherwise satisfy the
    326 \codeCFA{is\_thread} trait.
     325Thread stacks are those created @thread@ or otherwise satisfy the
     326@is\_thread@ trait.
    327327
    328328Threads only have two structural points of communication that must happen,
     
    333333and wait for another thread to join with it. The other thread, when it joins,
    334334checks for a cancellation. If so it will throw the resumption exception
    335 \codeCFA{ThreadCancelled}.
    336 
    337 There is a difference here in how explicate joins (with the \codeCFA{join}
     335@ThreadCancelled@.
     336
     337There is a difference here in how explicate joins (with the @join@
    338338function) and implicate joins (from a destructor call). Explicate joins will
    339 take the default handler (\codeCFA{defaultResumptionHandler}) from the context
     339take the default handler (@defaultResumptionHandler@) from the context
    340340and use like a regular through does if the exception is not caught. The
    341341implicate join does a program abort instead.
     
    349349
    350350\item Coroutine Stack:
    351 Coroutine stacks are those created with \codeCFA{coroutine} or otherwise
    352 satisfy the \codeCFA{is\_coroutine} trait.
     351Coroutine stacks are those created with @coroutine@ or otherwise
     352satisfy the @is\_coroutine@ trait.
    353353
    354354A coroutine knows of two other coroutines, its starter and its last resumer.
     
    356356
    357357After the stack is unwound control goes to the last resumer.
    358 Resume will resume throw a \codeCFA{CoroutineCancelled} exception, which is
     358Resume will resume throw a @CoroutineCancelled@ exception, which is
    359359polymorphic over the coroutine type and has a pointer to the coroutine being
    360360canceled and the canceling exception. The resume function also has an
    361 assertion that the \codeCFA{defaultResumptionHandler} for the exception. So it
     361assertion that the @defaultResumptionHandler@ for the exception. So it
    362362will use the default handler like a regular throw.
    363363
  • doc/theses/andrew_beach_MMath/future.tex

    r79e261b7 rf28fdee  
    2020
    2121\section{Additional Throws}
    22 Several other kinds of throws, beyond the termination throw (\codeCFA{throw}),
    23 the resumption throw (\codeCFA{throwResume}) and the re-throws, were considered.
     22Several other kinds of throws, beyond the termination throw (@throw@),
     23the resumption throw (@throwResume@) and the re-throws, were considered.
    2424None were as useful as the core throws but they would likely be worth
    2525revising.
     
    114114is no reason not to allow it. It is however a small improvement; giving a bit
    115115of flexibility to the user in what style they want to use.
    116 \item Enabling local control flow (by \codeCFA{break}, \codeCFA{return} and
     116\item Enabling local control flow (by @break@, @return@ and
    117117similar statements) out of a termination handler. The current set-up makes
    118118this very difficult but the catch function that runs the handler after it has
  • doc/theses/andrew_beach_MMath/implement.tex

    r79e261b7 rf28fdee  
    99
    1010All of this is accessed through a field inserted at the beginning of every
    11 virtual type. Currently it is called \codeC{virtual_table} but it is not
     11virtual type. Currently it is called @virtual_table@ but it is not
    1212ment to be accessed by the user. This field is a pointer to the type's
    1313virtual table instance. It is assigned once during the object's construction
     
    4040using that to calculate the mangled name of the parent's virtual table type.
    4141There are two special fields that are included like normal fields but have
    42 special initialization rules: the \codeC{size} field is the type's size and is
    43 initialized with a sizeof expression, the \codeC{align} field is the type's
     42special initialization rules: the @size@ field is the type's size and is
     43initialized with a sizeof expression, the @align@ field is the type's
    4444alignment and uses an alignof expression. The remaining fields are resolved
    4545to a name matching the field's name and type using the normal visibility
     
    5656The declarations include the virtual type definition and forward declarations
    5757of the virtual table instance, constructor, message function and
    58 \codeCFA{get_exception_vtable}. The definition includes the storage and
     58@get_exception_vtable@. The definition includes the storage and
    5959initialization of the virtual table instance and the bodies of the three
    6060functions.
     
    6565from the per-instance information. The virtual table type and most of the
    6666functions are polymorphic so they are all part of the core. The virtual table
    67 instance and the \codeCFA{get_exception_vtable} function.
    68 
    69 Coroutines and threads need instances of \codeCFA{CoroutineCancelled} and
    70 \codeCFA{ThreadCancelled} respectively to use all of their functionality.
    71 When a new data type is declared with \codeCFA{coroutine} or \codeCFA{thread}
     67instance and the @get_exception_vtable@ function.
     68
     69Coroutines and threads need instances of @CoroutineCancelled@ and
     70@ThreadCancelled@ respectively to use all of their functionality.
     71When a new data type is declared with @coroutine@ or @thread@
    7272the forward declaration for the instance is created as well. The definition
    7373of the virtual table is created at the definition of the main function.
     
    7979function.
    8080
    81 The function is \codeC{__cfa__virtual_cast} and it is implemented in the
     81The function is @__cfa__virtual_cast@ and it is implemented in the
    8282standard library. It takes a pointer to the target type's virtual table and
    8383the object pointer being cast. The function is very simple, getting the
     
    8787
    8888For the generated code a forward decaration of the virtual works as follows.
    89 There is a forward declaration of \codeC{__cfa__virtual_cast} in every cfa
     89There is a forward declaration of @__cfa__virtual_cast@ in every cfa
    9090file so it can just be used. The object argument is the expression being cast
    9191so that is just placed in the argument list.
     
    110110often across functions.
    111111
    112 At a very basic level this can be done with \codeC{setjmp} \& \codeC{longjmp}
     112At a very basic level this can be done with @setjmp@ \& @longjmp@
    113113which simply move the top of the stack, discarding everything on the stack
    114114above a certain point. However this ignores all the clean-up code that should
     
    118118both of these problems.
    119119
    120 Libunwind, provided in \texttt{unwind.h} on most platorms, is a C library
     120Libunwind, provided in @unwind.h@ on most platorms, is a C library
    121121that provides \CPP style stack unwinding. Its operation is divided into two
    122122phases. The search phase -- phase 1 -- is used to scan the stack and decide
     
    142142
    143143GCC will generate an LSDA and attach its personality function with the
    144 \texttt{-fexceptions} flag. However this only handles the cleanup attribute.
     144@-fexceptions@ flag. However this only handles the cleanup attribute.
    145145This attribute is used on a variable and specifies a function that should be
    146146run when the variable goes out of scope. The function is passed a pointer to
     
    165165messages for special cases (some of which should never be used by the
    166166personality function) and error codes but unless otherwise noted the
    167 personality function should always return \codeC{_URC_CONTINUE_UNWIND}.
    168 
    169 The \codeC{version} argument is the verson of the implementation that is
     167personality function should always return @_URC_CONTINUE_UNWIND@.
     168
     169The @version@ argument is the verson of the implementation that is
    170170calling the personality function. At this point it appears to always be 1 and
    171171it will likely stay that way until a new version of the API is updated.
    172172
    173 The \codeC{action} argument is set of flags that tell the personality
     173The @action@ argument is set of flags that tell the personality
    174174function when it is being called and what it must do on this invocation.
    175175The flags are as follows:
    176176\begin{itemize}
    177 \item\codeC{_UA_SEARCH_PHASE}: This flag is set whenever the personality
     177\item@_UA_SEARCH_PHASE@: This flag is set whenever the personality
    178178function is called during the search phase. The personality function should
    179179decide if unwinding will stop in this function or not. If it does then the
    180 personality function should return \codeC{_URC_HANDLER_FOUND}.
    181 \item\codeC{_UA_CLEANUP_PHASE}: This flag is set whenever the personality
     180personality function should return @_URC_HANDLER_FOUND@.
     181\item@_UA_CLEANUP_PHASE@: This flag is set whenever the personality
    182182function is called during the cleanup phase. If no other flags are set this
    183183means the entire frame will be unwound and all cleanup code should be run.
    184 \item\codeC{_UA_HANDLER_FRAME}: This flag is set during the cleanup phase
     184\item@_UA_HANDLER_FRAME@: This flag is set during the cleanup phase
    185185on the function frame that found the handler. The personality function must
    186186prepare to return to normal code execution and return
    187 \codeC{_URC_INSTALL_CONTEXT}.
    188 \item\codeC{_UA_FORCE_UNWIND}: This flag is set if the personality function
     187@_URC_INSTALL_CONTEXT@.
     188\item@_UA_FORCE_UNWIND@: This flag is set if the personality function
    189189is called through a forced unwind call. Forced unwind only performs the
    190190cleanup phase and uses a different means to decide when to stop. See its
     
    192192\end{itemize}
    193193
    194 The \codeC{exception_class} argument is a copy of the \codeC{exception}'s
    195 \codeC{exception_class} field.
    196 
    197 The \codeC{exception} argument is a pointer to the user provided storage
     194The @exception_class@ argument is a copy of the @exception@'s
     195@exception_class@ field.
     196
     197The @exception@ argument is a pointer to the user provided storage
    198198object. It has two public fields, the exception class which is actually just
    199199a number that identifies the exception handling mechanism that created it and
     
    201201exception needs to
    202202
    203 The \codeC{context} argument is a pointer to an opaque type. This is passed
     203The @context@ argument is a pointer to an opaque type. This is passed
    204204to the many helper functions that can be called inside the personality
    205205function.
     
    218218functions traversing the stack new-to-old until a function finds a handler or
    219219the end of the stack is reached. In the latter case raise exception will
    220 return with \codeC{_URC_END_OF_STACK}.
     220return with @_URC_END_OF_STACK@.
    221221
    222222Once a handler has been found raise exception continues onto the the cleanup
     
    227227
    228228If an error is encountered raise exception will return either
    229 \codeC{_URC_FATAL_PHASE1_ERROR} or \codeC{_URC_FATAL_PHASE2_ERROR} depending
     229@_URC_FATAL_PHASE1_ERROR@ or @_URC_FATAL_PHASE2_ERROR@ depending
    230230on when the error occured.
    231231
     
    259259been unwound.
    260260
    261 Each time it is called the stop function should return \codeC{_URC_NO_REASON}
     261Each time it is called the stop function should return @_URC_NO_REASON@
    262262or transfer control directly to other code outside of libunwind. The
    263263framework does not provide any assistance here.
    264264
    265265Its arguments are the same as the paired personality function.
    266 The actions \codeC{_UA_CLEANUP_PHASE} and \codeC{_UA_FORCE_UNWIND} are always
     266The actions @_UA_CLEANUP_PHASE@ and @_UA_FORCE_UNWIND@ are always
    267267set when it is called. By the official standard that is all but both GCC and
    268268Clang add an extra action on the last call at the end of the stack:
    269 \codeC{_UA_END_OF_STACK}.
     269@_UA_END_OF_STACK@.
    270270
    271271\section{Exception Context}
     
    280280Each stack has its own exception context. In a purely sequental program, using
    281281only core Cforall, there is only one stack and the context is global. However
    282 if the library \texttt{libcfathread} is linked then there can be multiple
     282if the library @libcfathread@ is linked then there can be multiple
    283283stacks so they will each need their own.
    284284
    285285To handle this code always gets the exception context from the function
    286 \codeC{this_exception_context}. The main exception handling code is in
    287 \texttt{libcfa} and that library also defines the function as a weak symbol
    288 so it acts as a default. Meanwhile in \texttt{libcfathread} the function is
     286@this_exception_context@. The main exception handling code is in
     287@libcfa@ and that library also defines the function as a weak symbol
     288so it acts as a default. Meanwhile in @libcfathread@ the function is
    289289defined as a strong symbol that replaces it when the libraries are linked
    290290together.
    291291
    292 The version of the function defined in \texttt{libcfa} is very simple. It
     292The version of the function defined in @libcfa@ is very simple. It
    293293returns a pointer to a global static variable. With only one stack this
    294294global instance is associated with the only stack.
    295295
    296 The version of the function defined in \texttt{libcfathread} has to handle
     296The version of the function defined in @libcfathread@ has to handle
    297297more as there are multiple stacks. The exception context is included as
    298298part of the per-stack data stored as part of coroutines. In the cold data
    299299section, stored at the base of each stack, is the exception context for that
    300 stack. The \codeC{this_exception_context} uses the concurrency library to get
     300stack. The @this_exception_context@ uses the concurrency library to get
    301301the current coroutine and through it the cold data section and the exception
    302302context.
     
    323323to store the exception. Macros with pointer arthritic and type cast are
    324324used to move between the components or go from the embedded
    325 \codeC{_Unwind_Exception} to the entire node.
     325@_Unwind_Exception@ to the entire node.
    326326
    327327All of these nodes are strung together in a linked list. One linked list per
     
    347347C which is what the \CFA compiler outputs so a work-around is used.
    348348
    349 This work around is a function called \codeC{__cfaehm_try_terminate} in the
     349This work around is a function called @__cfaehm_try_terminate@ in the
    350350standard library. The contents of a try block and the termination handlers
    351351are converted into functions. These are then passed to the try terminate
     
    385385
    386386These nested functions and all other functions besides
    387 \codeC{__cfaehm_try_terminate} in \CFA use the GCC personality function and
    388 the \texttt{-fexceptions} flag to generate the LSDA. This allows destructors
     387@__cfaehm_try_terminate@ in \CFA use the GCC personality function and
     388the @-fexceptions@ flag to generate the LSDA. This allows destructors
    389389to be implemented with the cleanup attribute.
    390390
     
    401401
    402402The handler function does both the matching and catching. It tries each
    403 the condition of \codeCFA{catchResume} in order, top-to-bottom and until it
     403the condition of @catchResume@ in order, top-to-bottom and until it
    404404finds a handler that matches. If no handler matches then the function returns
    405405false. Otherwise the matching handler is run, if it completes successfully
    406 the function returns true. Rethrows, through the \codeCFA{throwResume;}
     406the function returns true. Rethrows, through the @throwResume;@
    407407statement, cause the function to return true.
    408408
     
    438438
    439439Cancellation also uses libunwind to do its stack traversal and unwinding,
    440 however it uses a different primary function \codeC{_Unwind_ForcedUnwind}.
     440however it uses a different primary function @_Unwind_ForcedUnwind@.
    441441Details of its interface can be found in the unwind section.
    442442
  • doc/theses/andrew_beach_MMath/unwinding.tex

    r79e261b7 rf28fdee  
    1010Even this is fairly simple if nothing needs to happen when the stack unwinds.
    1111Traditional C can unwind the stack by saving and restoring state (with
    12 \codeC{setjmp} \& \codeC{longjmp}). However many languages define actions that
     12@setjmp@ \& @longjmp@). However many languages define actions that
    1313have to be taken when something is removed from the stack, such as running
    14 a variable's destructor or a \codeCFA{try} statement's \codeCFA{finally}
     14a variable's destructor or a @try@ statement's @finally@
    1515clause. Handling this requires walking the stack going through each stack
    1616frame.
     
    2929
    3030\CFA uses two primary functions in libunwind to create most of its
    31 exceptional control-flow: \codeC{_Unwind_RaiseException} and
    32 \codeC{_Unwind_ForcedUnwind}.
     31exceptional control-flow: @_Unwind_RaiseException@ and
     32@_Unwind_ForcedUnwind@.
    3333Their operation is divided into two phases: search and clean-up. The search
    3434phase -- phase 1 -- is used to scan the stack but not unwinding it. The
     
    4444A personality function performs three tasks, although not all have to be
    4545present. The tasks performed are decided by the actions provided.
    46 \codeC{_Unwind_Action} is a bitmask of possible actions and an argument of
     46@_Unwind_Action@ is a bitmask of possible actions and an argument of
    4747this type is passed into the personality function.
    4848\begin{itemize}
    49 \item\codeC{_UA_SEARCH_PHASE} is passed in search phase and tells the
     49\item@_UA_SEARCH_PHASE@ is passed in search phase and tells the
    5050personality function to check for handlers. If there is a handler in this
    5151stack frame, as defined by the language, the personality function should
    52 return \codeC{_URC_HANDLER_FOUND}. Otherwise it should return
    53 \codeC{_URC_CONTINUE_UNWIND}.
    54 \item\codeC{_UA_CLEANUP_PHASE} is passed in during the clean-up phase and
     52return @_URC_HANDLER_FOUND@. Otherwise it should return
     53@_URC_CONTINUE_UNWIND@.
     54\item@_UA_CLEANUP_PHASE@ is passed in during the clean-up phase and
    5555means part or all of the stack frame is removed. The personality function
    5656should do whatever clean-up the language defines
    5757(such as running destructors/finalizers) and then generally returns
    58 \codeC{_URC_CONTINUE_UNWIND}.
    59 \item\codeC{_UA_HANDLER_FRAME} means the personality function must install
     58@_URC_CONTINUE_UNWIND@.
     59\item@_UA_HANDLER_FRAME@ means the personality function must install
    6060a handler. It is also passed in during the clean-up phase and is in addition
    6161to the clean-up action. libunwind provides several helpers for the personality
    6262function here. Once it is done, the personality function must return
    63 \codeC{_URC_INSTALL_CONTEXT}.
     63@_URC_INSTALL_CONTEXT@.
    6464\end{itemize}
    6565The personality function is given a number of other arguments. Some are for
    66 compatability and there is the \codeC{struct _Unwind_Context} pointer which
     66compatability and there is the @struct _Unwind_Context@ pointer which
    6767passed to many helpers to get information about the current stack frame.
    6868
     
    7272raise-exception but with some extras.
    7373The first it passes in an extra action to the personality function on each
    74 stack frame, \codeC{_UA_FORCE_UNWIND}, which means a handler cannot be
     74stack frame, @_UA_FORCE_UNWIND@, which means a handler cannot be
    7575installed.
    7676
     
    8383stack frames have been removed. By the standard API this is marked by setting
    8484the stack pointer inside the context passed to the stop function. However both
    85 GCC and Clang add an extra action for this case \codeC{_UA_END_OF_STACK}.
     85GCC and Clang add an extra action for this case @_UA_END_OF_STACK@.
    8686
    8787Each time function the stop function is called it can do one or two things.
    88 When it is not the end of the stack it can return \codeC{_URC_NO_REASON} to
     88When it is not the end of the stack it can return @_URC_NO_REASON@ to
    8989continue unwinding.
    9090% Is there a reason that NO_REASON is used instead of CONTINUE_UNWIND?
     
    113113
    114114The stop function is very simple. It checks the end of stack flag to see if
    115 it is finished unwinding. If so, it calls \codeC{exit} to end the process,
     115it is finished unwinding. If so, it calls @exit@ to end the process,
    116116otherwise it returns with no-reason to continue unwinding.
    117117% Yeah, this is going to have to change.
     
    128128location of the instruction pointer and stack layout, which varies with
    129129compiler and optimization levels. So for frames where there are only
    130 destructors, GCC's attribute cleanup with the \texttt{-fexception} flag is
     130destructors, GCC's attribute cleanup with the @-fexception@ flag is
    131131sufficient to handle unwinding.
    132132
    133133The only functions that require more than that are those that contain
    134 \codeCFA{try} statements. A \codeCFA{try} statement has a \codeCFA{try}
    135 clause, some number of \codeCFA{catch} clauses and \codeCFA{catchResume}
    136 clauses and may have a \codeCFA{finally} clause. Of these only \codeCFA{try}
    137 statements with \codeCFA{catch} clauses need to be transformed and only they
    138 and the \codeCFA{try} clause are involved.
     134@try@ statements. A @try@ statement has a @try@
     135clause, some number of @catch@ clauses and @catchResume@
     136clauses and may have a @finally@ clause. Of these only @try@
     137statements with @catch@ clauses need to be transformed and only they
     138and the @try@ clause are involved.
    139139
    140 The \codeCFA{try} statement is converted into a series of closures which can
     140The @try@ statement is converted into a series of closures which can
    141141access other parts of the function according to scoping rules but can be
    142 passed around. The \codeCFA{try} clause is converted into the try functions,
    143 almost entirely unchanged. The \codeCFA{catch} clauses are converted into two
     142passed around. The @try@ clause is converted into the try functions,
     143almost entirely unchanged. The @catch@ clauses are converted into two
    144144functions; the match function and the catch function.
    145145
     
    153153runs the handler's body.
    154154
    155 These three functions are passed to \codeC{try_terminate}. This is an
     155These three functions are passed to @try_terminate@. This is an
    156156% Maybe I shouldn't quote that, it isn't its actual name.
    157157internal hand-written function that has its own personality function and
     
    167167handler was found in this frame. If it was then the personality function
    168168installs the handler, which is setting the instruction pointer in
    169 \codeC{try_terminate} to an otherwise unused section that calls the catch
     169@try_terminate@ to an otherwise unused section that calls the catch
    170170function, passing it the current exception and handler index.
    171 \codeC{try_terminate} returns as soon as the catch function returns.
     171@try_terminate@ returns as soon as the catch function returns.
    172172
    173173At this point control has returned to normal control flow.
Note: See TracChangeset for help on using the changeset viewer.