Index: doc/theses/andrew_beach_MMath/cfalab.sty =================================================================== --- doc/theses/andrew_beach_MMath/cfalab.sty (revision 0c4df433f787efae5c9a00134cd7759d530cd054) +++ doc/theses/andrew_beach_MMath/cfalab.sty (revision 9d7e5cb8d333e693f8ced35925a418c730d01e1a) @@ -1,3 +1,4 @@ % Package for CFA Research Lab. +% (Now more a personal collection and testing grounds for common.sty.) % % This is a collection of commands everyone working on CFA related documents @@ -56,4 +57,7 @@ \newrobustcmd*\codeCpp[1]{\lstinline[language=C++]{#1}} \newrobustcmd*\codePy[1]{\lstinline[language=Python]{#1}} +% \code{}{} +% Use the listings package to format the snipit of in . +\newrobustcmd*\code[2]{\lstinline[language=#1]{#2}} % \begin{cfa}[] Index: doc/theses/andrew_beach_MMath/implement.tex =================================================================== --- doc/theses/andrew_beach_MMath/implement.tex (revision 0c4df433f787efae5c9a00134cd7759d530cd054) +++ doc/theses/andrew_beach_MMath/implement.tex (revision 9d7e5cb8d333e693f8ced35925a418c730d01e1a) @@ -14,97 +14,129 @@ \subsection{Virtual Type} -Virtual types only have one change to their structure, the addition of a -pointer to the virtual table. This is always the first field so that -if it is cast to a supertype the field's location is still known. - -This field is set as part of all new generated constructors. -\todo{They only come as part exceptions and don't work.} -After the object is created the field is constant. - -However it can be read from, internally it is just a regular field called -@virtual_table@. Dereferencing it gives the virtual table and access to the -type's virtual members. +Virtual types only have one change to their structure: the addition of a +pointer to the virtual table, which is called the \emph{virtual-table pointer}. +Internally, the field is called @virtual_table@. +The field is fixed after construction. It is always the first field in the +structure so that its location is always known. +\todo{Talk about constructors for virtual types (after they are working).} + +This is what binds an instance of a virtual type to a virtual table. This +pointer can be used as an identity check. It can also be used to access the +virtual table and the virtual members there. + +\subsection{Type Id} +Every virtual type has a unique id. +Type ids can be compared for equality (the types reperented are the same) +or used to access the type's type information. +The type information currently is only the parent's type id or, if the +type has no parent, zero. + +The id's are implemented as pointers to the type's type information instance. +Derefencing the pointer gets the type information. +By going back-and-forth between the type id and +the type info one can find every ancestor of a virtual type. +It also pushes the issue of creating a unique value (for +the type id) to the problem of creating a unique instance (for type +information) which the linker can solve. + +Advanced linker support is required because there is no place that appears +only once to attach the type information to. There should be one structure +definition but it is included in multiple translation units. Each virtual +table definition should be unique but there are an arbitrary number of thoses. +So the special section prefix \texttt{.gnu.linkonce} is used. +With a unique suffix (making the entire section name unique) the linker will +remove multiple definition making sure only one version exists after linking. +Then it is just a matter of making sure there is a unique name for each type. + +This is done in three phases. +The first phase is to generate a new structure definition to store the type +information. The layout is the same in each case, just the parent's type id, +but the types are changed. +The structure's name is change, it is based off the virtual type's name, and +the type of the parent's type id. +If the virtual type is polymorphic then the type information structure is +polymorphic as well, with the same polymorphic arguments. + +The second phase is to generate an instance of the type information with a +almost unique name, generated by mangling the virtual type name. + +The third phase is implicit with \CFA's overloading scheme. \CFA mangles +names with type information so that all of the symbols exported to the linker +are unique even if in \CFA code they are the same. Having two declarations +with the same name and same type is forbidden because it is impossible for +overload resolution to pick between them. This is why a unique type is +generated for each virtual type. +Polymorphic information is included in this mangling so polymorphic +types will have seperate instances for each set of polymorphic arguments. + +\begin{cfa} +struct /* type name */ { + /* parent type name */ const * parent; +}; + +__attribute__((section(".gnu.linkonce./* instance name */"))) +/* type name */ const /* instance name */ = { + &/* parent instance name */, +}; +\end{cfa} \subsection{Virtual Table} -Every time a virtual type is defined the new virtual table type must also be -defined. - -The unique instance is important because the address of the virtual table -instance is used as the identifier for the virtual type. So a pointer to the -virtual table and the ID for the virtual type are interchangable. -\todo{Unique instances might be going so we will have to talk about the new -system instead.} - -The first step in putting it all together is to create the virtual table type. -The virtual table type is just a structure and can be described in terms of -its fields. The first field is always the parent type ID (or a pointer to -the parent virtual table) or 0 (the null pointer). -Next are other fields on the parent virtual table are repeated. -Finally are the fields used to store any new virtual members of the new -The virtual type - -The virtual system is accessed through a private constant field inserted at the -beginning of every virtual type, called the virtual-table pointer. This field -points at a type's virtual table and is assigned during the object's -construction. The address of a virtual table acts as the unique identifier for -the virtual type, and the first field of a virtual table is a pointer to the -parent virtual-table or @0p@. The remaining fields are duplicated from the -parent tables in this type's inheritance chain, followed by any fields this type -introduces. Parent fields are duplicated so they can be changed (all virtual -members are overridable), so that references to the dispatched type -are replaced with the current virtual type. -% These are always taken by pointer or reference. - -% Simple ascii diragram: -\begin{verbatim} -parent_pointer \ -parent_field0 | -... | Same layout as parent. -parent_fieldN / +Each virtual type has a virtual table type that stores its type id and +virtual members. +Each virtual type instance is bound to a table instance that is filled with +the values of virtual members. +Both the layout of the fields and their value are decided by the rules given +below. + +The layout always comes in three parts. +The first section is just the type id at the head of the table. It is always +there to ensure that +The second section are all the virtual members of the parent, in the same +order as they appear in the parent's virtual table. Note that the type may +change slightly as references to the ``this" will change. This is limited to +inside pointers/references and via function pointers so that the size (and +hence the offsets) are the same. +The third section is similar to the second except that it is the new virtual +members introduced at this level in the hierarchy. + +\begin{figure} +\begin{cfa} +type_id +parent_field0 +... +parent_fieldN child_field0 ... child_fieldN -\end{verbatim} -\todo{Refine the diagram} - -% For each virtual type, a virtual table is constructed. This is both a new type -% and an instance of that type. Other instances of the type could be created -% but the system doesn't use them. So this section will go over the creation of -% the type and the instance. - -A virtual table is created when the virtual type is created. The name of the -type is created by mangling the name of the base type. The name of the instance -is also generated by name mangling. The fields are initialized automatically. -The parent field is initialized by getting the type of the parent field and -using that to calculate the mangled name of the parent's virtual table type. -There are two special fields that are included like normal fields but have -special initialization rules: the @size@ field is the type's size and is -initialized with a @sizeof@ expression, the @align@ field is the type's -alignment and uses an @alignof@ expression. The remaining fields are resolved -to a name matching the field's name and type using the normal visibility and -overload resolution rules of the type system. - -These operations are split up into several groups depending on where they take -place which varies for monomorphic and polymorphic types. The first devision is -between the declarations and the definitions. Declarations, such as a function -signature or a aggregate's name, must always be visible but may be repeated in -the form of forward declarations in headers. Definitions, such as function -bodies and a aggregate's layout, can be separately compiled but must occur -exactly once in a source file. - -\begin{sloppypar} -The declarations include the virtual type definition and forward declarations -of the virtual table instance, constructor, message function and -@get_exception_vtable@. The definition includes the storage and initialization -of the virtual table instance and the bodies of the three functions. -\end{sloppypar} - -Monomorphic instances put all of these two groups in one place each. -Polymorphic instances also split out the core declarations and definitions from -the per-instance information. The virtual table type and most of the functions -are polymorphic so they are all part of the core. The virtual table instance -and the @get_exception_vtable@ function. - -\begin{sloppypar} +\end{cfa} +\caption{Virtual Table Layout} +\label{f:VirtualTableLayout} +\todo*{Improve the Virtual Table Layout diagram.} +\end{figure} + +The first and second sections together mean that every virtual table has a +prefix that has the same layout and types as its parent virtual table. +This, combined with the fixed offset to the virtual table pointer, means that +for any virtual type it doesn't matter if we have it or any of its +descendants, it is still always safe to access the virtual table through +the virtual table pointer. +From there it is safe to check the type id to identify the exact type of the +underlying object, access any of the virtual members and pass the object to +any of the method-like virtual members. +\todo{Introduce method-like virtual members.} + +When a virtual table is declared the user decides where to declare it and its +name. The initialization of the virtual table is entirely automatic based on +the context of the declaration. + +The type id is always fixed, each virtual table type will always have one +exactly one possible type id. +The virtual members are usually filled in by resolution. The best match for +a given name and type at the declaration site is filled in. +There are two exceptions to that rule: the @size@ field is the type's size +and is set to the result of a @sizeof@ expression, the @align@ field is the +type's alignment and similarly uses an @alignof@ expression. + +\subsubsection{Concurrency Integration} Coroutines and threads need instances of @CoroutineCancelled@ and @ThreadCancelled@ respectively to use all of their functionality. When a new @@ -112,5 +144,5 @@ the instance is created as well. The definition of the virtual table is created at the definition of the main function. -\end{sloppypar} +\todo{Add an example with code snipits.} \subsection{Virtual Cast} @@ -119,5 +151,6 @@ % The C-cast is just to make sure the generated code is correct so the rest of % the section is about that function. -The function is +The function is implemented in the standard library and has the following +signature: \begin{cfa} void * __cfa__virtual_cast( @@ -125,26 +158,18 @@ struct __cfa__parent_vtable const * const * child ); \end{cfa} -and it is implemented in the standard library. The structure reperents the -head of a vtable which is the pointer to the parent virtual table. The -@parent@ points directly at the parent type virtual table while the @child@ -points at the object of the (possibe) child type. - -In terms of the virtual cast expression, @parent@ comes from looking up the -type being cast to and @child@ is the result of the expression being cast. -Because the complier outputs C code, some type C type casts are also used. -The last bit of glue is an map that saves every virtual type the compiler -sees. This is used to check the type used in a virtual cast is a virtual -type and to get its virtual table. -(It also checks for conflicting definitions.) - -Inside the function it is a simple conditional. If the type repersented by -@parent@ is or is an ancestor of the type repersented by @*child@ (it -requires one more level of derefence to pass through the object) then @child@ -is returned, otherwise the null pointer is returned. - -The check itself is preformed is a simple linear search. If the child -virtual table or any of its ancestors (which are retreved through the first -field of every virtual table) are the same as the parent virtual table then -the cast succeeds. +\todo{Get rid of \_\_cfa\_\_parent\_vtable in the standard library and then +the document.} +The type id of target type of the virtual cast is passed in as @parent@ and +the cast target is passed in as @child@. + +For C generation both arguments and the result are wrapped with type casts. +There is also an internal store inside the compiler to make sure that the +target type is a virtual type. +% It also checks for conflicting definitions. + +The virtual cast either returns the original pointer as a new type or null. +So the function just does the parent check and returns the approprate value. +The parent check is a simple linear search of child's ancestors using the +type information. \section{Exceptions} @@ -161,28 +186,25 @@ Stack unwinding is the process of removing stack frames (activations) from the -stack. On function entry and return, unwinding is handled directly by the code -embedded in the function. Usually, the stack-frame size is known statically -based on parameter and local variable declarations. For dynamically-sized -local variables, a runtime computation is necessary to know the frame -size. Finally, a function's frame-size may change during execution as local -variables (static or dynamic sized) go in and out of scope. +stack. On function entry and return, unwinding is handled directly by the +call/return code embedded in the function. +In many cases the position of the instruction pointer (relative to parameter +and local declarations) is enough to know the current size of the stack +frame. + +Usually, the stack-frame size is known statically based on parameter and +local variable declarations. Even with dynamic stack-size the information +to determain how much of the stack has to be removed is still contained +within the function. Allocating/deallocating stack space is usually an $O(1)$ operation achieved by bumping the hardware stack-pointer up or down as needed. - -Unwinding across multiple stack frames is more complex because individual stack -management code associated with each frame is bypassed. That is, the location -of a function's frame-management code is largely unknown and dispersed -throughout the function, hence the current frame size managed by that code is -also unknown. Hence, code unwinding across frames does not have direct -knowledge about what is on the stack, and hence, how much of the stack needs to -be removed. - -% At a very basic level this can be done with @setjmp@ \& @longjmp@ which simply -% move the top of the stack, discarding everything on the stack above a certain -% point. However this ignores all the cleanup code that should be run when -% certain sections of the stack are removed (for \CFA these are from destructors -% and finally clauses) and also requires that the point to which the stack is -% being unwound is known ahead of time. libunwind is used to address both of -% these problems. +Constructing/destructing values on the stack takes longer put in terms of +figuring out what needs to be done is of similar complexity. + +Unwinding across multiple stack frames is more complex because that +information is no longer contained within the current function. +With seperate compilation a function has no way of knowing what its callers +are so it can't know how large those frames are. +Without altering the main code path it is also hard to pass that work off +to the caller. The traditional unwinding mechanism for C is implemented by saving a snap-shot @@ -191,19 +213,18 @@ reseting to a snap-shot of an arbitrary but existing function frame on the stack. It is up to the programmer to ensure the snap-shot is valid when it is -reset, making this unwinding approach fragile with potential errors that are -difficult to debug because the stack becomes corrupted. - -However, many languages define cleanup actions that must be taken when objects -are deallocated from the stack or blocks end, such as running a variable's -destructor or a @try@ statement's @finally@ clause. Handling these mechanisms -requires walking the stack and checking each stack frame for these potential -actions. - -For exceptions, it must be possible to walk the stack frames in search of @try@ -statements to match and execute a handler. For termination exceptions, it must -also be possible to unwind all stack frames from the throw to the matching -catch, and each of these frames must be checked for cleanup actions. Stack -walking is where most of the complexity and expense of exception handling -appears. +reset and that all required clean-up from the unwound stacks is preformed. +This approach is fragile and forces a work onto the surounding code. + +With respect to that work forced onto the surounding code, +many languages define clean-up actions that must be taken when certain +sections of the stack are removed. Such as when the storage for a variable +is removed from the stack or when a try statement with a finally clause is +(conceptually) popped from the stack. +None of these should be handled by the user, that would contradict the +intention of these features, so they need to be handled automatically. + +To safely remove sections of the stack the language must be able to find and +run these clean-up actions even when removing multiple functions unknown at +the beginning of the unwinding. One of the most popular tools for stack management is libunwind, a low-level @@ -226,5 +247,5 @@ LSDA can contain any information but conventionally it is a table with entries representing regions of the function and what has to be done there during -unwinding. These regions are bracketed by the instruction pointer. If the +unwinding. These regions are bracketed by instruction addresses. If the instruction pointer is within a region's start/end, then execution is currently executing in that region. Regions are used to mark out the scopes of objects @@ -238,18 +259,19 @@ The GCC compilation flag @-fexceptions@ causes the generation of an LSDA and -attaches its personality function. However, this +attaches a personality function to each function. +In plain C (which \CFA currently compiles down to) this flag only handles the cleanup attribute: -\todo{Peter: What is attached? Andrew: It uses the .cfi\_personality directive -and that's all I know.} \begin{cfa} void clean_up( int * var ) { ... } int avar __attribute__(( cleanup(clean_up) )); \end{cfa} -which is used on a variable and specifies a function, in this case @clean_up@, -run when the variable goes out of scope. -The function is passed a pointer to the object being removed from the stack -so it can be used to mimic destructors. -However, this feature cannot be used to mimic @try@ statements as it cannot -control the unwinding. +The attribue is used on a variable and specifies a function, +in this case @clean_up@, run when the variable goes out of scope. +This is enough to mimic destructors, but not try statements which can effect +the unwinding. + +To get full unwinding support all of this has to be done directly with +assembly and assembler directives. Partiularly the cfi directives +\texttt{.cfi\_lsda} and \texttt{.cfi\_personality}. \subsection{Personality Functions} @@ -268,5 +290,5 @@ \end{lstlisting} The @action@ argument is a bitmask of possible actions: -\begin{enumerate} +\begin{enumerate}[topsep=5pt] \item @_UA_SEARCH_PHASE@ specifies a search phase and tells the personality function @@ -295,11 +317,14 @@ The @exception_class@ argument is a copy of the -\lstinline[language=C]|exception|'s @exception_class@ field. - -The \lstinline[language=C]|exception| argument is a pointer to the user -provided storage object. It has two public fields, the exception class, which -is actually just a number, identifying the exception handling mechanism that -created it, and the cleanup function. The cleanup function is called if -required by the exception. +\code{C}{exception}'s @exception_class@ field. +This a number that identifies the exception handling mechanism that created +the + +The \code{C}{exception} argument is a pointer to the user +provided storage object. It has two public fields: the @exception_class@, +which is described above, and the @exception_cleanup@ function. +The clean-up function is used by the EHM to clean-up the exception if it +should need to be freed at an unusual time, it takes an argument that says +why it had to be cleaned up. The @context@ argument is a pointer to an opaque type passed to helper @@ -309,5 +334,5 @@ that can be passed several places in libunwind. It includes a number of messages for special cases (some of which should never be used by the -personality function) and error codes but unless otherwise noted the +personality function) and error codes. However, unless otherwise noted, the personality function should always return @_URC_CONTINUE_UNWIND@. @@ -324,6 +349,6 @@ @_URC_END_OF_STACK@. -Second, when a handler is matched, raise exception continues onto the cleanup -phase. +Second, when a handler is matched, raise exception moves to the clean-up +phase and walks the stack a second time. Once again, it calls the personality functions of each stack frame from newest to oldest. This pass stops at the stack frame containing the matching handler. @@ -338,5 +363,5 @@ Forced Unwind is the other central function in libunwind. \begin{cfa} -_Unwind_Reason_Code _Unwind_ForcedUnwind( _Unwind_Exception *, +_Unwind_Reason_Code _Unwind_ForcedUnwind(_Unwind_Exception *, _Unwind_Stop_Fn, void *); \end{cfa} @@ -380,8 +405,8 @@ Each stack must have its own exception context. In a sequential \CFA program, there is only one stack with a single global exception-context. However, when -the library @libcfathread@ is linked, there are multiple stacks where each +the library @libcfathread@ is linked, there are multiple stacks and each needs its own exception context. -General access to the exception context is provided by function +The exception context should be retrieved by calling the function @this_exception_context@. For sequential execution, this function is defined as a weak symbol in the \CFA system-library, @libcfa@. When a \CFA program is @@ -390,7 +415,7 @@ The sequential @this_exception_context@ returns a hard-coded pointer to the -global execption context. +global exception context. The concurrent version adds the exception context to the data stored at the -base of each stack. When @this_exception_context@ is called it retrieves the +base of each stack. When @this_exception_context@ is called, it retrieves the active stack and returns the address of the context saved there. @@ -399,6 +424,6 @@ % catches. Talk about GCC nested functions. -Termination exceptions use libunwind heavily because it matches the intended -use from \Cpp exceptions closely. The main complication for \CFA is that the +\CFA termination exceptions use libunwind heavily because they match \Cpp +\Cpp exceptions closely. The main complication for \CFA is that the compiler generates C code, making it very difficult to generate the assembly to form the LSDA for try blocks or destructors. @@ -411,5 +436,5 @@ per-exception storage. -[Quick ASCII diagram to get started.] +\begin{figure} \begin{verbatim} Fixed Header | _Unwind_Exception <- pointer target @@ -420,7 +445,11 @@ V ... \end{verbatim} - -Exceptions are stored in variable-sized blocks. -The first component is a fixed sized data structure that contains the +\caption{Exception Layout} +\label{f:ExceptionLayout} +\end{figure} +\todo*{Convert the exception layout to an actual diagram.} + +Exceptions are stored in variable-sized blocks (see \vref{f:ExceptionLayout}). +The first component is a fixed-sized data structure that contains the information for libunwind and the exception system. The second component is an area of memory big enough to store the exception. Macros with pointer arthritic @@ -428,5 +457,58 @@ @_Unwind_Exception@ to the entire node. -All of these nodes are linked together in a list, one list per stack, with the +Multipe exceptions can exist at the same time because exceptions can be +raised inside handlers, destructors and finally blocks. +Figure~\vref{f:MultipleExceptions} shows a program that has multiple +exceptions active at one time. +Each time an exception is thrown and caught the stack unwinds and the finally +clause runs. This will throw another exception (until @num_exceptions@ gets +high enough) which must be allocated. The previous exceptions may not be +freed because the handler/catch clause has not been run. +So the EHM must keep them alive while it allocates exceptions for new throws. + +\begin{figure} +\centering +% Andrew: Figure out what these do and give them better names. +\newsavebox{\myboxA} +\newsavebox{\myboxB} +\begin{lrbox}{\myboxA} +\begin{lstlisting}[language=CFA,{moredelim=**[is][\color{red}]{@}{@}}] +unsigned num_exceptions = 0; +void throws() { + try { + try { + ++num_exceptions; + throw (Example){table}; + } finally { + if (num_exceptions < 3) { + throws(); + } + } + } catch (exception_t *) { + --num_exceptions; + } +} +int main() { + throws(); +} +\end{lstlisting} +\end{lrbox} + +\begin{lrbox}{\myboxB} +\begin{lstlisting} +\end{lstlisting} +\end{lrbox} + +{\usebox\myboxA} +\hspace{25pt} +{\usebox\myboxB} + +\caption{Multiple Exceptions} +\label{f:MultipleExceptions} +\end{figure} +\todo*{Work on multiple exceptions code sample.} + +All exceptions are stored in nodes which are then linked together in lists, +one list per stack, with the list head stored in the exception context. Within each linked list, the most recently thrown exception is at the head followed by older thrown @@ -439,7 +521,7 @@ exception, the copy function, and the free function, so they are specific to an exception type. The size and copy function are used immediately to copy an -exception into managed memory. After the exception is handled the free function -is used to clean up the exception and then the entire node is passed to free -so the memory can be given back to the heap. +exception into managed memory. After the exception is handled, the free +function is used to clean up the exception and then the entire node is +passed to free so the memory can be given back to the heap. \subsection{Try Statements and Catch Clauses} @@ -454,9 +536,10 @@ calls them. Because this function is known and fixed (and not an arbitrary function that -happens to contain a try statement) this means the LSDA can be generated ahead +happens to contain a try statement), the LSDA can be generated ahead of time. Both the LSDA and the personality function are set ahead of time using -embedded assembly. This is handcrafted using C @asm@ statements and contains +embedded assembly. This assembly code is handcrafted using C @asm@ statements +and contains enough information for the single try statement the function repersents. @@ -487,24 +570,41 @@ nested functions and all other functions besides @__cfaehm_try_terminate@ in \CFA use the GCC personality function and the @-fexceptions@ flag to generate -the LSDA. This allows destructors to be implemented with the cleanup attribute. +the LSDA. +Using this pattern, \CFA implements destructors with the cleanup attribute. +\todo{Add an example of the conversion from try statement to functions.} \section{Resumption} % The stack-local data, the linked list of nodes. -Resumption simple to implement because there is no stack unwinding. The -resumption raise uses a list of nodes for its stack traversal. The head of the -list is stored in the exception context. The nodes in the list have a pointer -to the next node and a pointer to the handler function. - -A resumption raise traverses this list. At each node the handler function is -called, passing the exception by pointer. It returns true if the exception is -handled and false otherwise. - -The handler function does both the matching and handling. It computes the -condition of each @catchResume@ in top-to-bottom order, until it finds a -handler that matches. If no handler matches then the function returns -false. Otherwise the matching handler is run; if it completes successfully, the -function returns true. Rethrowing, through the @throwResume;@ statement, -causes the function to return true. +Resumption simpler to implement than termination +because there is no stack unwinding. +Instead of storing the data in a special area using assembly, +there is just a linked list of possible handlers for each stack, +with each node on the list reperenting a try statement on the stack. + +The head of the list is stored in the exception context. +The nodes are stored in order, with the more recent try statements closer +to the head of the list. +Instead of traversing the stack resumption handling traverses the list. +At each node the EHM checks to see if the try statement the node repersents +can handle the exception. If it can, then the exception is handled and +the operation finishes, otherwise the search continues to the next node. +If the search reaches the end of the list without finding a try statement +that can handle the exception the default handler is executed and the +operation finishes. + +In each node is a handler function which does most of the work there. +The handler function is passed the raised the exception and returns true +if the exception is handled and false if it cannot be handled here. + +For each @catchResume@ clause the handler function will: +check to see if the raised exception is a descendant type of the declared +exception type, if it is and there is a conditional expression then it will +run the test, if both checks pass the handling code for the clause is run +and the function returns true, otherwise it moves onto the next clause. +If this is the last @catchResume@ clause then instead of moving onto +the next clause the function returns false as no handler could be found. + +\todo{Diagram showing a try statement being converted into resumption handlers.} % Recursive Resumption Stuff: @@ -512,5 +612,5 @@ the stack already examined, is accomplished by updating the front of the list as the -search continues. Before the handler at a node is called the head of the list +search continues. Before the handler at a node is called, the head of the list is updated to the next node of the current node. After the search is complete, successful or not, the head of the list is reset. @@ -525,4 +625,5 @@ stack -- the first one points over all the checked handlers -- and the ordering is maintained. +\todo{Add a diagram for resumption marking.} \label{p:zero-cost} @@ -541,10 +642,11 @@ \section{Finally} % Uses destructors and GCC nested functions. -Finally clauses is placed into a GCC nested-function with a unique name, and no -arguments or return values. This nested function is then set as the cleanup +A finally clause is placed into a GCC nested-function with a unique name, +and no arguments or return values. +This nested function is then set as the cleanup function of an empty object that is declared at the beginning of a block placed around the context of the associated @try@ statement. -The rest is handled by GCC. The try block and all handlers are inside the +The rest is handled by GCC. The try block and all handlers are inside this block. At completion, control exits the block and the empty object is cleaned up, which runs the function that contains the finally code. @@ -554,6 +656,6 @@ Cancellation also uses libunwind to do its stack traversal and unwinding, -however it uses a different primary function @_Unwind_ForcedUnwind@. Details -of its interface can be found in the \vref{s:ForcedUnwind}. +however it uses a different primary function: @_Unwind_ForcedUnwind@. Details +of its interface can be found in the Section~\vref{s:ForcedUnwind}. The first step of cancellation is to find the cancelled stack and its type: @@ -561,10 +663,10 @@ pointer and the current thread pointer, and every thread stores a pointer to its main coroutine and the coroutine it is currently executing. - -So if the active thread's main and current coroutine are the same. If they -are then the current stack is a thread stack, otherwise it is a coroutine -stack. If it is a thread stack then an equality check with the stored main -thread pointer and current thread pointer is enough to tell if the current -thread is the main thread or not. +\todo*{Consider adding a description of how threads are coroutines.} + +If a the current thread's main and current coroutines are the same then the +current stack is a thread stack. Furthermore it is easy to compare the +current thread to the main thread to see if they are the same. And if this +is not a thread stack then it must be a coroutine stack. However, if the threading library is not linked, the sequential execution is on @@ -575,6 +677,6 @@ Regardless of how the stack is chosen, the stop function and parameter are passed to the forced-unwind function. The general pattern of all three stop -functions is the same: they continue unwinding until the end of stack when they -do there primary work. +functions is the same: they continue unwinding until the end of stack and +then preform their transfer. For main stack cancellation, the transfer is just a program abort.