7cee670303c9d4f7ee8f4bf18e21cefa0b53fae6
[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 typedef struct nursery_ {
57 bdescr * blocks;
58 unsigned int n_blocks;
59 } nursery;
60
61 typedef struct generation_ {
62 unsigned int no; // generation number
63
64 bdescr * blocks; // blocks in this gen
65 unsigned int n_blocks; // number of blocks
66 unsigned int n_words; // number of used words
67
68 bdescr * large_objects; // large objects (doubly linked)
69 unsigned int n_large_blocks; // no. of blocks used by large objs
70 unsigned long n_new_large_words; // words of new large objects
71 // (for allocation stats)
72
73 unsigned int max_blocks; // max blocks
74
75 StgTSO * threads; // threads in this gen
76 // linked via global_link
77 struct generation_ *to; // destination gen for live objects
78
79 // stats information
80 unsigned int collections;
81 unsigned int par_collections;
82 unsigned int failed_promotions;
83
84 // ------------------------------------
85 // Fields below are used during GC only
86
87 #if defined(THREADED_RTS)
88 char pad[128]; // make sure the following is
89 // on a separate cache line.
90 SpinLock sync_large_objects; // lock for large_objects
91 // and scavenged_large_objects
92 #endif
93
94 int mark; // mark (not copy)? (old gen only)
95 int compact; // compact (not sweep)? (old gen only)
96
97 // During GC, if we are collecting this gen, blocks and n_blocks
98 // are copied into the following two fields. After GC, these blocks
99 // are freed.
100 bdescr * old_blocks; // bdescr of first from-space block
101 unsigned int n_old_blocks; // number of blocks in from-space
102 unsigned int live_estimate; // for sweeping: estimate of live data
103
104 bdescr * part_blocks; // partially-full scanned blocks
105 unsigned int n_part_blocks; // count of above
106
107 bdescr * scavenged_large_objects; // live large objs after GC (d-link)
108 unsigned int n_scavenged_large_blocks; // size (not count) of above
109
110 bdescr * bitmap; // bitmap for compacting collection
111
112 StgTSO * old_threads;
113 } generation;
114
115 extern generation * generations;
116 extern generation * g0;
117 extern generation * oldest_gen;
118
119 /* -----------------------------------------------------------------------------
120 Generic allocation
121
122 StgPtr allocate(Capability *cap, nat n)
123 Allocates memory from the nursery in
124 the current Capability. This can be
125 done without taking a global lock,
126 unlike allocate().
127
128 StgPtr allocatePinned(Capability *cap, nat n)
129 Allocates a chunk of contiguous store
130 n words long, which is at a fixed
131 address (won't be moved by GC).
132 Returns a pointer to the first word.
133 Always succeeds.
134
135 NOTE: the GC can't in general handle
136 pinned objects, so allocatePinned()
137 can only be used for ByteArrays at the
138 moment.
139
140 Don't forget to TICK_ALLOC_XXX(...)
141 after calling allocate or
142 allocatePinned, for the
143 benefit of the ticky-ticky profiler.
144
145 -------------------------------------------------------------------------- */
146
147 StgPtr allocate ( Capability *cap, lnat n );
148 StgPtr allocatePinned ( Capability *cap, lnat n );
149
150 /* memory allocator for executable memory */
151 void * allocateExec(unsigned int len, void **exec_addr);
152 void freeExec (void *p);
153
154 // Used by GC checks in external .cmm code:
155 extern nat large_alloc_lim;
156
157 /* -----------------------------------------------------------------------------
158 Performing Garbage Collection
159 -------------------------------------------------------------------------- */
160
161 void performGC(void);
162 void performMajorGC(void);
163
164 /* -----------------------------------------------------------------------------
165 The CAF table - used to let us revert CAFs in GHCi
166 -------------------------------------------------------------------------- */
167
168 void newCAF (StgRegTable *reg, StgClosure *);
169 void newDynCAF (StgRegTable *reg, StgClosure *);
170 void revertCAFs (void);
171
172 // Request that all CAFs are retained indefinitely.
173 void setKeepCAFs (void);
174
175 /* -----------------------------------------------------------------------------
176 Stats
177 -------------------------------------------------------------------------- */
178
179 // Returns the total number of bytes allocated since the start of the program.
180 HsInt64 getAllocations (void);
181
182 /* -----------------------------------------------------------------------------
183 This is the write barrier for MUT_VARs, a.k.a. IORefs. A
184 MUT_VAR_CLEAN object is not on the mutable list; a MUT_VAR_DIRTY
185 is. When written to, a MUT_VAR_CLEAN turns into a MUT_VAR_DIRTY
186 and is put on the mutable list.
187 -------------------------------------------------------------------------- */
188
189 void dirty_MUT_VAR(StgRegTable *reg, StgClosure *p);
190
191 /* set to disable CAF garbage collection in GHCi. */
192 /* (needed when dynamic libraries are used). */
193 extern rtsBool keepCAFs;
194
195 INLINE_HEADER void initBdescr(bdescr *bd, generation *gen, generation *dest)
196 {
197 bd->gen = gen;
198 bd->gen_no = gen->no;
199 bd->dest_no = dest->no;
200 }
201
202 #endif /* RTS_STORAGE_GC_H */