[project @ 1999-01-06 11:29:44 by simonm]

updates

1 files changed, 83 insertions, 64 deletions

diff --git a/docs/rts/rts.verb b/docs/rts/rts.verb
index fb996e2665..0f58ca6c68 100644
--- a/docs/rts/rts.verb
+++ b/docs/rts/rts.verb
@@ -69,7 +69,7 @@ Alastair Reid \\ Yale University}
 This document describes the GHC/Hugs run-time system.  It serves as 
 a Glasgow/Yale/Nottingham ``contract'' about what the RTS does.
 
-\Subsection{New features compared to GHC 2.04}{new-features}
+\Subsection{New features compared to GHC 3.xx}{new-features}
 
 \begin{itemize}
 \item The RTS supports mixed compiled/interpreted execution, so
@@ -99,13 +99,14 @@ architectures.  It has been partly replaced by unboxed tuples
 explicitly state where results should be returned in registers (or on
 the stack) instead of on the heap.
 
-\item
+\item Exceptions are supported by the RTS.
+
+\item Weak Pointers generalise the previously available Foreign Object
+interface.
 
-Lazy black-holing has been replaced by eager black-holing.  The
-problem with lazy black-holing is that it leaves slop in the heap
-which conflicts with the use of a mostly-copying collector.
-\ToDo{Why?  I think we can still do lazy black holing without leaving
-slop (SDM)}
+\item The garbage collector supports a number of new features,
+including a dynamically resizable heap and multiple generations with
+aging within a generation.
 
 \end{itemize}
 
@@ -120,12 +121,6 @@ The SM could tune the size of the allocation arena, the number of
 generations, etc taking into account residency, GC rate and page fault
 rate.
 
-\item
-There should be no need to specify the amnount of stack/heap space to
-allocate when you started a program - let it just take as much or as
-little as it wants.  (It might be useful to be able to specify maximum
-sizes and to be able to suggest an initial size.)
-
 \item 
 We could trigger a GC when all threads are blocked waiting for IO if
 the allocation arena (or some of the generations) are nearly full.
@@ -470,12 +465,11 @@ All heap objects look like this:
 The headers vary between different kinds of object but they all start
 with a pointer to a pair consisting of an \emph{info table} and some
 \emph{entry code}.  The info table is used both by the evaluators and
-by the storage manager and contains an @INFO_TYPE@ field which
-identifies which kind of heap object uses it and determines the
-interpretation of the payload and of the other fields of the info
-table.  The entry code is some machine code used by the machine code
-evaluator to evaluate closures and raises an error for other kinds of
-objects.
+by the storage manager and contains a @type@ field which identifies
+which kind of heap object uses it and determines the interpretation of
+the payload and of the other fields of the info table.  The entry code
+is some machine code used by the machine code evaluator to evaluate
+closures and raises an error for other kinds of objects.
 
 The major kinds of heap object used are as follows.  (For simplicity,
 this description omits certain optimisations and extra fields required
@@ -493,14 +487,14 @@ constructor is stored in the info table.
 \end{tabular}
 \end{center}
 
-\item[Primitive objects] are used to represent objects with unpointed
+\item[Primitive objects] are used to represent objects with unlifted
 types which are too large to fit in a register (or stack slot) or for
 which sharing must be preserved.  Primitive objects include large
 objects such as multiple precision integers and immutable arrays and
 mutable objects such as mutable arrays, mutable variables, MVar's,
-IVar's and foreign object pointers.  Since unpointed objects are not
-pointed, they cannot be entered.  Their payload varies according to
-the kind of object.
+IVar's and foreign object pointers.  Since primitive objects are not
+lifted, they cannot be entered.  Their payload varies according to the
+kind of object.
 
 \item[Function closures] are used to represent functions.  Their
 payload (if any) consists of the free variables of the function.
@@ -516,11 +510,10 @@ Function closures are only generated by the machine code compiler.
 \item[Thunks] are used to represent unevaluated expressions which will
 be updated with their result.  Their payload (if any) consists of the
 free variables of the function.  The entry code for a thunk starts by
-pushing an \emph{update frame} onto the stack and overwriting the
-thunk with a \emph{black hole} (see Black Holes, below).  When
-evaluation of the thunk completes, the update frame will cause the
-thunk to be overwritten again with an \emph{indirection} to the result
-of the thunk, which is always a constructor or a partial application.
+pushing an \emph{update frame} onto the stack.  When evaluation of the
+thunk completes, the update frame will cause the thunk to be
+overwritten again with an \emph{indirection} to the result of the
+thunk, which is always a constructor or a partial application.
 
 \begin{center}
 \begin{tabular}{|l|l|l|l|}\hline
@@ -584,14 +577,18 @@ When evaluation of the black-holed closure completes, the black hole
 is overwritten with an indirection to the result of the closure and
 any blocked threads are restored to the runnable queue.
 
+Closures are overwritten by black-holes during a ``lazy black-holing''
+phase which runs on each thread when it returns to the scheduler.
+\ToDo{section describing lazy black-holing}.
+
 \begin{center}
 \begin{tabular}{|l|l|l|l|}\hline
-@BH@ & \emph{Blocked threads} \\ \hline
+@BLACKHOLE@ & \emph{Blocked threads} \\ \hline
 \end{tabular}
 \end{center}
 
 \ToDo{In a single threaded system, it's trivial to detect infinite
-loops: reentering a BH is always an error.  How easy is it in a
+loops: reentering a BLACKHOLE is always an error.  How easy is it in a
 multi-threaded system?}
 
 \item[Indirections] are used to update an unevaluated closure with its
@@ -608,17 +605,18 @@ an update in place.)
 
 Indirections needn't always point to a closure in WHNF.  They can
 point to a chain of indirections which point to an evaluated closure.
-When revertible black holes are added, they may also point to reverted
-black holes.
 
 \item[Thread State Objects (@TSO@s)] represent Haskell threads.  Their
-payload consists of a unique thread id, the status of the thread
-(runnable, blocked, etc) and the stack.  @TSO@s may be resized by the
-scheduler if its stack is too small or too large.
+payload consists of some per-thread information such as the Thread ID
+and the status of the thread (runnable, blocked etc.), and the
+thread's stack.  See @TSO.h@ for the full story.  @TSO@s may be
+resized by the scheduler if its stack is too small or too large.
+
+The thread stack grows downwards from higher to lower addresses.
 
 \begin{center}
 \begin{tabular}{|l|l|l|l|}\hline
-@TSO@ & \emph{Thread Id} & \emph{Status} & \emph{Stack} \\ \hline
+@TSO@ & \emph{Thread info} & \emph{Stack} \\ \hline
 \end{tabular}
 \end{center}
 
@@ -662,12 +660,15 @@ generated by the machine code compiler look like this:
 
 \begin{center}
 \begin{tabular}{|l|l|l|l|}\hline
-\emph{@RET_ADDR@} & \emph{Free Variables of the case alternatives} \\ \hline
+\emph{@RET_XXX@} & \emph{Free Variables of the case alternatives} \\ \hline
 \end{tabular}
 \end{center}
 
 The free variables are a mixture of pointers and non-pointers whose
-layout is described by the info table.
+layout is described by a bitmask in the info table.
+
+There are several kinds of @RET_XXX@ return address - see
+\secref{activation-records} for the details.
 
 Return addresses generated by the bytecode compiler look like this:
 \begin{center}
@@ -682,26 +683,37 @@ though they were pending arguments.
 
 \item[Update frames] are used to trigger updates.  When an update
 frame is entered, it overwrites the updatee with an indirection to the
-result, restarts any threads blocked on the @BH@ and returns to the
-stack object underneath the update frame.
+result, restarts any threads blocked on the @BLACKHOLE@ and returns to
+the stack object underneath the update frame.
 
 \begin{center}
 \begin{tabular}{|l|l|l|l|}\hline
-\emph{@UPDATE@} & \emph{Next Update Frame} & \emph{Updatee} \\ \hline
+\emph{@UPDATE_FRAME@} & \emph{Next Update Frame} & \emph{Updatee} \\ \hline
 \end{tabular}
 \end{center}
 
-\item[Seq frames] are used to implement the polymorphic @seq@ primitive.
-They are a special kind of update frame.
-
-\ToDo{Describe them properly}
+\item[Seq frames] are used to implement the polymorphic @seq@
+primitive.  They are a special kind of update frame, and are linked on
+the update frame list.
 
+\begin{center}
+\begin{tabular}{|l|l|l|l|}\hline
+\emph{@SEQ_FRAME@} & \emph{Next Update Frame} \\ \hline
+\end{tabular}
+\end{center}
 
-\end{description}
+\item[Stop frames] are put on the bottom of each thread's stack, and
+act as sentinels for the update frame list (i.e. the last update frame
+points to the stop frame).  Returning to a stop frame terminates the
+thread.  Stop frames have no payload:
 
-\ToDo{We also need a stop frame which goes on the bottom of the stack 
-when the thread terminates.}
+\begin{center}
+\begin{tabular}{|l|l|l|l|}\hline
+\emph{@SEQ_FRAME@} \\ \hline
+\end{tabular}
+\end{center}
 
+\end{description}
 
 \Subsubsection{Case expressions}{case-expr-overview}
 
@@ -1100,8 +1112,8 @@ Stable pointers allow other languages to access Haskell objects.
 
 \item
 
-Foreign Objects are a form of weak pointer which lets Haskell access
-foreign objects.
+Weak pointers and foreign objects provide finalisation support for
+Haskell references to external objects.
 
 \end{itemize}
 
@@ -1116,8 +1128,6 @@ manager may shrink the stack.  If it shrinks the stack, it guarantees
 never to leave less than @MIN_SIZE_SHRUNKEN_STACK@ empty words on the
 stack when it does so.
 
-\ToDo{Would it be useful for the storage manager to enlarge the stack?}
-
 \item
 
 For efficiency reasons, very large objects (eg large arrays and TSOs)
@@ -1327,7 +1337,8 @@ required. This has only been done for 2s collection.  }
 \end{itemize}
 
 Most of the RTS is completely insensitive to the number of admin
-words.  The total size of the fixed header is @FIXED_HS@.
+words.  The total size of the fixed header is given by
+@sizeof(StgHeader)@.
 
 \Subsection{Info Tables}{info-tables}
 
@@ -1338,15 +1349,19 @@ An \emph{info table} is a contiguous block of memory, laid out as follows:
    \hline Parallelism Info 	& variable
 \\ \hline Profile Info 		& variable
 \\ \hline Debug Info		& variable
-\\ \hline Static reference table  & 32 bits (optional)
-\\ \hline Storage manager layout info & 32 bits
-\\ \hline Closure type 		& 16 bits
-\\ \hline Constructor Tag    	& 16 bits
+\\ \hline Static reference table  & pointer word (optional)
+\\ \hline Storage manager layout info & pointer word
+\\ \hline Closure flags		& 8 bits
+\\ \hline Closure type 		& 8 bits
+\\ \hline Constructor Tag / SRT length    	& 16 bits
 \\ \hline entry code
 \\       \vdots
 \end{tabular}
 \end{center}
 
+On a 64-bit machine the tag, type and flags fields will all be doubled
+in size, so the info table is a multiple of 64 bits.
+
 An info table has the following contents (working backwards in memory
 addresses):
 
@@ -1357,15 +1372,19 @@ literally as the (large) last entry in the info table, immediately
 preceded by the rest of the info table.  An \emph{info pointer} always
 points to the first byte of the entry code.
 
-\item A 16-bit constructor tag.  This field is used for constructor
-info-tables only (\secref{CONSTR}), and contains an integer
-representing the tag value of the constructor, in the range $0..n-1$
-where $n$ is the number of constructors in the datatype.
+\item A 16-bit constructor tag / SRT length.  For a constructor info
+table this field contains the tag of the constructor, in the range
+$0..n-1$ where $n$ is the number of constructors in the datatype.
+Otherwise, it contains the number of entries in this closure's Static
+Reference Table (\secref{srt}).
 
-\item An 16-bit {\em closure type field}, which identifies what kind of
+\item An 8-bit {\em closure type field}, which identifies what kind of
 closure the object is.  The various types of closure are described in
 \secref{closures}.
 
+\item an 8-bit flags field, which holds various flags pertaining to
+the closure type.
+
 \item A single pointer or word --- the {\em storage manager info
 field}, contains auxiliary information describing the closure's
 precise layout, for the benefit of the garbage collector and the code
@@ -1394,7 +1413,7 @@ field contains a pointer to a bitmap record, consisting of a length
 field followed by two or more bitmap words.  This layout information
 is used for @RET_BIG@ and @RET_VEC_BIG@ closures.
 
-\item Selector Thunks (\secref{THUNK_SEL}) use the closure
+\item Selector Thunks (\secref{THUNK_SELECTOR}) use the closure
 layout field to hold the selector index, since the layout is always
 known (the closure contains a single pointer field).
 \end{itemize}
@@ -1408,7 +1427,7 @@ and is only present for the following closure types:
 	\item @THUNK_*@
 	\item @RET_*@
 	\end{itemize}
-  
+
 \item \emph{Profiling info\/}
 
 \ToDo{The profiling info is completely bogus.  I've not deleted it