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 includes directory.

.c

C source code for the runtime system. Conventions used in this code are described in 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 Commentary/Compiler/CmmFiles?.

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).

Haskell Execution

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

 Apply.cmm,  AutoApply.h, AutoApply.cmm,  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.

 Exception.cmm

Support for execptions.

 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.

 PrimOps.cmm

Implementation of out-of-line primitives (see Commentary/PrimOps).

 StgMiscClosures.cmm

Some built-in closures, such as the family of small Ints and Chars, and some built-in info tables such as BLACKHOLE and ARR_WORDS.

 StgStartup.cmm

Code that executes when a Haskell thread begins and ends.

 StgStdThunks.cmm

Some built-in thunks: Commentary/Rts/SelectorThunks? and "apply" thunks.

 Updates.cmm,  Updates.h

Updates.

 HCIncludes.h

Header file included when compiling .cmm files via C.

 StgCRun.c,  StgRun.h

The interface between the C execution layer and the Haskell execution layer.

 StgPrimFloat.c

Floating-point stuff.

 STM.c

Implementation of Software Transactional Memory.

The Storage Manager?

 Arena.c,  Arena.h

An arena allocator

 BlockAlloc.c,  BlockAlloc.h

The low-level block allocator, requires only MBlock.

 ClosureFlags.c

Determining properties of various types of closures.

 GC.c

The generational copying garbage collector.

 GCCompact.c,  GCCompact.h

The compacting garbage collector.

 Hash.c,  Hash.h

A generic hash table implementation.

 MBlock.c,  MBlock.h,  OSMem.h

The "megablock" allocator; this is the thin layer between the RTS and the operating system for allocating memory.

 Sanity.c,  Sanity.h

A sanity-checker for the heap and related data structures.

 Stats.c,  Stats.h

Statistics for the garbage collector and storage manager.

 Stable.c

Stable names and stable pointers.

 Storage.c

Top-level of the storage manager.

 Weak.c,  Weak.h

Weak pointers.

The Scheduler

 Capability.c,  Capability.h

Capabilities: virtual CPUs for executing Haskell code.

 RaiseAsync.c,  RaiseAsync.h

Asynchronous exceptions.

 Schedule.c,  Schedule.h

The scheduler itself.

 Sparks.c,  Sparks.h

Sparks: the implementation of par.

 ThreadLabels.c,  ThreadLabels.h

Labelling threads.

 Threads.c,  Threads.h

Various thread-related functionality.

 Task.c,  Task.h

Task: an OS-thread abstraction.

 AwaitEvent.h

Waiting for events (non-threaded RTS only).

 Timer.c,  Timer.h,  Ticker.h

The runtime's interval timer, used for context switching and profiling.

C files: the Commentary/Rts/FFI

 Adjustor.c

Very hairy support for foreign import "wrapper".

 HsFFI.c,  RtsAPI.c

Implementation of the Haskell FFI C interface: hs_init(), hs_exit(), etc.

The Byte-code Interpreter

 Disassembler.c,  Disassembler.h

 Interpreter.c,  Interpreter.h

The byte-code interpreter and disassembler.

 Linker.c

 LinkerInternals.h The dynamic object-code linker?.

Profiling

 LdvProfile.c,  LdvProfile.h

Lag-drag-void profiling (also known as Biographical Profiling).

 ProfHeap.c,  ProfHeap.h

Generic heap-profilng support.

 Profiling.c,  Profiling.h

Generic profilng support.

 Proftimer.c,  Proftimer.h

The profiling timer.

 RetainerProfile.c,  RetainerProfile.h

 RetainerSet.c,  RetainerSet.h

Retainer profiling.

 Ticky.c,  Ticky.h

Ticky-ticky profiling (currently defunct; needs reviving).

RTS Debugging

 Printer.c,  Printer.h

Generic printing for heap objects and stacks (not used much).

 Trace.c,  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.

 FrontPanel.c,  FrontPanel.h

 VisCallbacks.c,  VisCallbacks.h

 VisSupport.c,  VisSupport.h

 VisWindow.c,  VisWindow.h

Other

 Main.c

The C main() function for a standalone Haskell program; basically this is just a client of HsFFI.h.

 RtsFlags.c

Understands the +RTS ... -RTS flags.

 RtsMessages.c

Support for emitting messages from the runtime.

 RtsSignals.c,  RtsSignals.h

Signal-related stuff.

Miscellaneous stuff:

 RtsUtils.c,  RtsUtils.h

 GetTime.h

 PosixSource.h

 Prelude.h

 Typeable.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.