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
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}
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.
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
\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.
\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
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
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}
\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}
\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}
\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}
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)
\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}
\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):
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
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}
\item @THUNK_*@
\item @RET_*@
\end{itemize}
-
+
\item \emph{Profiling info\/}
\ToDo{The profiling info is completely bogus. I've not deleted it
projects / ghc-hetmet.git / commitdiff