ghc/includes/TSO.h

   1 /* -----------------------------------------------------------------------------
   2  * $Id: TSO.h,v 1.39 2004/11/18 09:56:22 tharris Exp $
   3  *
   4  * (c) The GHC Team, 1998-1999
   5  *
   6  * The definitions for Thread State Objects.
   7  *
   8  * ---------------------------------------------------------------------------*/
   9
  10 #ifndef TSO_H
  11 #define TSO_H
  12
  13 #if DEBUG
  14 #define TSO_MAGIC 4321
  15 #endif
  16
  17 typedef struct {
  18   StgInt   pri;
  19   StgInt   magic;
  20   StgInt   sparkname;
  21   rtsTime  startedat;
  22   rtsBool  exported;
  23   StgInt   basicblocks;
  24   StgInt   allocs;
  25   rtsTime  exectime;
  26   rtsTime  fetchtime;
  27   rtsTime  fetchcount;
  28   rtsTime  blocktime;
  29   StgInt   blockcount;
  30   rtsTime  blockedat;
  31   StgInt   globalsparks;
  32   StgInt   localsparks;
  33   rtsTime  clock;
  34 } StgTSOStatBuf;
  35
  36 /*
  37  * GRAN: We distinguish between the various classes of threads in
  38  * the system.
  39  */
  40 typedef enum {
  41   AdvisoryPriority,
  42   MandatoryPriority,
  43   RevalPriority
  44 } StgThreadPriority;
  45
  46 /*
  47  * PROFILING info in a TSO
  48  */
  49 typedef struct {
  50   CostCentreStack *CCCS;        /* thread's current CCS */
  51 } StgTSOProfInfo;
  52
  53 /*
  54  * PAR info in a TSO
  55  */
  56 typedef StgTSOStatBuf StgTSOParInfo;
  57
  58 /*
  59  * DIST info in a TSO
  60  */
  61 typedef struct {
  62   StgThreadPriority  priority;
  63   StgInt             revalTid;   /* ToDo: merge both into 1 word */
  64   StgInt             revalSlot;
  65 } StgTSODistInfo;
  66
  67 /*
  68  * GRAN info in a TSO
  69  */
  70 typedef StgTSOStatBuf StgTSOGranInfo;
  71
  72 /*
  73  * There is no TICKY info in a TSO at this time.
  74  */
  75
  76 /*
  77  * Thread IDs are 32 bits.
  78  */
  79 typedef StgWord32 StgThreadID;
  80
  81 /*
  82  * Type returned after running a thread.  Values of this type
  83  * include HeapOverflow, StackOverflow etc.  See Constants.h for the
  84  * full list.
  85  */
  86 typedef unsigned int StgThreadReturnCode;
  87
  88 #if defined(mingw32_TARGET_OS)
  89 /* results from an async I/O request + it's ID. */
  90 typedef struct {
  91   unsigned int reqID;
  92   int          len;
  93   int          errCode;
  94 } StgAsyncIOResult;
  95 #endif
  96
  97 typedef union {
  98   StgClosure *closure;
  99   struct StgTSO_ *tso;
 100   StgInt fd;    // StgInt instead of int, so that it's the same size as the ptrs
 101 #if defined(mingw32_TARGET_OS)
 102   StgAsyncIOResult* async_result;
 103 #endif
 104   StgWord target;
 105 } StgTSOBlockInfo;
 106
 107 /*
 108  * TSOs live on the heap, and therefore look just like heap objects.
 109  * Large TSOs will live in their own "block group" allocated by the
 110  * storage manager, and won't be copied during garbage collection.
 111  */
 112
 113 /*
 114  * Threads may be blocked for several reasons.  A blocked thread will
 115  * have the reason in the why_blocked field of the TSO, and some
 116  * further info (such as the closure the thread is blocked on, or the
 117  * file descriptor if the thread is waiting on I/O) in the block_info
 118  * field.
 119  */
 120
 121 /*
 122  * ToDo: make this structure sensible on a non-32-bit arch.
 123  */
 124
 125 typedef struct StgTSO_ {
 126   StgHeader          header;
 127
 128   struct StgTSO_*    link;           // Links threads onto blocking queues */
 129   StgMutClosure *    mut_link;       // TSO's are mutable of course! */
 130   struct StgTSO_*    global_link;    // Links all threads together */
 131
 132   StgWord16           what_next;  // Values defined in Constants.h
 133   StgWord16           why_blocked;  // Values defined in Constants.h
 134   StgTSOBlockInfo    block_info;
 135   struct StgTSO_*    blocked_exceptions;
 136   StgThreadID        id;
 137   int                saved_errno;
 138   struct StgMainThread_* main;
 139   struct StgTRecHeader_ *trec;       // STM transaction record
 140
 141 #ifdef TICKY_TICKY
 142   // TICKY-specific stuff would go here.
 143 #endif
 144 #ifdef PROFILING
 145    StgTSOProfInfo prof;
 146 #endif
 147 #ifdef PAR
 148    StgTSOParInfo par;
 149 #endif
 150 #ifdef GRAN
 151    StgTSOGranInfo gran;
 152 #endif
 153 #ifdef DIST
 154    StgTSODistInfo dist;
 155 #endif
 156
 157   /* The thread stack... */
 158   StgWord            stack_size;     /* stack size in *words* */
 159   StgWord            max_stack_size; /* maximum stack size in *words* */
 160   StgPtr             sp;
 161
 162   StgWord            stack[FLEXIBLE_ARRAY];
 163 } StgTSO;
 164
 165 /* -----------------------------------------------------------------------------
 166    Invariants:
 167
 168    An active thread has the following properties:
 169
 170       tso->stack < tso->sp < tso->stack+tso->stack_size
 171       tso->stack_size <= tso->max_stack_size
 172
 173       RESERVED_STACK_WORDS is large enough for any heap-check or
 174       stack-check failure.
 175
 176       The size of the TSO struct plus the stack is either
 177         (a) smaller than a block, or
 178         (b) a multiple of BLOCK_SIZE
 179
 180         tso->why_blocked       tso->block_info      location
 181         ----------------------------------------------------------------------
 182         NotBlocked             NULL                 runnable_queue, or running
 183
 184         BlockedOnBlackHole     the BLACKHOLE_BQ     the BLACKHOLE_BQ's queue
 185
 186         BlockedOnMVar          the MVAR             the MVAR's queue
 187
 188         BlockedOnSTM           END_TSO_QUEUE        STM wait queue(s)
 189
 190         BlockedOnException     the TSO              TSO->blocked_exception
 191
 192         BlockedOnRead          NULL                 blocked_queue
 193         BlockedOnWrite         NULL                 blocked_queue
 194         BlockedOnDelay         NULL                 blocked_queue
 195         BlockedOnGA            closure TSO blocks on   BQ of that closure
 196         BlockedOnGA_NoSend     closure TSO blocks on   BQ of that closure
 197
 198       tso->link == END_TSO_QUEUE, if the thread is currently running.
 199
 200    A zombie thread has the following properties:
 201
 202       tso->what_next == ThreadComplete or ThreadKilled
 203       tso->link     ==  (could be on some queue somewhere)
 204       tso->su       ==  tso->stack + tso->stack_size
 205       tso->sp       ==  tso->stack + tso->stack_size - 1 (i.e. top stack word)
 206       tso->sp[0]    ==  return value of thread, if what_next == ThreadComplete,
 207                         exception             , if what_next == ThreadKilled
 208
 209       (tso->sp is left pointing at the top word on the stack so that
 210       the return value or exception will be retained by a GC).
 211
 212    tso->blocked_exceptions is either:
 213
 214       NULL             if async exceptions are unblocked.
 215
 216       END_TSO_QUEUE    if async exceptions are blocked, but no threads
 217                        are currently waiting to deliver.
 218
 219       (StgTSO *)tso    if threads are currently awaiting delivery of
 220                        exceptions to this thread.
 221
 222    The 2 cases BlockedOnGA and BlockedOnGA_NoSend are needed in a GUM
 223    setup only. They mark a TSO that has entered a FETCH_ME or
 224    FETCH_ME_BQ closure, respectively; only the first TSO hitting the
 225    closure will send a Fetch message.
 226    Currently we have no separate code for blocking on an RBH; we use the
 227    BlockedOnBlackHole case for that.   -- HWL
 228
 229  ---------------------------------------------------------------------------- */
 230
 231 /* Workaround for a bug/quirk in gcc on certain architectures.
 232  * symptom is that (&tso->stack - &tso->header) /=  sizeof(StgTSO)
 233  * in other words, gcc pads the structure at the end.
 234  */
 235
 236 extern StgTSO dummy_tso;
 237
 238 #define TSO_STRUCT_SIZE \
 239    ((char *)&dummy_tso.stack - (char *)&dummy_tso.header)
 240
 241 #define TSO_STRUCT_SIZEW (TSO_STRUCT_SIZE / sizeof(W_))
 242
 243
 244 /* this is the NIL ptr for a TSO queue (e.g. runnable queue) */
 245 #define END_TSO_QUEUE  ((StgTSO *)(void*)&stg_END_TSO_QUEUE_closure)
 246
 247 #if defined(PAR) || defined(GRAN)
 248 /* this is the NIL ptr for a blocking queue */
 249 # define END_BQ_QUEUE  ((StgBlockingQueueElement *)(void*)&stg_END_TSO_QUEUE_closure)
 250 /* this is the NIL ptr for a blocked fetch queue (as in PendingFetches in GUM) */
 251 # define END_BF_QUEUE  ((StgBlockedFetch *)(void*)&stg_END_TSO_QUEUE_closure)
 252 #endif
 253 /* ToDo?: different name for end of sleeping queue ? -- HWL */
 254
 255 #endif /* TSO_H */