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 typedef union {
  71   StgClosure *closure;
  72   struct StgTSO_ *tso;
  73   StgInt fd;    /* StgInt instead of int, so that it's the same size as the ptrs */
  74 #if defined(mingw32_HOST_OS)
  75   StgAsyncIOResult *async_result;
  76 #endif
  77   StgWord target;
  78 } StgTSOBlockInfo;
  79
  80
  81 /*
  82  * TSOs live on the heap, and therefore look just like heap objects.
  83  * Large TSOs will live in their own "block group" allocated by the
  84  * storage manager, and won't be copied during garbage collection.
  85  */
  86
  87 /*
  88  * Threads may be blocked for several reasons.  A blocked thread will
  89  * have the reason in the why_blocked field of the TSO, and some
  90  * further info (such as the closure the thread is blocked on, or the
  91  * file descriptor if the thread is waiting on I/O) in the block_info
  92  * field.
  93  */
  94
  95 typedef struct StgTSO_ {
  96     StgHeader               header;
  97
  98     /* The link field, for linking threads together in lists (e.g. the
  99        run queue on a Capability.
 100     */
 101     struct StgTSO_*         _link;
 102     /*
 103        NOTE!!!  do not modify _link directly, it is subject to
 104        a write barrier for generational GC.  Instead use the
 105        setTSOLink() function.  Exceptions to this rule are:
 106
 107        * setting the link field to END_TSO_QUEUE
 108        * putting a TSO on the blackhole_queue
 109        * setting the link field of the currently running TSO, as it
 110          will already be dirty.
 111     */
 112
 113     struct StgTSO_*         global_link;    /* Links all threads together */
 114
 115     StgWord16               what_next;      /* Values defined in Constants.h */
 116     StgWord16               why_blocked;    /* Values defined in Constants.h */
 117     StgWord32               flags;
 118     StgTSOBlockInfo         block_info;
 119     StgThreadID             id;
 120     int                     saved_errno;
 121     struct Task_*           bound;
 122     struct Capability_*     cap;
 123     struct StgTRecHeader_ * trec;       /* STM transaction record */
 124
 125     /*
 126        A list of threads blocked on this TSO waiting to throw
 127        exceptions.  In order to access this field, the TSO must be
 128        locked using lockClosure/unlockClosure (see SMP.h).
 129     */
 130     struct StgTSO_ *        blocked_exceptions;
 131
 132 #ifdef TICKY_TICKY
 133     /* TICKY-specific stuff would go here. */
 134 #endif
 135 #ifdef PROFILING
 136     StgTSOProfInfo prof;
 137 #endif
 138 #ifdef mingw32_HOST_OS
 139     StgWord32 saved_winerror;
 140 #endif
 141
 142     /* The thread stack... */
 143     StgWord32          stack_size;     /* stack size in *words* */
 144     StgWord32          max_stack_size; /* maximum stack size in *words* */
 145     StgPtr             sp;
 146
 147     StgWord            stack[FLEXIBLE_ARRAY];
 148 } StgTSO;
 149
 150 /* -----------------------------------------------------------------------------
 151    functions
 152    -------------------------------------------------------------------------- */
 153
 154 extern void dirty_TSO  (Capability *cap, StgTSO *tso);
 155 extern void setTSOLink (Capability *cap, StgTSO *tso, StgTSO *target);
 156
 157 /* -----------------------------------------------------------------------------
 158    Invariants:
 159
 160    An active thread has the following properties:
 161
 162       tso->stack < tso->sp < tso->stack+tso->stack_size
 163       tso->stack_size <= tso->max_stack_size
 164
 165       RESERVED_STACK_WORDS is large enough for any heap-check or
 166       stack-check failure.
 167
 168       The size of the TSO struct plus the stack is either
 169         (a) smaller than a block, or
 170         (b) a multiple of BLOCK_SIZE
 171
 172         tso->why_blocked       tso->block_info      location
 173         ----------------------------------------------------------------------
 174         NotBlocked             NULL                 runnable_queue, or running
 175
 176         BlockedOnBlackHole     the BLACKHOLE_BQ     the BLACKHOLE_BQ's queue
 177
 178         BlockedOnMVar          the MVAR             the MVAR's queue
 179
 180         BlockedOnSTM           END_TSO_QUEUE        STM wait queue(s)
 181
 182         BlockedOnException     the TSO              TSO->blocked_exception
 183
 184         BlockedOnRead          NULL                 blocked_queue
 185         BlockedOnWrite         NULL                 blocked_queue
 186         BlockedOnDelay         NULL                 blocked_queue
 187         BlockedOnGA            closure TSO blocks on   BQ of that closure
 188         BlockedOnGA_NoSend     closure TSO blocks on   BQ of that closure
 189
 190       tso->link == END_TSO_QUEUE, if the thread is currently running.
 191
 192    A zombie thread has the following properties:
 193
 194       tso->what_next == ThreadComplete or ThreadKilled
 195       tso->link     ==  (could be on some queue somewhere)
 196       tso->su       ==  tso->stack + tso->stack_size
 197       tso->sp       ==  tso->stack + tso->stack_size - 1 (i.e. top stack word)
 198       tso->sp[0]    ==  return value of thread, if what_next == ThreadComplete,
 199                         exception             , if what_next == ThreadKilled
 200
 201       (tso->sp is left pointing at the top word on the stack so that
 202       the return value or exception will be retained by a GC).
 203
 204    The 2 cases BlockedOnGA and BlockedOnGA_NoSend are needed in a GUM
 205    setup only. They mark a TSO that has entered a FETCH_ME or
 206    FETCH_ME_BQ closure, respectively; only the first TSO hitting the
 207    closure will send a Fetch message.
 208    Currently we have no separate code for blocking on an RBH; we use the
 209    BlockedOnBlackHole case for that.   -- HWL
 210
 211  ---------------------------------------------------------------------------- */
 212
 213 /* Workaround for a bug/quirk in gcc on certain architectures.
 214  * symptom is that (&tso->stack - &tso->header) /=  sizeof(StgTSO)
 215  * in other words, gcc pads the structure at the end.
 216  */
 217
 218 extern StgTSO dummy_tso;
 219
 220 #define TSO_STRUCT_SIZE \
 221    ((char *)&dummy_tso.stack - (char *)&dummy_tso.header)
 222
 223 #define TSO_STRUCT_SIZEW (TSO_STRUCT_SIZE / sizeof(W_))
 224
 225 /* this is the NIL ptr for a TSO queue (e.g. runnable queue) */
 226 #define END_TSO_QUEUE  ((StgTSO *)(void*)&stg_END_TSO_QUEUE_closure)
 227
 228 #endif /* TSO_H */