includes/TSO.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 1998-1999
   4  *
   5  * The definitions for Thread State Objects.
   6  *
   7  * ---------------------------------------------------------------------------*/
   8
   9 #ifndef TSO_H
  10 #define TSO_H
  11
  12 #if DEBUG
  13 #define TSO_MAGIC 4321
  14 #endif
  15
  16 typedef struct {
  17   StgInt   pri;
  18   StgInt   magic;
  19   StgInt   sparkname;
  20   rtsTime  startedat;
  21   rtsBool  exported;
  22   StgInt   basicblocks;
  23   StgInt   allocs;
  24   rtsTime  exectime;
  25   rtsTime  fetchtime;
  26   rtsTime  fetchcount;
  27   rtsTime  blocktime;
  28   StgInt   blockcount;
  29   rtsTime  blockedat;
  30   StgInt   globalsparks;
  31   StgInt   localsparks;
  32   rtsTime  clock;
  33 } StgTSOStatBuf;
  34
  35 /*
  36  * PROFILING info in a TSO
  37  */
  38 typedef struct {
  39   CostCentreStack *CCCS;        /* thread's current CCS */
  40 } StgTSOProfInfo;
  41
  42 /*
  43  * There is no TICKY info in a TSO at this time.
  44  */
  45
  46 /*
  47  * Thread IDs are 32 bits.
  48  */
  49 typedef StgWord32 StgThreadID;
  50
  51 #define tsoDirty(tso)  ((tso)->flags & TSO_DIRTY)
  52 #define tsoLocked(tso) ((tso)->flags & TSO_LOCKED)
  53
  54 /*
  55  * Type returned after running a thread.  Values of this type
  56  * include HeapOverflow, StackOverflow etc.  See Constants.h for the
  57  * full list.
  58  */
  59 typedef unsigned int StgThreadReturnCode;
  60
  61 #if defined(mingw32_HOST_OS)
  62 /* results from an async I/O request + its request ID. */
  63 typedef struct {
  64   unsigned int reqID;
  65   int          len;
  66   int          errCode;
  67 } StgAsyncIOResult;
  68 #endif
  69
  70 /* Reason for thread being blocked. See comment above struct StgTso_. */
  71 typedef union {
  72   StgClosure *closure;
  73   struct StgTSO_ *tso;
  74   StgInt fd;    /* StgInt instead of int, so that it's the same size as the ptrs */
  75 #if defined(mingw32_HOST_OS)
  76   StgAsyncIOResult *async_result;
  77 #endif
  78   StgWord target;
  79 } StgTSOBlockInfo;
  80
  81
  82 /*
  83  * TSOs live on the heap, and therefore look just like heap objects.
  84  * Large TSOs will live in their own "block group" allocated by the
  85  * storage manager, and won't be copied during garbage collection.
  86  */
  87
  88 /*
  89  * Threads may be blocked for several reasons.  A blocked thread will
  90  * have the reason in the why_blocked field of the TSO, and some
  91  * further info (such as the closure the thread is blocked on, or the
  92  * file descriptor if the thread is waiting on I/O) in the block_info
  93  * field.
  94  */
  95
  96 typedef struct StgTSO_ {
  97     StgHeader               header;
  98
  99     /* The link field, for linking threads together in lists (e.g. the
 100        run queue on a Capability.
 101     */
 102     struct StgTSO_*         _link;
 103     /*
 104        NOTE!!!  do not modify _link directly, it is subject to
 105        a write barrier for generational GC.  Instead use the
 106        setTSOLink() function.  Exceptions to this rule are:
 107
 108        * setting the link field to END_TSO_QUEUE
 109        * putting a TSO on the blackhole_queue
 110        * setting the link field of the currently running TSO, as it
 111          will already be dirty.
 112     */
 113
 114     struct StgTSO_*         global_link;    /* Links all threads together */
 115
 116     StgWord16               what_next;      /* Values defined in Constants.h */
 117     StgWord16               why_blocked;    /* Values defined in Constants.h */
 118     StgWord32               flags;
 119     StgTSOBlockInfo         block_info;
 120     StgThreadID             id;
 121     int                     saved_errno;
 122     struct Task_*           bound;
 123     struct Capability_*     cap;
 124     struct StgTRecHeader_ * trec;       /* STM transaction record */
 125
 126     /*
 127        A list of threads blocked on this TSO waiting to throw
 128        exceptions.  In order to access this field, the TSO must be
 129        locked using lockClosure/unlockClosure (see SMP.h).
 130     */
 131     struct StgTSO_ *        blocked_exceptions;
 132
 133 #ifdef TICKY_TICKY
 134     /* TICKY-specific stuff would go here. */
 135 #endif
 136 #ifdef PROFILING
 137     StgTSOProfInfo prof;
 138 #endif
 139 #ifdef mingw32_HOST_OS
 140     StgWord32 saved_winerror;
 141 #endif
 142
 143     /* The thread stack... */
 144     StgWord32          stack_size;     /* stack size in *words* */
 145     StgWord32          max_stack_size; /* maximum stack size in *words* */
 146     StgPtr             sp;
 147
 148     StgWord            stack[FLEXIBLE_ARRAY];
 149 } StgTSO;
 150
 151 /* -----------------------------------------------------------------------------
 152    functions
 153    -------------------------------------------------------------------------- */
 154
 155 extern void dirty_TSO  (Capability *cap, StgTSO *tso);
 156 extern void setTSOLink (Capability *cap, StgTSO *tso, StgTSO *target);
 157
 158 /* -----------------------------------------------------------------------------
 159    Invariants:
 160
 161    An active thread has the following properties:
 162
 163       tso->stack < tso->sp < tso->stack+tso->stack_size
 164       tso->stack_size <= tso->max_stack_size
 165
 166       RESERVED_STACK_WORDS is large enough for any heap-check or
 167       stack-check failure.
 168
 169       The size of the TSO struct plus the stack is either
 170         (a) smaller than a block, or
 171         (b) a multiple of BLOCK_SIZE
 172
 173         tso->why_blocked       tso->block_info      location
 174         ----------------------------------------------------------------------
 175         NotBlocked             NULL                 runnable_queue, or running
 176
 177         BlockedOnBlackHole     the BLACKHOLE_BQ     the BLACKHOLE_BQ's queue
 178
 179         BlockedOnMVar          the MVAR             the MVAR's queue
 180
 181         BlockedOnSTM           END_TSO_QUEUE        STM wait queue(s)
 182
 183         BlockedOnException     the TSO              TSO->blocked_exception
 184
 185         BlockedOnRead          NULL                 blocked_queue
 186         BlockedOnWrite         NULL                 blocked_queue
 187         BlockedOnDelay         NULL                 blocked_queue
 188         BlockedOnGA            closure TSO blocks on   BQ of that closure
 189         BlockedOnGA_NoSend     closure TSO blocks on   BQ of that closure
 190
 191       tso->link == END_TSO_QUEUE, if the thread is currently running.
 192
 193    A zombie thread has the following properties:
 194
 195       tso->what_next == ThreadComplete or ThreadKilled
 196       tso->link     ==  (could be on some queue somewhere)
 197       tso->su       ==  tso->stack + tso->stack_size
 198       tso->sp       ==  tso->stack + tso->stack_size - 1 (i.e. top stack word)
 199       tso->sp[0]    ==  return value of thread, if what_next == ThreadComplete,
 200                         exception             , if what_next == ThreadKilled
 201
 202       (tso->sp is left pointing at the top word on the stack so that
 203       the return value or exception will be retained by a GC).
 204
 205    The 2 cases BlockedOnGA and BlockedOnGA_NoSend are needed in a GUM
 206    setup only. They mark a TSO that has entered a FETCH_ME or
 207    FETCH_ME_BQ closure, respectively; only the first TSO hitting the
 208    closure will send a Fetch message.
 209    Currently we have no separate code for blocking on an RBH; we use the
 210    BlockedOnBlackHole case for that.   -- HWL
 211
 212  ---------------------------------------------------------------------------- */
 213
 214 /* Workaround for a bug/quirk in gcc on certain architectures.
 215  * symptom is that (&tso->stack - &tso->header) /=  sizeof(StgTSO)
 216  * in other words, gcc pads the structure at the end.
 217  */
 218
 219 extern StgTSO dummy_tso;
 220
 221 #define TSO_STRUCT_SIZE \
 222    ((char *)&dummy_tso.stack - (char *)&dummy_tso.header)
 223
 224 #define TSO_STRUCT_SIZEW (TSO_STRUCT_SIZE / sizeof(W_))
 225
 226 /* this is the NIL ptr for a TSO queue (e.g. runnable queue) */
 227 #define END_TSO_QUEUE  ((StgTSO *)(void*)&stg_END_TSO_QUEUE_closure)
 228
 229 #endif /* TSO_H */