includes/rts/storage/Closures.h

   1 /* ----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 1998-2004
   4  *
   5  * Closures
   6  *
   7  * -------------------------------------------------------------------------- */
   8
   9 #ifndef RTS_STORAGE_CLOSURES_H
  10 #define RTS_STORAGE_CLOSURES_H
  11
  12 /*
  13  * The Layout of a closure header depends on which kind of system we're
  14  * compiling for: profiling, parallel, ticky, etc.
  15  */
  16
  17 /* -----------------------------------------------------------------------------
  18    The profiling header
  19    -------------------------------------------------------------------------- */
  20
  21 typedef struct {
  22   CostCentreStack *ccs;
  23   union {
  24     struct _RetainerSet *rs;  /* Retainer Set */
  25     StgWord ldvw;             /* Lag/Drag/Void Word */
  26   } hp;
  27 } StgProfHeader;
  28
  29 /* -----------------------------------------------------------------------------
  30    The SMP header
  31
  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.
  35
  36    Note: this doesn't apply to THUNK_STATICs, which have no payload.
  37
  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    -------------------------------------------------------------------------- */
  41
  42 typedef struct {
  43     StgWord pad;
  44 } StgSMPThunkHeader;
  45
  46 /* -----------------------------------------------------------------------------
  47    The full fixed-size closure header
  48
  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    -------------------------------------------------------------------------- */
  52
  53 typedef struct {
  54     const StgInfoTable* info;
  55 #ifdef PROFILING
  56     StgProfHeader         prof;
  57 #endif
  58 } StgHeader;
  59
  60 typedef struct {
  61     const StgInfoTable* info;
  62 #ifdef PROFILING
  63     StgProfHeader         prof;
  64 #endif
  65     StgSMPThunkHeader     smp;
  66 } StgThunkHeader;
  67
  68 #define THUNK_EXTRA_HEADER_W (sizeofW(StgThunkHeader)-sizeofW(StgHeader))
  69
  70 /* -----------------------------------------------------------------------------
  71    Closure Types
  72
  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    -------------------------------------------------------------------------- */
  77
  78 /* All closures follow the generic format */
  79
  80 typedef struct StgClosure_ {
  81     StgHeader   header;
  82     struct StgClosure_ *payload[FLEXIBLE_ARRAY];
  83 } *StgClosurePtr; // StgClosure defined in Rts.h
  84
  85 typedef struct {
  86     StgThunkHeader  header;
  87     struct StgClosure_ *payload[FLEXIBLE_ARRAY];
  88 } StgThunk;
  89
  90 typedef struct {
  91     StgThunkHeader   header;
  92     StgClosure *selectee;
  93 } StgSelector;
  94
  95 typedef struct {
  96     StgHeader   header;
  97     StgHalfWord arity;          /* zero if it is an AP */
  98     StgHalfWord n_args;
  99     StgClosure *fun;            /* really points to a fun */
 100     StgClosure *payload[FLEXIBLE_ARRAY];
 101 } StgPAP;
 102
 103 typedef struct {
 104     StgThunkHeader   header;
 105     StgHalfWord arity;          /* zero if it is an AP */
 106     StgHalfWord n_args;
 107     StgClosure *fun;            /* really points to a fun */
 108     StgClosure *payload[FLEXIBLE_ARRAY];
 109 } StgAP;
 110
 111 typedef struct {
 112     StgThunkHeader   header;
 113     StgWord     size;                    /* number of words in payload */
 114     StgClosure *fun;
 115     StgClosure *payload[FLEXIBLE_ARRAY]; /* contains a chunk of *stack* */
 116 } StgAP_STACK;
 117
 118 typedef struct {
 119     StgHeader   header;
 120     StgClosure *indirectee;
 121 } StgInd;
 122
 123 typedef struct {
 124     StgHeader     header;
 125     StgClosure   *indirectee;
 126     StgClosure   *static_link;
 127     StgInfoTable *saved_info;
 128 } StgIndStatic;
 129
 130 typedef struct {
 131     StgHeader  header;
 132     StgWord    words;
 133     StgWord    payload[FLEXIBLE_ARRAY];
 134 } StgArrWords;
 135
 136 typedef struct {
 137     StgHeader   header;
 138     StgWord     ptrs;
 139     StgClosure *payload[FLEXIBLE_ARRAY];
 140 } StgMutArrPtrs;
 141
 142 typedef struct {
 143     StgHeader   header;
 144     StgClosure *var;
 145 } StgMutVar;
 146
 147 typedef struct _StgUpdateFrame {
 148     StgHeader  header;
 149     StgClosure *updatee;
 150 } StgUpdateFrame;
 151
 152 typedef struct {
 153     StgHeader  header;
 154     StgInt      exceptions_blocked;
 155     StgClosure *handler;
 156 } StgCatchFrame;
 157
 158 typedef struct {
 159     StgHeader  header;
 160 } StgStopFrame;
 161
 162 typedef struct {
 163   StgHeader header;
 164   StgWord data;
 165 } StgIntCharlikeClosure;
 166
 167 /* statically allocated */
 168 typedef struct {
 169   StgHeader  header;
 170 } StgRetry;
 171
 172 typedef struct _StgStableName {
 173   StgHeader      header;
 174   StgWord        sn;
 175 } StgStableName;
 176
 177 typedef struct _StgWeak {       /* Weak v */
 178   StgHeader header;
 179   StgClosure *cfinalizer;
 180   StgClosure *key;
 181   StgClosure *value;            /* v */
 182   StgClosure *finalizer;
 183   struct _StgWeak *link;
 184 } StgWeak;
 185
 186 typedef struct _StgDeadWeak {   /* Weak v */
 187   StgHeader header;
 188   struct _StgWeak *link;
 189 } StgDeadWeak;
 190
 191 /* Byte code objects.  These are fixed size objects with pointers to
 192  * four arrays, designed so that a BCO can be easily "re-linked" to
 193  * other BCOs, to facilitate GHC's intelligent recompilation.  The
 194  * array of instructions is static and not re-generated when the BCO
 195  * is re-linked, but the other 3 arrays will be regenerated.
 196  *
 197  * A BCO represents either a function or a stack frame.  In each case,
 198  * it needs a bitmap to describe to the garbage collector the
 199  * pointerhood of its arguments/free variables respectively, and in
 200  * the case of a function it also needs an arity.  These are stored
 201  * directly in the BCO, rather than in the instrs array, for two
 202  * reasons:
 203  * (a) speed: we need to get at the bitmap info quickly when
 204  *     the GC is examining APs and PAPs that point to this BCO
 205  * (b) a subtle interaction with the compacting GC.  In compacting
 206  *     GC, the info that describes the size/layout of a closure
 207  *     cannot be in an object more than one level of indirection
 208  *     away from the current object, because of the order in
 209  *     which pointers are updated to point to their new locations.
 210  */
 211
 212 typedef struct {
 213     StgHeader      header;
 214     StgArrWords   *instrs;      /* a pointer to an ArrWords */
 215     StgArrWords   *literals;    /* a pointer to an ArrWords */
 216     StgMutArrPtrs *ptrs;        /* a pointer to a  MutArrPtrs */
 217     StgHalfWord   arity;        /* arity of this BCO */
 218     StgHalfWord   size;         /* size of this BCO (in words) */
 219     StgWord       bitmap[FLEXIBLE_ARRAY];  /* an StgLargeBitmap */
 220 } StgBCO;
 221
 222 #define BCO_BITMAP(bco)      ((StgLargeBitmap *)((StgBCO *)(bco))->bitmap)
 223 #define BCO_BITMAP_SIZE(bco) (BCO_BITMAP(bco)->size)
 224 #define BCO_BITMAP_BITS(bco) (BCO_BITMAP(bco)->bitmap)
 225 #define BCO_BITMAP_SIZEW(bco) ((BCO_BITMAP_SIZE(bco) + BITS_IN(StgWord) - 1) \
 226                                 / BITS_IN(StgWord))
 227
 228 /* -----------------------------------------------------------------------------
 229    Dynamic stack frames for generic heap checks.
 230
 231    These generic heap checks are slow, but have the advantage of being
 232    usable in a variety of situations.
 233
 234    The one restriction is that any relevant SRTs must already be pointed
 235    to from the stack.  The return address doesn't need to have an info
 236    table attached: hence it can be any old code pointer.
 237
 238    The liveness mask contains a 1 at bit n, if register Rn contains a
 239    non-pointer.  The contents of all 8 vanilla registers are always saved
 240    on the stack; the liveness mask tells the GC which ones contain
 241    pointers.
 242
 243    Good places to use a generic heap check:
 244
 245         - case alternatives (the return address with an SRT is already
 246           on the stack).
 247
 248         - primitives (no SRT required).
 249
 250    The stack frame layout for a RET_DYN is like this:
 251
 252           some pointers         |-- RET_DYN_PTRS(liveness) words
 253           some nonpointers      |-- RET_DYN_NONPTRS(liveness) words
 254
 255           L1                    \
 256           D1-2                  |-- RET_DYN_NONPTR_REGS_SIZE words
 257           F1-4                  /
 258
 259           R1-8                  |-- RET_DYN_BITMAP_SIZE words
 260
 261           return address        \
 262           liveness mask         |-- StgRetDyn structure
 263           stg_gen_chk_info      /
 264
 265    we assume that the size of a double is always 2 pointers (wasting a
 266    word when it is only one pointer, but avoiding lots of #ifdefs).
 267
 268    See Liveness.h for the macros (RET_DYN_PTRS() etc.).
 269
 270    NOTE: if you change the layout of RET_DYN stack frames, then you
 271    might also need to adjust the value of RESERVED_STACK_WORDS in
 272    Constants.h.
 273    -------------------------------------------------------------------------- */
 274
 275 typedef struct {
 276     const StgInfoTable* info;
 277     StgWord        liveness;
 278     StgWord        ret_addr;
 279     StgClosure *   payload[FLEXIBLE_ARRAY];
 280 } StgRetDyn;
 281
 282 /* A function return stack frame: used when saving the state for a
 283  * garbage collection at a function entry point.  The function
 284  * arguments are on the stack, and we also save the function (its
 285  * info table describes the pointerhood of the arguments).
 286  *
 287  * The stack frame size is also cached in the frame for convenience.
 288  */
 289 typedef struct {
 290     const StgInfoTable* info;
 291     StgWord        size;
 292     StgClosure *   fun;
 293     StgClosure *   payload[FLEXIBLE_ARRAY];
 294 } StgRetFun;
 295
 296 /* Concurrent communication objects */
 297
 298 typedef struct {
 299   StgHeader       header;
 300   struct StgTSO_ *head;
 301   struct StgTSO_ *tail;
 302   StgClosure*     value;
 303 } StgMVar;
 304
 305
 306 /* STM data structures
 307  *
 308  *  StgTVar defines the only type that can be updated through the STM
 309  *  interface.
 310  *
 311  *  Note that various optimisations may be possible in order to use less
 312  *  space for these data structures at the cost of more complexity in the
 313  *  implementation:
 314  *
 315  *   - In StgTVar, current_value and first_watch_queue_entry could be held in
 316  *     the same field: if any thread is waiting then its expected_value for
 317  *     the tvar is the current value.
 318  *
 319  *   - In StgTRecHeader, it might be worthwhile having separate chunks
 320  *     of read-only and read-write locations.  This would save a
 321  *     new_value field in the read-only locations.
 322  *
 323  *   - In StgAtomicallyFrame, we could combine the waiting bit into
 324  *     the header (maybe a different info tbl for a waiting transaction).
 325  *     This means we can specialise the code for the atomically frame
 326  *     (it immediately switches on frame->waiting anyway).
 327  */
 328
 329 typedef struct StgTRecHeader_ StgTRecHeader;
 330
 331 typedef struct StgTVarWatchQueue_ {
 332   StgHeader                  header;
 333   StgClosure                *closure; // StgTSO or StgAtomicInvariant
 334   struct StgTVarWatchQueue_ *next_queue_entry;
 335   struct StgTVarWatchQueue_ *prev_queue_entry;
 336 } StgTVarWatchQueue;
 337
 338 typedef struct {
 339   StgHeader                  header;
 340   StgClosure                *volatile current_value;
 341   StgTVarWatchQueue         *volatile first_watch_queue_entry;
 342 #if defined(THREADED_RTS)
 343   StgInt                     volatile num_updates;
 344 #endif
 345 } StgTVar;
 346
 347 typedef struct {
 348   StgHeader      header;
 349   StgClosure    *code;
 350   StgTRecHeader *last_execution;
 351   StgWord        lock;
 352 } StgAtomicInvariant;
 353
 354 /* new_value == expected_value for read-only accesses */
 355 /* new_value is a StgTVarWatchQueue entry when trec in state TREC_WAITING */
 356 typedef struct {
 357   StgTVar                   *tvar;
 358   StgClosure                *expected_value;
 359   StgClosure                *new_value;
 360 #if defined(THREADED_RTS)
 361   StgInt                     num_updates;
 362 #endif
 363 } TRecEntry;
 364
 365 #define TREC_CHUNK_NUM_ENTRIES 16
 366
 367 typedef struct StgTRecChunk_ {
 368   StgHeader                  header;
 369   struct StgTRecChunk_      *prev_chunk;
 370   StgWord                    next_entry_idx;
 371   TRecEntry                  entries[TREC_CHUNK_NUM_ENTRIES];
 372 } StgTRecChunk;
 373
 374 typedef enum {
 375   TREC_ACTIVE,        /* Transaction in progress, outcome undecided */
 376   TREC_CONDEMNED,     /* Transaction in progress, inconsistent / out of date reads */
 377   TREC_COMMITTED,     /* Transaction has committed, now updating tvars */
 378   TREC_ABORTED,       /* Transaction has aborted, now reverting tvars */
 379   TREC_WAITING,       /* Transaction currently waiting */
 380 } TRecState;
 381
 382 typedef struct StgInvariantCheckQueue_ {
 383   StgHeader                       header;
 384   StgAtomicInvariant             *invariant;
 385   StgTRecHeader                  *my_execution;
 386   struct StgInvariantCheckQueue_ *next_queue_entry;
 387 } StgInvariantCheckQueue;
 388
 389 struct StgTRecHeader_ {
 390   StgHeader                  header;
 391   TRecState                  state;
 392   struct StgTRecHeader_     *enclosing_trec;
 393   StgTRecChunk              *current_chunk;
 394   StgInvariantCheckQueue    *invariants_to_check;
 395 };
 396
 397 typedef struct {
 398   StgHeader   header;
 399   StgClosure *code;
 400   StgTVarWatchQueue *next_invariant_to_check;
 401   StgClosure *result;
 402 } StgAtomicallyFrame;
 403
 404 typedef struct {
 405   StgHeader   header;
 406   StgClosure *code;
 407   StgClosure *handler;
 408 } StgCatchSTMFrame;
 409
 410 typedef struct {
 411   StgHeader      header;
 412   StgBool        running_alt_code;
 413   StgClosure    *first_code;
 414   StgClosure    *alt_code;
 415 } StgCatchRetryFrame;
 416
 417 #endif /* RTS_STORAGE_CLOSURES_H */