11c8560a54a9b7d69fe180bc41f399c992064f58
[ghc.git] / includes / rts / storage / GC.h
1 /* -----------------------------------------------------------------------------
2 *
3 * (c) The GHC Team, 1998-2004
4 *
5 * External Storage Manger Interface
6 *
7 * ---------------------------------------------------------------------------*/
8
9 #ifndef RTS_STORAGE_GC_H
10 #define RTS_STORAGE_GC_H
11
12 #include <stddef.h>
13 #include "rts/OSThreads.h"
14
15 /* -----------------------------------------------------------------------------
16 * Generational GC
17 *
18 * We support an arbitrary number of generations, with an arbitrary number
19 * of steps per generation. Notes (in no particular order):
20 *
21 * - all generations except the oldest should have the same
22 * number of steps. Multiple steps gives objects a decent
23 * chance to age before being promoted, and helps ensure that
24 * we don't end up with too many thunks being updated in older
25 * generations.
26 *
27 * - the oldest generation has one step. There's no point in aging
28 * objects in the oldest generation.
29 *
30 * - generation 0, step 0 (G0S0) is the allocation area. It is given
31 * a fixed set of blocks during initialisation, and these blocks
32 * normally stay in G0S0. In parallel execution, each
33 * Capability has its own nursery.
34 *
35 * - during garbage collection, each step which is an evacuation
36 * destination (i.e. all steps except G0S0) is allocated a to-space.
37 * evacuated objects are allocated into the step's to-space until
38 * GC is finished, when the original step's contents may be freed
39 * and replaced by the to-space.
40 *
41 * - the mutable-list is per-generation (not per-step). G0 doesn't
42 * have one (since every garbage collection collects at least G0).
43 *
44 * - block descriptors contain pointers to both the step and the
45 * generation that the block belongs to, for convenience.
46 *
47 * - static objects are stored in per-generation lists. See GC.c for
48 * details of how we collect CAFs in the generational scheme.
49 *
50 * - large objects are per-step, and are promoted in the same way
51 * as small objects, except that we may allocate large objects into
52 * generation 1 initially.
53 *
54 * ------------------------------------------------------------------------- */
55
56 // A count of blocks needs to store anything up to the size of memory
57 // divided by the block size. The safest thing is therefore to use a
58 // type that can store the full range of memory addresses,
59 // ie. StgWord. Note that we have had some tricky int overflows in a
60 // couple of cases caused by using ints rather than longs (e.g. #5086)
61
62 typedef StgWord memcount;
63
64 typedef struct nursery_ {
65 bdescr * blocks;
66 memcount n_blocks;
67 } nursery;
68
69 typedef struct generation_ {
70 nat no; // generation number
71
72 bdescr * blocks; // blocks in this gen
73 memcount n_blocks; // number of blocks
74 memcount n_words; // number of used words
75
76 bdescr * large_objects; // large objects (doubly linked)
77 memcount n_large_blocks; // no. of blocks used by large objs
78 memcount n_new_large_words; // words of new large objects
79 // (for allocation stats)
80
81 memcount max_blocks; // max blocks
82
83 StgTSO * threads; // threads in this gen
84 // linked via global_link
85 struct generation_ *to; // destination gen for live objects
86
87 // stats information
88 nat collections;
89 nat par_collections;
90 nat failed_promotions;
91
92 // ------------------------------------
93 // Fields below are used during GC only
94
95 #if defined(THREADED_RTS)
96 char pad[128]; // make sure the following is
97 // on a separate cache line.
98 SpinLock sync; // lock for large_objects
99 // and scavenged_large_objects
100 #endif
101
102 int mark; // mark (not copy)? (old gen only)
103 int compact; // compact (not sweep)? (old gen only)
104
105 // During GC, if we are collecting this gen, blocks and n_blocks
106 // are copied into the following two fields. After GC, these blocks
107 // are freed.
108 bdescr * old_blocks; // bdescr of first from-space block
109 memcount n_old_blocks; // number of blocks in from-space
110 memcount live_estimate; // for sweeping: estimate of live data
111
112 bdescr * scavenged_large_objects; // live large objs after GC (d-link)
113 memcount n_scavenged_large_blocks; // size (not count) of above
114
115 bdescr * bitmap; // bitmap for compacting collection
116
117 StgTSO * old_threads;
118 } generation;
119
120 extern generation * generations;
121 extern generation * g0;
122 extern generation * oldest_gen;
123
124 /* -----------------------------------------------------------------------------
125 Generic allocation
126
127 StgPtr allocate(Capability *cap, nat n)
128 Allocates memory from the nursery in
129 the current Capability. This can be
130 done without taking a global lock,
131 unlike allocate().
132
133 StgPtr allocatePinned(Capability *cap, nat n)
134 Allocates a chunk of contiguous store
135 n words long, which is at a fixed
136 address (won't be moved by GC).
137 Returns a pointer to the first word.
138 Always succeeds.
139
140 NOTE: the GC can't in general handle
141 pinned objects, so allocatePinned()
142 can only be used for ByteArrays at the
143 moment.
144
145 Don't forget to TICK_ALLOC_XXX(...)
146 after calling allocate or
147 allocatePinned, for the
148 benefit of the ticky-ticky profiler.
149
150 -------------------------------------------------------------------------- */
151
152 StgPtr allocate ( Capability *cap, W_ n );
153 StgPtr allocatePinned ( Capability *cap, W_ n );
154
155 /* memory allocator for executable memory */
156 void * allocateExec(unsigned int len, void **exec_addr);
157 void freeExec (void *p);
158
159 // Used by GC checks in external .cmm code:
160 extern nat large_alloc_lim;
161
162 /* -----------------------------------------------------------------------------
163 Performing Garbage Collection
164 -------------------------------------------------------------------------- */
165
166 void performGC(void);
167 void performMajorGC(void);
168
169 /* -----------------------------------------------------------------------------
170 The CAF table - used to let us revert CAFs in GHCi
171 -------------------------------------------------------------------------- */
172
173 StgWord newCAF (StgRegTable *reg, StgClosure *caf, StgClosure *bh);
174 StgWord newDynCAF (StgRegTable *reg, StgClosure *caf, StgClosure *bh);
175 void revertCAFs (void);
176
177 // Request that all CAFs are retained indefinitely.
178 void setKeepCAFs (void);
179
180 /* -----------------------------------------------------------------------------
181 Stats
182 -------------------------------------------------------------------------- */
183
184 typedef struct _GCStats {
185 StgWord64 bytes_allocated;
186 StgWord64 num_gcs;
187 StgWord64 num_byte_usage_samples;
188 StgWord64 max_bytes_used;
189 StgWord64 cumulative_bytes_used;
190 StgWord64 bytes_copied;
191 StgWord64 current_bytes_used;
192 StgWord64 current_bytes_slop;
193 StgWord64 max_bytes_slop;
194 StgWord64 peak_megabytes_allocated;
195 StgWord64 par_tot_bytes_copied;
196 StgWord64 par_max_bytes_copied;
197 StgDouble mutator_cpu_seconds;
198 StgDouble mutator_wall_seconds;
199 StgDouble gc_cpu_seconds;
200 StgDouble gc_wall_seconds;
201 StgDouble cpu_seconds;
202 StgDouble wall_seconds;
203 } GCStats;
204 void getGCStats (GCStats *s);
205 rtsBool getGCStatsEnabled (void);
206
207 // These don't change over execution, so do them elsewhere
208 // StgDouble init_cpu_seconds;
209 // StgDouble init_wall_seconds;
210
211 typedef struct _ParGCStats {
212 StgWord64 tot_copied;
213 StgWord64 max_copied;
214 } ParGCStats;
215 void getParGCStats (ParGCStats *s);
216
217 /*
218 typedef struct _TaskStats {
219 StgWord64 mut_time;
220 StgWord64 mut_etime;
221 StgWord64 gc_time;
222 StgWord64 gc_etime;
223 } TaskStats;
224 // would need to allocate arbitrarily large amount of memory
225 // because it's a linked list of results
226 void getTaskStats (TaskStats **s);
227 // Need to stuff SparkCounters in a public header file...
228 void getSparkStats (SparkCounters *s);
229 */
230
231 // Returns the total number of bytes allocated since the start of the program.
232 HsInt64 getAllocations (void);
233
234 /* -----------------------------------------------------------------------------
235 This is the write barrier for MUT_VARs, a.k.a. IORefs. A
236 MUT_VAR_CLEAN object is not on the mutable list; a MUT_VAR_DIRTY
237 is. When written to, a MUT_VAR_CLEAN turns into a MUT_VAR_DIRTY
238 and is put on the mutable list.
239 -------------------------------------------------------------------------- */
240
241 void dirty_MUT_VAR(StgRegTable *reg, StgClosure *p);
242
243 /* set to disable CAF garbage collection in GHCi. */
244 /* (needed when dynamic libraries are used). */
245 extern rtsBool keepCAFs;
246
247 INLINE_HEADER void initBdescr(bdescr *bd, generation *gen, generation *dest)
248 {
249 bd->gen = gen;
250 bd->gen_no = gen->no;
251 bd->dest_no = dest->no;
252 }
253
254 #endif /* RTS_STORAGE_GC_H */