ghc/includes/TSO.h

   1 /* -----------------------------------------------------------------------------
   2  * $Id: TSO.h,v 1.37 2004/11/08 12:26:57 simonmar 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   int fd;
 101 #if defined(mingw32_TARGET_OS)
 102   StgAsyncIOResult* async_result;
 103 #endif
 104   unsigned int 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
 140 #ifdef TICKY_TICKY
 141   // TICKY-specific stuff would go here.
 142 #endif
 143 #ifdef PROFILING
 144    StgTSOProfInfo prof;
 145 #endif
 146 #ifdef PAR
 147    StgTSOParInfo par;
 148 #endif
 149 #ifdef GRAN
 150    StgTSOGranInfo gran;
 151 #endif
 152 #ifdef DIST
 153    StgTSODistInfo dist;
 154 #endif
 155
 156   /* The thread stack... */
 157   StgWord            stack_size;     /* stack size in *words* */
 158   StgWord            max_stack_size; /* maximum stack size in *words* */
 159   StgPtr             sp;
 160
 161   StgWord            stack[FLEXIBLE_ARRAY];
 162 } StgTSO;
 163
 164 /* -----------------------------------------------------------------------------
 165    Invariants:
 166
 167    An active thread has the following properties:
 168
 169       tso->stack < tso->sp < tso->stack+tso->stack_size
 170       tso->stack_size <= tso->max_stack_size
 171
 172       RESERVED_STACK_WORDS is large enough for any heap-check or
 173       stack-check failure.
 174
 175       The size of the TSO struct plus the stack is either
 176         (a) smaller than a block, or
 177         (b) a multiple of BLOCK_SIZE
 178
 179         tso->why_blocked       tso->block_info      location
 180         ----------------------------------------------------------------------
 181         NotBlocked             NULL                 runnable_queue, or running
 182
 183         BlockedOnBlackHole     the BLACKHOLE_BQ     the BLACKHOLE_BQ's queue
 184
 185         BlockedOnMVar          the MVAR             the MVAR's queue
 186
 187         BlockedOnException     the TSO              TSO->blocked_exception
 188
 189         BlockedOnRead          NULL                 blocked_queue
 190         BlockedOnWrite         NULL                 blocked_queue
 191         BlockedOnDelay         NULL                 blocked_queue
 192         BlockedOnGA            closure TSO blocks on   BQ of that closure
 193         BlockedOnGA_NoSend     closure TSO blocks on   BQ of that closure
 194
 195       tso->link == END_TSO_QUEUE, if the thread is currently running.
 196
 197    A zombie thread has the following properties:
 198
 199       tso->what_next == ThreadComplete or ThreadKilled
 200       tso->link     ==  (could be on some queue somewhere)
 201       tso->su       ==  tso->stack + tso->stack_size
 202       tso->sp       ==  tso->stack + tso->stack_size - 1 (i.e. top stack word)
 203       tso->sp[0]    ==  return value of thread, if what_next == ThreadComplete,
 204                         exception             , if what_next == ThreadKilled
 205
 206       (tso->sp is left pointing at the top word on the stack so that
 207       the return value or exception will be retained by a GC).
 208
 209    tso->blocked_exceptions is either:
 210
 211       NULL             if async exceptions are unblocked.
 212
 213       END_TSO_QUEUE    if async exceptions are blocked, but no threads
 214                        are currently waiting to deliver.
 215
 216       (StgTSO *)tso    if threads are currently awaiting delivery of
 217                        exceptions to this thread.
 218
 219    The 2 cases BlockedOnGA and BlockedOnGA_NoSend are needed in a GUM
 220    setup only. They mark a TSO that has entered a FETCH_ME or
 221    FETCH_ME_BQ closure, respectively; only the first TSO hitting the
 222    closure will send a Fetch message.
 223    Currently we have no separate code for blocking on an RBH; we use the
 224    BlockedOnBlackHole case for that.   -- HWL
 225
 226  ---------------------------------------------------------------------------- */
 227
 228 /* Workaround for a bug/quirk in gcc on certain architectures.
 229  * symptom is that (&tso->stack - &tso->header) /=  sizeof(StgTSO)
 230  * in other words, gcc pads the structure at the end.
 231  */
 232
 233 extern StgTSO dummy_tso;
 234
 235 #define TSO_STRUCT_SIZE \
 236    ((char *)&dummy_tso.stack - (char *)&dummy_tso.header)
 237
 238 #define TSO_STRUCT_SIZEW (TSO_STRUCT_SIZE / sizeof(W_))
 239
 240
 241 /* this is the NIL ptr for a TSO queue (e.g. runnable queue) */
 242 #define END_TSO_QUEUE  ((StgTSO *)(void*)&stg_END_TSO_QUEUE_closure)
 243
 244 #if defined(PAR) || defined(GRAN)
 245 /* this is the NIL ptr for a blocking queue */
 246 # define END_BQ_QUEUE  ((StgBlockingQueueElement *)(void*)&stg_END_TSO_QUEUE_closure)
 247 /* this is the NIL ptr for a blocked fetch queue (as in PendingFetches in GUM) */
 248 # define END_BF_QUEUE  ((StgBlockedFetch *)(void*)&stg_END_TSO_QUEUE_closure)
 249 #endif
 250 /* ToDo?: different name for end of sleeping queue ? -- HWL */
 251
 252 #endif /* TSO_H */