--- /dev/null
+
+ GARBAGE COLLECTION
+ ~~~~~~~~~~~~~~~~~~
+
+The following discussion outlines how the GC is organised and what C
+the compiler needs to produce to use it.
+
+The files associated with GC are:
+
+ StgGC.h header file -- macros and externs
+ StgCreate.lc GC init routines
+ StgOverflow.lhc Overflow routines -- interface to GC
+ GC2s.lhc }
+ GC1s.lhc } GC control routines
+ GCdm.lhc } for each particular GC
+ GCap.lhc }
+ GCevac.lc Evacuation code fragments (copying GC)
+ GCscav.lhc Scavenging code fragments (copying GC)
+ GCcompact.lhc Inplace Compacting GC code fragments
+ GCmark.lhc Marking code fragments
+
+Other files:
+
+ In gctest/
+ gctest.c GC Small detail test bed program
+
+ In gcstat/
+ Performance evaluation stuff
+
+
+Basic Requirements of the C code Produced by the Haskell Compiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two main aspects of the compiler generated code that
+interact with GC:
+
+1) Compiled haskell code calls the garbage collection routine when the
+ heap overflows by entering the appropriate _HEAP_OVERFLOW_... routine.
+
+ These routines isolate register usage and calls the GC control
+ routine that was defined at compile time.
+
+ For a description of the heap overflow conventions see:
+
+ ~grasp/ghc/compiler/absCSyn/RTSLabels.lhs
+
+
+ The following must be adhered to by the mutator:
+
+ REQUIREMENT COLLECTOR
+ SpA and SpB point to A and B stacks all
+
+ Hp must point to last word allocated dual,comp
+ All updated closures must "know" their original dual,comp
+ size
+
+ HpLim must point to one beyond top of root stack appel
+ Updated closures in the old generation must "know" appel
+ their original size
+
+ The GC Control routines have to know about the pointer stack and
+ Update Stack.
+
+2) The info tables that are pointed to by closures must have the
+ appropriate GC routines within them. This is achieved by using the
+ following C Macros to declare them:
+
+ table_name -- the name given to the info table
+ entry_code -- the name of the normal evaluation
+ entry code required for the closure
+ size -- the No of free var words in the closure
+ ptrs -- the number of pointers in the closure
+
+
+ SPEC_INFO_TABLE(table_name,entry_code,size,ptrs);
+
+ Declares an info table with specialiazed code fragments
+ These are currently available for the following closure
+ configurations: size, ptrs
+ 1,0 2,0 3,0 4,0 5,0
+ 1,1 2,1 3,1
+ 2,2
+ 3,3
+ 4,4
+ 5,5
+ ...
+ 11,11
+
+ GEN_INFO_TABLE(table_name,entry_code,size,ptrs);
+
+ Declares an info table that uses generic code fragments and
+ places data to drive these routines in the info table.
+ These are available for all combinations of size,ptrs (even
+ those for which SPEC routines are provided).
+
+
+ STATIC_INFO_TABLE(table_name,entry_code);
+
+ Declares an info table suitable for a static closure.
+
+
+ DATA_INFO_TABLE(table_name,entry_code);
+
+ Declares an info table suitable for a data closure.
+ This closure contains no heap pointers and its size
+ (of data and size field) in its first word
+
+ See NOTES.arbitary-ints
+
+
+ IND_INFO_TABLE(table_name,ind_code);
+
+ Declares an info table suitable for an indirection.
+ But see below !! (ToDo)
+
+
+Using a Particular Garbage Collection Scheme
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When deciding which collector to use there are two decision points.
+
+At compile time it must be decided which code fragments are going to
+be attached to closures. This will limit the possible choice of GC
+schemes at run time.
+
+To compile the GC code and compiler-produced C Code for a particular
+set of code fragments an appropriate define (-D) directive is given
+to the compiler.
+
+Possible directives are:
+
+ Code Fragments GC Control Routines
+
+-DGC2s Copying Two Space Collection
+
+-DGC1s Marking & Compacting Inplace Compaction
+
+-DGCdm Copying, Marking DualMode Collection
+ & Compaction (+ TwoSpace and Compaction)
+-DGCap Copying, Marking Appels Collector
+ & Compaction (+ Compaction)
+
+If none of these are defined the result will be No Collection Schame.
+Heap will be allocated but the program will die if it is ever filled.
+
+Other Directives:
+
+-D_GC_DEBUG Provides detailed GC debugging trace output
+ (if showGCTrace set)
+
+Note that the GC code will eventually be set up already compiled for
+the different schemes and all that will be required will be to link
+with the appropriate object files. The compiler produced C will still
+need to be compiled with the appropriate define.
+
+
+Trace and Statistics Info
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a couple of variables that can be set to provide info about
+GC.
+
+showGCTrace -- Provides detailed trace of GC and closure movement
+ TRUE -- Summary about GC invokation and heap location
+ & 2 -- Detailed trace of copying AND compacting collection
+ & 4 -- More detail about linked location lists during compaction
+ & 8 -- Detalied info about marking
+
+ The & options are only available if compiled with -D_GC_DEBUG
+
+showGCStats -- Provides summary statistics about GC performance
+ (ToDo)
+
+ToDo: These should eventually be able to be set by runtime flages
+
+
+Compiler Extensions Required for Compacting Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a number of additional requirements required of the STG
+machine and the resulting C code for Inplace Compaction to work.
+
+The most important and awkward arises from the fact that updated nodes
+will be scanned. This requires updated nodes (blackholes, indirections
+or inplace updates) to know how big the original closure was (so the
+location of the next closure can be determined).
+
+Implications (Suggestions -- Still to be done):
+
+ Need specialized black holes info pointers which know their size.
+
+ Code on the Update Stack needs to know the orig closure size. Either
+ record this size or have specialised update code fragments.
+
+ Updated closures need to know orig size. Possible solns are:
+
+ Create dummy garbage closures at the end to fill the hole.
+
+ Store size of closure in free space beyond and have GC
+ routines which look here for the size.
+
+ Specialised indirections that know their size.
+
+ May be able to search beyond the end of the closure for the next
+ info pointer. Possibly blanking out the unused portion of the
+ closure.
projects / ghc-hetmet.git / blobdiff