5 The following discussion outlines how the GC is organised and what C
6 the compiler needs to produce to use it.
8 The files associated with GC are:
10 StgGC.h header file -- macros and externs
11 StgCreate.lc GC init routines
12 StgOverflow.lhc Overflow routines -- interface to GC
14 GC1s.lhc } GC control routines
15 GCdm.lhc } for each particular GC
17 GCevac.lc Evacuation code fragments (copying GC)
18 GCscav.lhc Scavenging code fragments (copying GC)
19 GCcompact.lhc Inplace Compacting GC code fragments
20 GCmark.lhc Marking code fragments
25 gctest.c GC Small detail test bed program
28 Performance evaluation stuff
31 Basic Requirements of the C code Produced by the Haskell Compiler
32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34 There are two main aspects of the compiler generated code that
37 1) Compiled haskell code calls the garbage collection routine when the
38 heap overflows by entering the appropriate _HEAP_OVERFLOW_... routine.
40 These routines isolate register usage and calls the GC control
41 routine that was defined at compile time.
43 For a description of the heap overflow conventions see:
45 ~grasp/ghc/compiler/absCSyn/RTSLabels.lhs
48 The following must be adhered to by the mutator:
51 SpA and SpB point to A and B stacks all
53 Hp must point to last word allocated dual,comp
54 All updated closures must "know" their original dual,comp
57 HpLim must point to one beyond top of root stack appel
58 Updated closures in the old generation must "know" appel
61 The GC Control routines have to know about the pointer stack and
64 2) The info tables that are pointed to by closures must have the
65 appropriate GC routines within them. This is achieved by using the
66 following C Macros to declare them:
68 table_name -- the name given to the info table
69 entry_code -- the name of the normal evaluation
70 entry code required for the closure
71 size -- the No of free var words in the closure
72 ptrs -- the number of pointers in the closure
75 SPEC_INFO_TABLE(table_name,entry_code,size,ptrs);
77 Declares an info table with specialiazed code fragments
78 These are currently available for the following closure
79 configurations: size, ptrs
89 GEN_INFO_TABLE(table_name,entry_code,size,ptrs);
91 Declares an info table that uses generic code fragments and
92 places data to drive these routines in the info table.
93 These are available for all combinations of size,ptrs (even
94 those for which SPEC routines are provided).
97 STATIC_INFO_TABLE(table_name,entry_code);
99 Declares an info table suitable for a static closure.
102 DATA_INFO_TABLE(table_name,entry_code);
104 Declares an info table suitable for a data closure.
105 This closure contains no heap pointers and its size
106 (of data and size field) in its first word
108 See NOTES.arbitary-ints
111 IND_INFO_TABLE(table_name,ind_code);
113 Declares an info table suitable for an indirection.
114 But see below !! (ToDo)
117 Using a Particular Garbage Collection Scheme
118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120 When deciding which collector to use there are two decision points.
122 At compile time it must be decided which code fragments are going to
123 be attached to closures. This will limit the possible choice of GC
126 To compile the GC code and compiler-produced C Code for a particular
127 set of code fragments an appropriate define (-D) directive is given
130 Possible directives are:
132 Code Fragments GC Control Routines
134 -DGC2s Copying Two Space Collection
136 -DGC1s Marking & Compacting Inplace Compaction
138 -DGCdm Copying, Marking DualMode Collection
139 & Compaction (+ TwoSpace and Compaction)
140 -DGCap Copying, Marking Appels Collector
141 & Compaction (+ Compaction)
143 If none of these are defined the result will be No Collection Schame.
144 Heap will be allocated but the program will die if it is ever filled.
148 -D_GC_DEBUG Provides detailed GC debugging trace output
151 Note that the GC code will eventually be set up already compiled for
152 the different schemes and all that will be required will be to link
153 with the appropriate object files. The compiler produced C will still
154 need to be compiled with the appropriate define.
157 Trace and Statistics Info
158 ~~~~~~~~~~~~~~~~~~~~~~~~~
160 There are a couple of variables that can be set to provide info about
163 showGCTrace -- Provides detailed trace of GC and closure movement
164 TRUE -- Summary about GC invokation and heap location
165 & 2 -- Detailed trace of copying AND compacting collection
166 & 4 -- More detail about linked location lists during compaction
167 & 8 -- Detalied info about marking
169 The & options are only available if compiled with -D_GC_DEBUG
171 showGCStats -- Provides summary statistics about GC performance
174 ToDo: These should eventually be able to be set by runtime flages
177 Compiler Extensions Required for Compacting Collection
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180 There are a number of additional requirements required of the STG
181 machine and the resulting C code for Inplace Compaction to work.
183 The most important and awkward arises from the fact that updated nodes
184 will be scanned. This requires updated nodes (blackholes, indirections
185 or inplace updates) to know how big the original closure was (so the
186 location of the next closure can be determined).
188 Implications (Suggestions -- Still to be done):
190 Need specialized black holes info pointers which know their size.
192 Code on the Update Stack needs to know the orig closure size. Either
193 record this size or have specialised update code fragments.
195 Updated closures need to know orig size. Possible solns are:
197 Create dummy garbage closures at the end to fill the hole.
199 Store size of closure in free space beyond and have GC
200 routines which look here for the size.
202 Specialised indirections that know their size.
204 May be able to search beyond the end of the closure for the next
205 info pointer. Possibly blanking out the unused portion of the