2aed7c57eecfc039159a8b00aeb0554517a2d0ae
[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 #pragma once
10
11 #include <stddef.h>
12 #include "rts/OSThreads.h"
13
14 /* -----------------------------------------------------------------------------
15 * Generational GC
16 *
17 * We support an arbitrary number of generations. Notes (in no particular
18 * order):
19 *
20 * - Objects "age" in the nursery for one GC cycle before being promoted
21 * to the next generation. There is no aging in other generations.
22 *
23 * - generation 0 is the allocation area. It is given
24 * a fixed set of blocks during initialisation, and these blocks
25 * normally stay in G0S0. In parallel execution, each
26 * Capability has its own nursery.
27 *
28 * - during garbage collection, each generation which is an
29 * evacuation destination (i.e. all generations except G0) is
30 * allocated a to-space. evacuated objects are allocated into
31 * the generation's to-space until GC is finished, when the
32 * original generations's contents may be freed and replaced
33 * by the to-space.
34 *
35 * - the mutable-list is per-generation. G0 doesn't have one
36 * (since every garbage collection collects at least G0).
37 *
38 * - block descriptors contain a pointer to the generation that
39 * the block belongs to, for convenience.
40 *
41 * - static objects are stored in per-generation lists. See GC.c for
42 * details of how we collect CAFs in the generational scheme.
43 *
44 * - large objects are per-generation, and are promoted in the
45 * same way as small objects.
46 *
47 * ------------------------------------------------------------------------- */
48
49 // A count of blocks needs to store anything up to the size of memory
50 // divided by the block size. The safest thing is therefore to use a
51 // type that can store the full range of memory addresses,
52 // ie. StgWord. Note that we have had some tricky int overflows in a
53 // couple of cases caused by using ints rather than longs (e.g. #5086)
54
55 typedef StgWord memcount;
56
57 typedef struct nursery_ {
58 bdescr * blocks;
59 memcount n_blocks;
60 } nursery;
61
62 // Nursery invariants:
63 //
64 // - cap->r.rNursery points to the nursery for this capability
65 //
66 // - cap->r.rCurrentNursery points to the block in the nursery that we are
67 // currently allocating into. While in Haskell the current heap pointer is
68 // in Hp, outside Haskell it is stored in cap->r.rCurrentNursery->free.
69 //
70 // - the blocks *after* cap->rCurrentNursery in the chain are empty
71 // (although their bd->free pointers have not been updated to
72 // reflect that)
73 //
74 // - the blocks *before* cap->rCurrentNursery have been used. Except
75 // for rCurrentAlloc.
76 //
77 // - cap->r.rCurrentAlloc is either NULL, or it points to a block in
78 // the nursery *before* cap->r.rCurrentNursery.
79 //
80 // See also Note [allocation accounting] to understand how total
81 // memory allocation is tracked.
82
83 typedef struct generation_ {
84 uint32_t no; // generation number
85
86 bdescr * blocks; // blocks in this gen
87 memcount n_blocks; // number of blocks
88 memcount n_words; // number of used words
89
90 bdescr * large_objects; // large objects (doubly linked)
91 memcount n_large_blocks; // no. of blocks used by large objs
92 memcount n_large_words; // no. of words used by large objs
93 memcount n_new_large_words; // words of new large objects
94 // (for doYouWantToGC())
95
96 bdescr * compact_objects; // compact objects chain
97 // the second block in each compact is
98 // linked from the closure object, while
99 // the second compact object in the
100 // chain is linked from bd->link (like
101 // large objects)
102 memcount n_compact_blocks; // no. of blocks used by all compacts
103 bdescr * compact_blocks_in_import; // compact objects being imported
104 // (not known to the GC because
105 // potentially invalid, but we
106 // need to keep track of them
107 // to avoid assertions in Sanity)
108 // this is a list shaped like compact_objects
109 memcount n_compact_blocks_in_import; // no. of blocks used by compacts
110 // being imported
111
112 memcount max_blocks; // max blocks
113
114 StgTSO * threads; // threads in this gen
115 // linked via global_link
116 StgWeak * weak_ptr_list; // weak pointers in this gen
117
118 struct generation_ *to; // destination gen for live objects
119
120 // stats information
121 uint32_t collections;
122 uint32_t par_collections;
123 uint32_t failed_promotions;
124
125 // ------------------------------------
126 // Fields below are used during GC only
127
128 #if defined(THREADED_RTS)
129 char pad[128]; // make sure the following is
130 // on a separate cache line.
131 SpinLock sync; // lock for large_objects
132 // and scavenged_large_objects
133 #endif
134
135 int mark; // mark (not copy)? (old gen only)
136 int compact; // compact (not sweep)? (old gen only)
137
138 // During GC, if we are collecting this gen, blocks and n_blocks
139 // are copied into the following two fields. After GC, these blocks
140 // are freed.
141 bdescr * old_blocks; // bdescr of first from-space block
142 memcount n_old_blocks; // number of blocks in from-space
143 memcount live_estimate; // for sweeping: estimate of live data
144
145 bdescr * scavenged_large_objects; // live large objs after GC (d-link)
146 memcount n_scavenged_large_blocks; // size (not count) of above
147
148 bdescr * live_compact_objects; // live compact objs after GC (d-link)
149 memcount n_live_compact_blocks; // size (not count) of above
150
151 bdescr * bitmap; // bitmap for compacting collection
152
153 StgTSO * old_threads;
154 StgWeak * old_weak_ptr_list;
155 } generation;
156
157 extern generation * generations;
158 extern generation * g0;
159 extern generation * oldest_gen;
160
161 /* -----------------------------------------------------------------------------
162 Generic allocation
163
164 StgPtr allocate(Capability *cap, W_ n)
165 Allocates memory from the nursery in
166 the current Capability.
167
168 StgPtr allocatePinned(Capability *cap, W_ n)
169 Allocates a chunk of contiguous store
170 n words long, which is at a fixed
171 address (won't be moved by GC).
172 Returns a pointer to the first word.
173 Always succeeds.
174
175 NOTE: the GC can't in general handle
176 pinned objects, so allocatePinned()
177 can only be used for ByteArrays at the
178 moment.
179
180 Don't forget to TICK_ALLOC_XXX(...)
181 after calling allocate or
182 allocatePinned, for the
183 benefit of the ticky-ticky profiler.
184
185 -------------------------------------------------------------------------- */
186
187 StgPtr allocate ( Capability *cap, W_ n );
188 StgPtr allocateMightFail ( Capability *cap, W_ n );
189 StgPtr allocatePinned ( Capability *cap, W_ n );
190
191 /* memory allocator for executable memory */
192 typedef void* AdjustorWritable;
193 typedef void* AdjustorExecutable;
194
195 AdjustorWritable allocateExec(W_ len, AdjustorExecutable *exec_addr);
196 void flushExec(W_ len, AdjustorExecutable exec_addr);
197 #if defined(ios_HOST_OS)
198 AdjustorWritable execToWritable(AdjustorExecutable exec);
199 #endif
200 void freeExec (AdjustorExecutable p);
201
202 // Used by GC checks in external .cmm code:
203 extern W_ large_alloc_lim;
204
205 /* -----------------------------------------------------------------------------
206 Performing Garbage Collection
207 -------------------------------------------------------------------------- */
208
209 void performGC(void);
210 void performMajorGC(void);
211
212 /* -----------------------------------------------------------------------------
213 The CAF table - used to let us revert CAFs in GHCi
214 -------------------------------------------------------------------------- */
215
216 StgInd *newCAF (StgRegTable *reg, StgIndStatic *caf);
217 StgInd *newRetainedCAF (StgRegTable *reg, StgIndStatic *caf);
218 StgInd *newGCdCAF (StgRegTable *reg, StgIndStatic *caf);
219 void revertCAFs (void);
220
221 // Request that all CAFs are retained indefinitely.
222 // (preferably use RtsConfig.keep_cafs instead)
223 void setKeepCAFs (void);
224
225 /* -----------------------------------------------------------------------------
226 This is the write barrier for MUT_VARs, a.k.a. IORefs. A
227 MUT_VAR_CLEAN object is not on the mutable list; a MUT_VAR_DIRTY
228 is. When written to, a MUT_VAR_CLEAN turns into a MUT_VAR_DIRTY
229 and is put on the mutable list.
230 -------------------------------------------------------------------------- */
231
232 void dirty_MUT_VAR(StgRegTable *reg, StgClosure *p);
233
234 /* set to disable CAF garbage collection in GHCi. */
235 /* (needed when dynamic libraries are used). */
236 extern bool keepCAFs;
237
238 INLINE_HEADER void initBdescr(bdescr *bd, generation *gen, generation *dest)
239 {
240 bd->gen = gen;
241 bd->gen_no = gen->no;
242 bd->dest_no = dest->no;
243 }