1 /* ----------------------------------------------------------------------------
3 * (c) The GHC Team, 1998-2004
7 * -------------------------------------------------------------------------- */
9 #ifndef RTS_STORAGE_CLOSURES_H
10 #define RTS_STORAGE_CLOSURES_H
13 * The Layout of a closure header depends on which kind of system we're
14 * compiling for: profiling, parallel, ticky, etc.
17 /* -----------------------------------------------------------------------------
19 -------------------------------------------------------------------------- */
24 struct _RetainerSet *rs; /* Retainer Set */
25 StgWord ldvw; /* Lag/Drag/Void Word */
29 /* -----------------------------------------------------------------------------
32 A thunk has a padding word to take the updated value. This is so
33 that the update doesn't overwrite the payload, so we can avoid
34 needing to lock the thunk during entry and update.
36 Note: this doesn't apply to THUNK_STATICs, which have no payload.
38 Note: we leave this padding word in all ways, rather than just SMP,
39 so that we don't have to recompile all our libraries for SMP.
40 -------------------------------------------------------------------------- */
46 /* -----------------------------------------------------------------------------
47 The full fixed-size closure header
49 The size of the fixed header is the sum of the optional parts plus a single
50 word for the entry code pointer.
51 -------------------------------------------------------------------------- */
54 const StgInfoTable* info;
61 const StgInfoTable* info;
65 StgSMPThunkHeader smp;
68 #define THUNK_EXTRA_HEADER_W (sizeofW(StgThunkHeader)-sizeofW(StgHeader))
70 /* -----------------------------------------------------------------------------
73 For any given closure type (defined in InfoTables.h), there is a
74 corresponding structure defined below. The name of the structure
75 is obtained by concatenating the closure type with '_closure'
76 -------------------------------------------------------------------------- */
78 /* All closures follow the generic format */
80 typedef struct StgClosure_ {
82 struct StgClosure_ *payload[FLEXIBLE_ARRAY];
83 } *StgClosurePtr; // StgClosure defined in Rts.h
86 StgThunkHeader header;
87 struct StgClosure_ *payload[FLEXIBLE_ARRAY];
91 StgThunkHeader header;
97 StgHalfWord arity; /* zero if it is an AP */
99 StgClosure *fun; /* really points to a fun */
100 StgClosure *payload[FLEXIBLE_ARRAY];
104 StgThunkHeader header;
105 StgHalfWord arity; /* zero if it is an AP */
107 StgClosure *fun; /* really points to a fun */
108 StgClosure *payload[FLEXIBLE_ARRAY];
112 StgThunkHeader header;
113 StgWord size; /* number of words in payload */
115 StgClosure *payload[FLEXIBLE_ARRAY]; /* contains a chunk of *stack* */
120 StgClosure *indirectee;
125 StgClosure *indirectee;
126 StgClosure *static_link;
127 StgInfoTable *saved_info;
130 typedef struct StgBlockingQueue_ {
132 struct StgBlockingQueue_ *link; // here so it looks like an IND
133 StgClosure *bh; // the BLACKHOLE
135 struct MessageBlackHole_ *queue;
141 StgWord payload[FLEXIBLE_ARRAY];
147 StgWord size; // ptrs plus card table
148 StgClosure *payload[FLEXIBLE_ARRAY];
149 // see also: StgMutArrPtrs macros in ClosureMacros.h
157 typedef struct _StgUpdateFrame {
164 StgWord exceptions_blocked;
175 } StgIntCharlikeClosure;
177 /* statically allocated */
182 typedef struct _StgStableName {
187 typedef struct _StgWeak { /* Weak v */
189 StgClosure *cfinalizer;
191 StgClosure *value; /* v */
192 StgClosure *finalizer;
193 struct _StgWeak *link;
196 typedef struct _StgDeadWeak { /* Weak v */
198 struct _StgWeak *link;
201 /* Byte code objects. These are fixed size objects with pointers to
202 * four arrays, designed so that a BCO can be easily "re-linked" to
203 * other BCOs, to facilitate GHC's intelligent recompilation. The
204 * array of instructions is static and not re-generated when the BCO
205 * is re-linked, but the other 3 arrays will be regenerated.
207 * A BCO represents either a function or a stack frame. In each case,
208 * it needs a bitmap to describe to the garbage collector the
209 * pointerhood of its arguments/free variables respectively, and in
210 * the case of a function it also needs an arity. These are stored
211 * directly in the BCO, rather than in the instrs array, for two
213 * (a) speed: we need to get at the bitmap info quickly when
214 * the GC is examining APs and PAPs that point to this BCO
215 * (b) a subtle interaction with the compacting GC. In compacting
216 * GC, the info that describes the size/layout of a closure
217 * cannot be in an object more than one level of indirection
218 * away from the current object, because of the order in
219 * which pointers are updated to point to their new locations.
224 StgArrWords *instrs; /* a pointer to an ArrWords */
225 StgArrWords *literals; /* a pointer to an ArrWords */
226 StgMutArrPtrs *ptrs; /* a pointer to a MutArrPtrs */
227 StgHalfWord arity; /* arity of this BCO */
228 StgHalfWord size; /* size of this BCO (in words) */
229 StgWord bitmap[FLEXIBLE_ARRAY]; /* an StgLargeBitmap */
232 #define BCO_BITMAP(bco) ((StgLargeBitmap *)((StgBCO *)(bco))->bitmap)
233 #define BCO_BITMAP_SIZE(bco) (BCO_BITMAP(bco)->size)
234 #define BCO_BITMAP_BITS(bco) (BCO_BITMAP(bco)->bitmap)
235 #define BCO_BITMAP_SIZEW(bco) ((BCO_BITMAP_SIZE(bco) + BITS_IN(StgWord) - 1) \
238 /* -----------------------------------------------------------------------------
239 Dynamic stack frames for generic heap checks.
241 These generic heap checks are slow, but have the advantage of being
242 usable in a variety of situations.
244 The one restriction is that any relevant SRTs must already be pointed
245 to from the stack. The return address doesn't need to have an info
246 table attached: hence it can be any old code pointer.
248 The liveness mask contains a 1 at bit n, if register Rn contains a
249 non-pointer. The contents of all 8 vanilla registers are always saved
250 on the stack; the liveness mask tells the GC which ones contain
253 Good places to use a generic heap check:
255 - case alternatives (the return address with an SRT is already
258 - primitives (no SRT required).
260 The stack frame layout for a RET_DYN is like this:
262 some pointers |-- RET_DYN_PTRS(liveness) words
263 some nonpointers |-- RET_DYN_NONPTRS(liveness) words
266 D1-2 |-- RET_DYN_NONPTR_REGS_SIZE words
269 R1-8 |-- RET_DYN_BITMAP_SIZE words
272 liveness mask |-- StgRetDyn structure
275 we assume that the size of a double is always 2 pointers (wasting a
276 word when it is only one pointer, but avoiding lots of #ifdefs).
278 See Liveness.h for the macros (RET_DYN_PTRS() etc.).
280 NOTE: if you change the layout of RET_DYN stack frames, then you
281 might also need to adjust the value of RESERVED_STACK_WORDS in
283 -------------------------------------------------------------------------- */
286 const StgInfoTable* info;
289 StgClosure * payload[FLEXIBLE_ARRAY];
292 /* A function return stack frame: used when saving the state for a
293 * garbage collection at a function entry point. The function
294 * arguments are on the stack, and we also save the function (its
295 * info table describes the pointerhood of the arguments).
297 * The stack frame size is also cached in the frame for convenience.
300 const StgInfoTable* info;
303 StgClosure * payload[FLEXIBLE_ARRAY];
306 /* Concurrent communication objects */
308 typedef struct StgMVarTSOQueue_ {
310 struct StgMVarTSOQueue_ *link;
316 struct StgMVarTSOQueue_ *head;
317 struct StgMVarTSOQueue_ *tail;
322 /* STM data structures
324 * StgTVar defines the only type that can be updated through the STM
327 * Note that various optimisations may be possible in order to use less
328 * space for these data structures at the cost of more complexity in the
331 * - In StgTVar, current_value and first_watch_queue_entry could be held in
332 * the same field: if any thread is waiting then its expected_value for
333 * the tvar is the current value.
335 * - In StgTRecHeader, it might be worthwhile having separate chunks
336 * of read-only and read-write locations. This would save a
337 * new_value field in the read-only locations.
339 * - In StgAtomicallyFrame, we could combine the waiting bit into
340 * the header (maybe a different info tbl for a waiting transaction).
341 * This means we can specialise the code for the atomically frame
342 * (it immediately switches on frame->waiting anyway).
345 typedef struct StgTRecHeader_ StgTRecHeader;
347 typedef struct StgTVarWatchQueue_ {
349 StgClosure *closure; // StgTSO or StgAtomicInvariant
350 struct StgTVarWatchQueue_ *next_queue_entry;
351 struct StgTVarWatchQueue_ *prev_queue_entry;
356 StgClosure *volatile current_value;
357 StgTVarWatchQueue *volatile first_watch_queue_entry;
358 #if defined(THREADED_RTS)
359 StgInt volatile num_updates;
366 StgTRecHeader *last_execution;
368 } StgAtomicInvariant;
370 /* new_value == expected_value for read-only accesses */
371 /* new_value is a StgTVarWatchQueue entry when trec in state TREC_WAITING */
374 StgClosure *expected_value;
375 StgClosure *new_value;
376 #if defined(THREADED_RTS)
381 #define TREC_CHUNK_NUM_ENTRIES 16
383 typedef struct StgTRecChunk_ {
385 struct StgTRecChunk_ *prev_chunk;
386 StgWord next_entry_idx;
387 TRecEntry entries[TREC_CHUNK_NUM_ENTRIES];
391 TREC_ACTIVE, /* Transaction in progress, outcome undecided */
392 TREC_CONDEMNED, /* Transaction in progress, inconsistent / out of date reads */
393 TREC_COMMITTED, /* Transaction has committed, now updating tvars */
394 TREC_ABORTED, /* Transaction has aborted, now reverting tvars */
395 TREC_WAITING, /* Transaction currently waiting */
398 typedef struct StgInvariantCheckQueue_ {
400 StgAtomicInvariant *invariant;
401 StgTRecHeader *my_execution;
402 struct StgInvariantCheckQueue_ *next_queue_entry;
403 } StgInvariantCheckQueue;
405 struct StgTRecHeader_ {
407 struct StgTRecHeader_ *enclosing_trec;
408 StgTRecChunk *current_chunk;
409 StgInvariantCheckQueue *invariants_to_check;
416 StgTVarWatchQueue *next_invariant_to_check;
418 } StgAtomicallyFrame;
428 StgBool running_alt_code;
429 StgClosure *first_code;
430 StgClosure *alt_code;
431 } StgCatchRetryFrame;
433 /* ----------------------------------------------------------------------------
435 ------------------------------------------------------------------------- */
437 typedef struct Message_ {
439 struct Message_ *link;
442 typedef struct MessageWakeup_ {
448 typedef struct MessageThrowTo_ {
450 struct MessageThrowTo_ *link;
453 StgClosure *exception;
456 typedef struct MessageBlackHole_ {
458 struct MessageBlackHole_ *link;
463 #endif /* RTS_STORAGE_CLOSURES_H */