ghc/includes/Closures.h

   1 /* ----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 1998-2004
   4  *
   5  * Closures
   6  *
   7  * -------------------------------------------------------------------------- */
   8
   9 #ifndef CLOSURES_H
  10 #define 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 GranSim header
  31    -------------------------------------------------------------------------- */
  32
  33 typedef struct {
  34   StgWord procs; /* bitmask indicating on which PEs this closure resides */
  35 } StgGranHeader;
  36
  37 /* -----------------------------------------------------------------------------
  38    The full fixed-size closure header
  39
  40    The size of the fixed header is the sum of the optional parts plus a single
  41    word for the entry code pointer.
  42    -------------------------------------------------------------------------- */
  43
  44 typedef struct {
  45         const struct _StgInfoTable* info;
  46 #ifdef PROFILING
  47         StgProfHeader         prof;
  48 #endif
  49 #ifdef GRAN
  50         StgGranHeader         gran;
  51 #endif
  52 } StgHeader;
  53
  54 /* -----------------------------------------------------------------------------
  55    Closure Types
  56
  57    For any given closure type (defined in InfoTables.h), there is a
  58    corresponding structure defined below.  The name of the structure
  59    is obtained by concatenating the closure type with '_closure'
  60    -------------------------------------------------------------------------- */
  61
  62 /* All closures follow the generic format */
  63
  64 struct StgClosure_ {
  65     StgHeader   header;
  66     struct StgClosure_ *payload[FLEXIBLE_ARRAY];
  67 };
  68
  69 typedef struct {
  70     StgHeader   header;
  71     StgClosure *selectee;
  72 } StgSelector;
  73
  74 typedef struct {
  75     StgHeader   header;
  76     StgHalfWord arity;          /* zero if it is an AP */
  77     StgHalfWord n_args;
  78     StgClosure *fun;            /* really points to a fun */
  79     StgClosure *payload[FLEXIBLE_ARRAY];
  80 } StgPAP;
  81
  82 // AP closures have the same layout, for convenience
  83 typedef StgPAP StgAP;
  84
  85 typedef struct {
  86     StgHeader   header;
  87     StgWord     size;                    // number of words in payload
  88     StgClosure *fun;
  89     StgClosure *payload[FLEXIBLE_ARRAY]; // contains a chunk of *stack*
  90 } StgAP_STACK;
  91
  92 typedef struct {
  93     StgHeader   header;
  94     StgClosure *indirectee;
  95 } StgInd;
  96
  97 typedef struct {
  98     StgHeader     header;
  99     StgClosure   *indirectee;
 100     StgClosure   *static_link;
 101     struct _StgInfoTable *saved_info;
 102 } StgIndStatic;
 103
 104 typedef struct {
 105     StgHeader  header;
 106     StgWord    words;
 107     StgWord    payload[FLEXIBLE_ARRAY];
 108 } StgArrWords;
 109
 110 typedef struct {
 111     StgHeader   header;
 112     StgWord     ptrs;
 113     StgClosure *payload[FLEXIBLE_ARRAY];
 114 } StgMutArrPtrs;
 115
 116 typedef struct {
 117     StgHeader   header;
 118     StgClosure *var;
 119 } StgMutVar;
 120
 121 typedef struct _StgUpdateFrame {
 122     StgHeader  header;
 123     StgClosure *updatee;
 124 } StgUpdateFrame;
 125
 126 typedef struct {
 127     StgHeader  header;
 128     StgInt      exceptions_blocked;
 129     StgClosure *handler;
 130 } StgCatchFrame;
 131
 132 typedef struct {
 133     StgHeader  header;
 134 } StgStopFrame;
 135
 136 typedef struct {
 137     StgHeader   header;
 138     StgClosure *evacuee;
 139 } StgEvacuated;
 140
 141 typedef struct {
 142   StgHeader header;
 143   StgWord data;
 144 } StgIntCharlikeClosure;
 145
 146 /* statically allocated */
 147 typedef struct {
 148   StgHeader  header;
 149 } StgRetry;
 150
 151 typedef struct _StgForeignObj {
 152   StgHeader      header;
 153   StgAddr        data;          /* pointer to data in non-haskell-land */
 154 } StgForeignObj;
 155
 156 typedef struct _StgStableName {
 157   StgHeader      header;
 158   StgWord        sn;
 159 } StgStableName;
 160
 161 typedef struct _StgWeak {       /* Weak v */
 162   StgHeader header;
 163   StgClosure *key;
 164   StgClosure *value;            /* v */
 165   StgClosure *finalizer;
 166   struct _StgWeak *link;
 167 } StgWeak;
 168
 169 typedef struct _StgDeadWeak {   /* Weak v */
 170   StgHeader header;
 171   struct _StgWeak *link;
 172 } StgDeadWeak;
 173
 174 /* Byte code objects.  These are fixed size objects with pointers to
 175  * four arrays, designed so that a BCO can be easily "re-linked" to
 176  * other BCOs, to facilitate GHC's intelligent recompilation.  The
 177  * array of instructions is static and not re-generated when the BCO
 178  * is re-linked, but the other 3 arrays will be regenerated.
 179  *
 180  * A BCO represents either a function or a stack frame.  In each case,
 181  * it needs a bitmap to describe to the garbage collector the
 182  * pointerhood of its arguments/free variables respectively, and in
 183  * the case of a function it also needs an arity.  These are stored
 184  * directly in the BCO, rather than in the instrs array, for two
 185  * reasons:
 186  * (a) speed: we need to get at the bitmap info quickly when
 187  *     the GC is examining APs and PAPs that point to this BCO
 188  * (b) a subtle interaction with the compacting GC.  In compacting
 189  *     GC, the info that describes the size/layout of a closure
 190  *     cannot be in an object more than one level of indirection
 191  *     away from the current object, because of the order in
 192  *     which pointers are updated to point to their new locations.
 193  */
 194
 195 typedef struct {
 196     StgHeader      header;
 197     StgArrWords   *instrs;      // a pointer to an ArrWords
 198     StgArrWords   *literals;    // a pointer to an ArrWords
 199     StgMutArrPtrs *ptrs;        // a pointer to a  MutArrPtrs
 200     StgArrWords   *itbls;       // a pointer to an ArrWords
 201     StgHalfWord   arity;        // arity of this BCO
 202     StgHalfWord   size;         // size of this BCO (in words)
 203     StgWord       bitmap[FLEXIBLE_ARRAY];  // an StgLargeBitmap
 204 } StgBCO;
 205
 206 #define BCO_BITMAP(bco)      ((StgLargeBitmap *)((StgBCO *)(bco))->bitmap)
 207 #define BCO_BITMAP_SIZE(bco) (BCO_BITMAP(bco)->size)
 208 #define BCO_BITMAP_BITS(bco) (BCO_BITMAP(bco)->bitmap)
 209 #define BCO_BITMAP_SIZEW(bco) ((BCO_BITMAP_SIZE(bco) + BITS_IN(StgWord) - 1) \
 210                                 / BITS_IN(StgWord))
 211
 212 /* -----------------------------------------------------------------------------
 213    Dynamic stack frames for generic heap checks.
 214
 215    These generic heap checks are slow, but have the advantage of being
 216    usable in a variety of situations.
 217
 218    The one restriction is that any relevant SRTs must already be pointed
 219    to from the stack.  The return address doesn't need to have an info
 220    table attached: hence it can be any old code pointer.
 221
 222    The liveness mask contains a 1 at bit n, if register Rn contains a
 223    non-pointer.  The contents of all 8 vanilla registers are always saved
 224    on the stack; the liveness mask tells the GC which ones contain
 225    pointers.
 226
 227    Good places to use a generic heap check:
 228
 229         - case alternatives (the return address with an SRT is already
 230           on the stack).
 231
 232         - primitives (no SRT required).
 233
 234    The stack frame layout for a RET_DYN is like this:
 235
 236           some pointers         |-- RET_DYN_PTRS(liveness) words
 237           some nonpointers      |-- RET_DYN_NONPTRS(liveness) words
 238
 239           L1                    \
 240           D1-2                  |-- RET_DYN_NONPTR_REGS_SIZE words
 241           F1-4                  /
 242
 243           R1-8                  |-- RET_DYN_BITMAP_SIZE words
 244
 245           return address        \
 246           liveness mask         |-- StgRetDyn structure
 247           stg_gen_chk_info      /
 248
 249    we assume that the size of a double is always 2 pointers (wasting a
 250    word when it is only one pointer, but avoiding lots of #ifdefs).
 251
 252    See Liveness.h for the macros (RET_DYN_PTRS() etc.).
 253
 254    NOTE: if you change the layout of RET_DYN stack frames, then you
 255    might also need to adjust the value of RESERVED_STACK_WORDS in
 256    Constants.h.
 257    -------------------------------------------------------------------------- */
 258
 259 typedef struct {
 260     const struct _StgInfoTable* info;
 261     StgWord        liveness;
 262     StgWord        ret_addr;
 263     StgClosure *   payload[FLEXIBLE_ARRAY];
 264 } StgRetDyn;
 265
 266 /* A function return stack frame: used when saving the state for a
 267  * garbage collection at a function entry point.  The function
 268  * arguments are on the stack, and we also save the function (its
 269  * info table describes the pointerhood of the arguments).
 270  *
 271  * The stack frame size is also cached in the frame for convenience.
 272  */
 273 typedef struct {
 274     const struct _StgInfoTable* info;
 275     StgWord        size;
 276     StgClosure *   fun;
 277     StgClosure *   payload[FLEXIBLE_ARRAY];
 278 } StgRetFun;
 279
 280 /* Concurrent communication objects */
 281
 282 typedef struct {
 283   StgHeader       header;
 284   struct StgTSO_ *head;
 285   struct StgTSO_ *tail;
 286   StgClosure*     value;
 287 } StgMVar;
 288
 289 /* STM data structures
 290  *
 291  *  StgTVar defines the only type that can be updated through the STM
 292  *  interface.
 293  *
 294  *  Note that various optimisations may be possible in order to use less
 295  *  space for these data structures at the cost of more complexity in the
 296  *  implementation:
 297  *
 298  *   - In StgTVar, current_value and first_wait_queue_entry could be held in
 299  *     the same field: if any thread is waiting then its expected_value for
 300  *     the tvar is the current value.
 301  *
 302  *   - In StgTRecHeader, it might be worthwhile having separate chunks
 303  *     of read-only and read-write locations.  This would save a
 304  *     new_value field in the read-only locations.
 305  */
 306
 307 typedef struct StgTVarWaitQueue_ {
 308   StgHeader                  header;
 309   struct StgTSO_            *waiting_tso;
 310   struct StgTVarWaitQueue_  *next_queue_entry;
 311   struct StgTVarWaitQueue_  *prev_queue_entry;
 312 } StgTVarWaitQueue;
 313
 314 typedef struct {
 315   StgHeader                  header;
 316   StgClosure                *current_value;
 317   StgTVarWaitQueue          *first_wait_queue_entry;
 318 } StgTVar;
 319
 320 // new_value == expected_value for read-only accesses
 321 // new_value is a StgTVarWaitQueue entry when trec in state TREC_WAITING
 322 typedef struct {
 323   StgTVar                   *tvar;
 324   StgClosure                *expected_value;
 325   StgClosure                *new_value;
 326 } TRecEntry;
 327
 328 #define TREC_CHUNK_NUM_ENTRIES 256
 329
 330 typedef struct StgTRecChunk_ {
 331   StgHeader                  header;
 332   struct StgTRecChunk_      *prev_chunk;
 333   StgWord                    next_entry_idx;
 334   TRecEntry                  entries[TREC_CHUNK_NUM_ENTRIES];
 335 } StgTRecChunk;
 336
 337 typedef enum {
 338   TREC_ACTIVE,        // Transaction in progress, outcome undecided
 339   TREC_CANNOT_COMMIT, // Transaction in progress, inconsistent writes performed
 340   TREC_MUST_ABORT,    // Transaction in progress, inconsistent / out of date reads
 341   TREC_COMMITTED,     // Transaction has committed, now updating tvars
 342   TREC_ABORTED,       // Transaction has aborted, now reverting tvars
 343   TREC_WAITING,       // Transaction currently waiting
 344 } TRecState;
 345
 346 typedef struct StgTRecHeader_ {
 347   StgHeader                  header;
 348   TRecState                  state;
 349   struct StgTRecHeader_     *enclosing_trec;
 350   StgTRecChunk              *current_chunk;
 351 } StgTRecHeader;
 352
 353 typedef struct {
 354     StgHeader   header;
 355     StgBool     waiting;
 356     StgClosure *code;
 357 } StgAtomicallyFrame;
 358
 359 typedef struct {
 360     StgHeader   header;
 361     StgClosure *handler;
 362 } StgCatchSTMFrame;
 363
 364 typedef struct {
 365     StgHeader      header;
 366     StgBool        running_alt_code;
 367     StgClosure    *first_code;
 368     StgClosure    *alt_code;
 369     StgTRecHeader *first_code_trec;
 370 } StgCatchRetryFrame;
 371
 372 #if defined(PAR) || defined(GRAN)
 373 /*
 374   StgBlockingQueueElement is a ``collective type'' representing the types
 375   of closures that can be found on a blocking queue: StgTSO, StgRBHSave,
 376   StgBlockedFetch.  (StgRBHSave can only appear at the end of a blocking
 377   queue).  Logically, this is a union type, but defining another struct
 378   with a common layout is easier to handle in the code.
 379   Note that in the standard setup only StgTSOs can be on a blocking queue.
 380   This is one of the main reasons for slightly different code in files
 381   such as Schedule.c.
 382 */
 383 typedef struct StgBlockingQueueElement_ {
 384   StgHeader                         header;
 385   struct StgBlockingQueueElement_  *link;      /* next elem in BQ */
 386   struct StgClosure_               *payload[FLEXIBLE_ARRAY];/* contents of the closure */
 387 } StgBlockingQueueElement;
 388
 389 /* only difference to std code is type of the elem in the BQ */
 390 typedef struct StgBlockingQueue_ {
 391   StgHeader                 header;
 392   struct StgBlockingQueueElement_ *blocking_queue; /* start of the BQ */
 393 } StgBlockingQueue;
 394
 395 /* this closure is hanging at the end of a blocking queue in (see RBH.c) */
 396 typedef struct StgRBHSave_ {
 397   StgHeader    header;
 398   StgClosure  *payload[FLEXIBLE_ARRAY];     /* 2 words ripped out of the guts of the */
 399 } StgRBHSave;                  /*  closure holding the blocking queue */
 400
 401 typedef struct StgRBH_ {
 402   StgHeader                         header;
 403   struct StgBlockingQueueElement_  *blocking_queue; /* start of the BQ */
 404 } StgRBH;
 405
 406 #else
 407
 408 typedef struct StgBlockingQueue_ {
 409   StgHeader          header;
 410   struct StgTSO_    *blocking_queue;
 411 } StgBlockingQueue;
 412
 413 #endif
 414
 415 #if defined(PAR)
 416 /* global indirections aka FETCH_ME closures */
 417 typedef struct StgFetchMe_ {
 418   StgHeader              header;
 419   globalAddr            *ga;        /* ptr to unique id for a closure */
 420 } StgFetchMe;
 421
 422 /* same contents as an ordinary StgBlockingQueue */
 423 typedef struct StgFetchMeBlockingQueue_ {
 424   StgHeader                          header;
 425   struct StgBlockingQueueElement_   *blocking_queue; /* start of the BQ */
 426 } StgFetchMeBlockingQueue;
 427
 428 /* This is an entry in a blocking queue. It indicates a fetch request from a
 429    TSO on another PE demanding the value of this closur. Note that a
 430    StgBlockedFetch can only occur in a BQ. Once the node is evaluated and
 431    updated with the result, the result will be sent back (the PE is encoded
 432    in the globalAddr) and the StgBlockedFetch closure will be nuked.
 433 */
 434 typedef struct StgBlockedFetch_ {
 435   StgHeader                         header;
 436   struct StgBlockingQueueElement_  *link;     /* next elem in the BQ */
 437   StgClosure                       *node;     /* node to fetch */
 438   globalAddr                        ga;       /* where to send the result to */
 439 } StgBlockedFetch;                            /* NB: not just a ptr to a GA */
 440 #endif
 441
 442 #endif /* CLOSURES_H */