[[PageOutline]]

= GHC Source Tree Roadmap: rts/ =

This directory contains the source code for the runtime system.

There are three types of files:

 {{{.h}}}::
   Header files that are ''private to the RTS''.  That is, header files in this directory are
   not shipped with GHC, and APIs they define are therefore intended to be private and not
   usable by client code (in practice, we do not and probably cannot enforce this).  Header
   files that we ''do'' ship with GHC are in the [wiki:Commentary/SourceTree/Includes includes]
   directory.

 {{{.c}}}::
   C source code for the runtime system.  Conventions used in this code are described in
   [wiki:Commentary/Rts/Conventions].

 {{{.cmm}}}::
   C-- code for parts of the runtime that are part of the Haskell execution environment: for
   example, the implementation of primitives, exceptions, and so on.  A {{{.cmm}}} file is
   pseudo C--: more or less C-- syntax with some omissions and some additional macro-like
   extensions implemented by GHC.  The {{{.cmm}}} files are compiled using GHC itself: see
   [wiki:Commentary/Rts/Cmm].

=== Subdirectories of rts/ ===

 {{{posix/}}}::
 {{{win32/}}}::
   POSIX and Win32-specific parts of the runtime respectively.  We try to put platform-specific stuff in these directories,
   however not all of the RTS follows this convention right now.

 {{{hooks/}}}::
   Hooks for changing the RTS behaviour from client code, eg. changing the default heap size. (see User's Guide
   for more about hooks).

 {{{sm/}}}::
   The [wiki:Commentary/Rts/Storage Storage Manager].

=== Haskell Execution ===

All this code runs on the Haskell side of the Haskell/C divide; 
{{{StgCRun}}} is the interface between the two layers.

 [http://darcs.haskell.org/ghc/rts/Apply.cmm Apply.cmm], [http://darcs.haskell.org/ghc/rts/AutoApply.h AutoApply.h], {{{AutoApply.cmm}}}, [http://darcs.haskell.org/ghc/rts/Apply.h Apply.h]::
  The eval/apply machinery.  Note: {{{AutoApply.cmm}}} is the family
  of functions for performing generic application of unknown
  functions, this code depends on the number of registers available
  for argument passing, so it is generated automatically by the program
  {{{genapply}}} in {{{utils/genapply}}}.

 [http://darcs.haskell.org/ghc/rts/Exception.cmm Exception.cmm]::
  Support for execptions.

 [http://darcs.haskell.org/ghc/rts/HeapStackCheck.cmm HeapStackCheck.cmm]::
  Code for preparing the stack when the current Haskell thread needs
  to return to the RTS, because we either ran out of heap or stack, or
  need to block (eg. {{{takeMVar}}}), or yield.

 [http://darcs.haskell.org/ghc/rts/PrimOps.cmm PrimOps.cmm]::
  Implementation of out-of-line primitives (see [wiki:Commentary/PrimOps]).

 [http://darcs.haskell.org/ghc/rts/StgMiscClosures.cmm StgMiscClosures.cmm]::
  Some built-in closures, such as the family of small {{{Int}}}s and
  {{{Chars}}}, and some built-in info tables such as {{{BLACKHOLE}}}
  and {{{ARR_WORDS}}}.

 [http://darcs.haskell.org/ghc/rts/StgStartup.cmm StgStartup.cmm]::
  Code that executes when a Haskell thread begins and ends.

 [http://darcs.haskell.org/ghc/rts/StgStdThunks.cmm StgStdThunks.cmm]::
  Some built-in thunks: [wiki:Commentary/Rts/SelectorThunks] and "apply" thunks.

 [http://darcs.haskell.org/ghc/rts/Updates.cmm Updates.cmm], [http://darcs.haskell.org/ghc/rts/Updates.h Updates.h]::
  [wiki:Commentary Updates].

 [http://darcs.haskell.org/ghc/rts/HCIncludes.h HCIncludes.h]::
  Header file included when compiling {{{.cmm}}} files via C.

 [http://darcs.haskell.org/ghc/rts/StgCRun.c StgCRun.c], [http://darcs.haskell.org/ghc/rts/StgRun.h StgRun.h]::
  The interface between the C execution layer and the Haskell
  execution layer.

 [http://darcs.haskell.org/ghc/rts/StgPrimFloat.c StgPrimFloat.c]::
  Floating-point stuff.

 [http://darcs.haskell.org/ghc/rts/STM.c STM.c]::
  Implementation of Software Transactional Memory.

=== The [wiki:Commentary/Rts/Storage Storage Manager] ===

 [http://darcs.haskell.org/ghc/rts/sm/Storage.c sm/Storage.c]::
  Top-level of the storage manager.

 [http://darcs.haskell.org/ghc/rts/sm/MBlock.c sm/MBlock.c], [http://darcs.haskell.org/ghc/rts/sm/MBlock.h sm/MBlock.h], [http://darcs.haskell.org/ghc/rts/sm/OSMem.h sm/OSMem.h]::
  The "megablock" allocator; this is the thin layer between the RTS and
  the operating system for allocating memory.

 [http://darcs.haskell.org/ghc/rts/sm/BlockAlloc.c sm/BlockAlloc.c], [http://darcs.haskell.org/ghc/rts/sm/BlockAlloc.h sm/BlockAlloc.h]::
  The low-level block allocator, requires only {{{MBlock}}}.

 [http://darcs.haskell.org/ghc/rts/sm/GC.c sm/GC.c], [http://darcs.haskell.org/ghc/rts/sm/Scav.c sm/Scav.c], [http://darcs.haskell.org/ghc/rts/sm/Evac.c sm/Evac.c], [http://darcs.haskell.org/ghc/rts/sm/GCUtils.c sm/GCUtils.c], [http://darcs.haskell.org/ghc/rts/sm/MarkWeak.c sm/MarkWeak.c]::
  The generational copying garbage collector.

 [http://darcs.haskell.org/ghc/rts/sm/Compact.c sm/Compact.c], [http://darcs.haskell.org/ghc/rts/sm/Compact.h sm/Compact.h]::
  The compacting garbage collector.

 [http://darcs.haskell.org/ghc/rts/ClosureFlags.c ClosureFlags.c]::
  Determining properties of various types of closures.

 [http://darcs.haskell.org/ghc/rts/Sanity.c Sanity.c], [http://darcs.haskell.org/ghc/rts/Sanity.h Sanity.h]::
  A sanity-checker for the heap and related data structures.

 [http://darcs.haskell.org/ghc/rts/Stats.c Stats.c], [http://darcs.haskell.org/ghc/rts/Stats.h Stats.h]::
  Statistics for the garbage collector and storage manager.

 [http://darcs.haskell.org/ghc/rts/Stable.c Stable.c]::
  Stable names and stable pointers.

 [http://darcs.haskell.org/ghc/rts/Weak.c Weak.c], [http://darcs.haskell.org/ghc/rts/Weak.h Weak.h]::
  Weak pointers.

=== Data Structures ===

Data structure abstractions for use in the RTS:

 [http://darcs.haskell.org/ghc/rts/Arena.c Arena.c], [http://darcs.haskell.org/ghc/rts/Arena.h Arena.h]::
  An arena allocator

 [http://darcs.haskell.org/ghc/rts/Hash.c Hash.c], [http://darcs.haskell.org/ghc/rts/Hash.h Hash.h]::
  A generic hash table implementation.

=== The [wiki:Commentary/Rts/Scheduler Scheduler] ===

 [http://darcs.haskell.org/ghc/rts/Capability.c Capability.c], [http://darcs.haskell.org/ghc/rts/Capability.h Capability.h]::
  Capabilities: virtual CPUs for executing Haskell code.

 [http://darcs.haskell.org/ghc/rts/RaiseAsync.c RaiseAsync.c], [http://darcs.haskell.org/ghc/rts/RaiseAsync.h RaiseAsync.h]::
  Asynchronous exceptions.

 [http://darcs.haskell.org/ghc/rts/Schedule.c Schedule.c], [http://darcs.haskell.org/ghc/rts/Schedule.h Schedule.h]::
  The scheduler itself.

 [http://darcs.haskell.org/ghc/rts/Sparks.c Sparks.c], [http://darcs.haskell.org/ghc/rts/Sparks.h Sparks.h]::
  Sparks: the implementation of {{{par}}}.

 [http://darcs.haskell.org/ghc/rts/ThreadLabels.c ThreadLabels.c], [http://darcs.haskell.org/ghc/rts/ThreadLabels.h ThreadLabels.h]::
  Labelling threads.

 [http://darcs.haskell.org/ghc/rts/Threads.c Threads.c], [http://darcs.haskell.org/ghc/rts/Threads.h Threads.h]::
  Various thread-related functionality.

 [http://darcs.haskell.org/ghc/rts/ThreadPaused.c ThreadPaused.c]::
  Suspending a thread before it returns to the RTS.

 [http://darcs.haskell.org/ghc/rts/Task.c Task.c], [http://darcs.haskell.org/ghc/rts/Task.h Task.h]::
  Task: an OS-thread abstraction.

 [http://darcs.haskell.org/ghc/rts/AwaitEvent.h AwaitEvent.h]::
  Waiting for events (non-threaded RTS only).

 [http://darcs.haskell.org/ghc/rts/Timer.c Timer.c], [http://darcs.haskell.org/ghc/rts/Timer.h Timer.h],  [http://darcs.haskell.org/ghc/rts/Ticker.h Ticker.h]::
  The runtime's interval timer, used for context switching and profiling.

=== C files: the [wiki:Commentary/Rts/FFI FFI] ===

 [http://darcs.haskell.org/ghc/rts/Adjustor.c Adjustor.c]::
  Very hairy support for {{{foreign import "wrapper"}}}.

 [http://darcs.haskell.org/ghc/rts/HsFFI.c HsFFI.c], [http://darcs.haskell.org/ghc/rts/RtsAPI.c RtsAPI.c]::
  Implementation of the Haskell FFI C interface: {{{hs_init()}}},
  {{{hs_exit()}}}, etc.
  

=== The [wiki:Commentary/Rts/Interpreter Byte-code Interpreter] ===

 [http://darcs.haskell.org/ghc/rts/Disassembler.c Disassembler.c], [http://darcs.haskell.org/ghc/rts/Disassembler.h Disassembler.h]::
 [http://darcs.haskell.org/ghc/rts/Interpreter.c Interpreter.c], [http://darcs.haskell.org/ghc/rts/Interpreter.h Interpreter.h]::
  The [wiki:Commentary/Rts/Interpreter byte-code interpreter] and disassembler.

 [http://darcs.haskell.org/ghc/rts/Linker.c Linker.c]::
 [http://darcs.haskell.org/ghc/rts/LinkerInternals.h LinkerInternals.h]
  The [wiki:Commentary/Rts/Linker dynamic object-code linker].

=== [wiki:Commentary/Profiling Profiling] ===

 [http://darcs.haskell.org/ghc/rts/LdvProfile.c LdvProfile.c], [http://darcs.haskell.org/ghc/rts/LdvProfile.h LdvProfile.h]::
  Lag-drag-void profiling (also known as Biographical Profiling).

 [http://darcs.haskell.org/ghc/rts/ProfHeap.c ProfHeap.c], [http://darcs.haskell.org/ghc/rts/ProfHeap.h ProfHeap.h]::
  Generic heap-profilng support.

 [http://darcs.haskell.org/ghc/rts/Profiling.c Profiling.c], [http://darcs.haskell.org/ghc/rts/Profiling.h Profiling.h]::
  Generic profilng support.

 [http://darcs.haskell.org/ghc/rts/Proftimer.c Proftimer.c], [http://darcs.haskell.org/ghc/rts/Proftimer.h Proftimer.h]::
  The profiling timer.

 [http://darcs.haskell.org/ghc/rts/RetainerProfile.c RetainerProfile.c], [http://darcs.haskell.org/ghc/rts/RetainerProfile.h RetainerProfile.h]::
 [http://darcs.haskell.org/ghc/rts/RetainerSet.c RetainerSet.c], [http://darcs.haskell.org/ghc/rts/RetainerSet.h RetainerSet.h]::
  Retainer profiling.

 [http://darcs.haskell.org/ghc/rts/Ticky.c Ticky.c], [http://darcs.haskell.org/ghc/rts/Ticky.h Ticky.h]::
  Ticky-ticky profiling (currently defunct; needs reviving).

=== RTS Debugging ===

 [http://darcs.haskell.org/ghc/rts/Printer.c Printer.c], [http://darcs.haskell.org/ghc/rts/Printer.h Printer.h]::
  Generic printing for heap objects and stacks (not used much).

 [http://darcs.haskell.org/ghc/rts/Trace.c Trace.c], [http://darcs.haskell.org/ghc/rts/Trace.h Trace.h]::
  Generic support for various kinds of trace and debugging messages.  

=== The Front Panel ===

The front panel is currently defunct.  It offers a graphical view of
the running Haskell program in real time, and was pretty cool when it
worked.

 [http://darcs.haskell.org/ghc/rts/FrontPanel.c FrontPanel.c], [http://darcs.haskell.org/ghc/rts/FrontPanel.h FrontPanel.h]::
 [http://darcs.haskell.org/ghc/rts/VisCallbacks.c VisCallbacks.c], [http://darcs.haskell.org/ghc/rts/VisCallbacks.h VisCallbacks.h]::
 [http://darcs.haskell.org/ghc/rts/VisSupport.c VisSupport.c], [http://darcs.haskell.org/ghc/rts/VisSupport.h VisSupport.h]::
 [http://darcs.haskell.org/ghc/rts/VisWindow.c VisWindow.c], [http://darcs.haskell.org/ghc/rts/VisWindow.h VisWindow.h]::

=== Other ===

 [http://darcs.haskell.org/ghc/rts/Main.c Main.c]::
  The C {{{main()}}} function for a standalone Haskell program;
  basically this is just a client of {{{HsFFI.h}}}.

 [http://darcs.haskell.org/ghc/rts/RtsFlags.c RtsFlags.c]::
  Understands the {{{+RTS ... -RTS}}} flags.

 [http://darcs.haskell.org/ghc/rts/RtsMessages.c RtsMessages.c]::
  Support for emitting messages from the runtime.

 [http://darcs.haskell.org/ghc/rts/RtsSignals.c RtsSignals.c], [http://darcs.haskell.org/ghc/rts/RtsSignals.h RtsSignals.h]::
  Signal-related stuff.

Miscellaneous stuff:

 [http://darcs.haskell.org/ghc/rts/RtsUtils.c RtsUtils.c], [http://darcs.haskell.org/ghc/rts/RtsUtils.h RtsUtils.h]::
 [http://darcs.haskell.org/ghc/rts/GetTime.h GetTime.h]::
 [http://darcs.haskell.org/ghc/rts/PosixSource.h PosixSource.h]::
 [http://darcs.haskell.org/ghc/rts/Prelude.h Prelude.h]::
 [http://darcs.haskell.org/ghc/rts/Typeable.c Typeable.c]::
 [http://darcs.haskell.org/ghc/rts/RtsDllMain.c RtsDllMain.c]::

=== OLD stuff ===

 {{{parallel/}}}::
  Code for GUM: parallel GHC.  This is heavily bitrotted and currently doesn't work (as of GHC 6.6; it last worked around
  5.02 I believe).

 {{{dotnet/}}}::
  Bitrotted code for GHC.NET.