rts/Schedule.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team 1998-2005
   4  *
   5  * Prototypes for functions in Schedule.c
   6  * (RTS internal scheduler interface)
   7  *
   8  * -------------------------------------------------------------------------*/
   9
  10 #ifndef SCHEDULE_H
  11 #define SCHEDULE_H
  12
  13 #include "OSThreads.h"
  14 #include "Capability.h"
  15 #include "EventLog.h"
  16
  17 /* initScheduler(), exitScheduler()
  18  * Called from STG :  no
  19  * Locks assumed   :  none
  20  */
  21 void initScheduler (void);
  22 void exitScheduler (rtsBool wait_foreign);
  23 void freeScheduler (void);
  24
  25 // Place a new thread on the run queue of the current Capability
  26 void scheduleThread (Capability *cap, StgTSO *tso);
  27
  28 // Place a new thread on the run queue of a specified Capability
  29 // (cap is the currently owned Capability, cpu is the number of
  30 // the desired Capability).
  31 void scheduleThreadOn(Capability *cap, StgWord cpu, StgTSO *tso);
  32
  33 /* awakenBlockedQueue()
  34  *
  35  * Takes a pointer to the beginning of a blocked TSO queue, and
  36  * wakes up the entire queue.
  37  * Called from STG :  yes
  38  * Locks assumed   :  none
  39  */
  40 void awakenBlockedQueue (Capability *cap, StgTSO *tso);
  41
  42 /* wakeUpRts()
  43  *
  44  * Causes an OS thread to wake up and run the scheduler, if necessary.
  45  */
  46 void wakeUpRts(void);
  47
  48 /* unblockOne()
  49  *
  50  * Put the specified thread on the run queue of the given Capability.
  51  * Called from STG :  yes
  52  * Locks assumed   :  we own the Capability.
  53  */
  54 StgTSO * unblockOne (Capability *cap, StgTSO *tso);
  55
  56 /* raiseExceptionHelper */
  57 StgWord raiseExceptionHelper (StgRegTable *reg, StgTSO *tso, StgClosure *exception);
  58
  59 /* findRetryFrameHelper */
  60 StgWord findRetryFrameHelper (StgTSO *tso);
  61
  62 /* workerStart()
  63  *
  64  * Entry point for a new worker task.
  65  * Called from STG :  NO
  66  * Locks assumed   :  none
  67  */
  68 #if defined(THREADED_RTS)
  69 void OSThreadProcAttr workerStart(Task *task);
  70 #endif
  71
  72 char   *info_type(StgClosure *closure);    // dummy
  73 char   *info_type_by_ip(StgInfoTable *ip); // dummy
  74 void    awaken_blocked_queue(StgTSO *q);
  75 void    initThread(StgTSO *tso, nat stack_size);
  76
  77 /* The state of the scheduler.  This is used to control the sequence
  78  * of events during shutdown, and when the runtime is interrupted
  79  * using ^C.
  80  */
  81 #define SCHED_RUNNING       0  /* running as normal */
  82 #define SCHED_INTERRUPTING  1  /* ^C detected, before threads are deleted */
  83 #define SCHED_SHUTTING_DOWN 2  /* final shutdown */
  84
  85 extern volatile StgWord RTS_VAR(sched_state);
  86
  87 /*
  88  * flag that tracks whether we have done any execution in this time slice.
  89  */
  90 #define ACTIVITY_YES      0 /* there has been activity in the current slice */
  91 #define ACTIVITY_MAYBE_NO 1 /* no activity in the current slice */
  92 #define ACTIVITY_INACTIVE 2 /* a complete slice has passed with no activity */
  93 #define ACTIVITY_DONE_GC  3 /* like 2, but we've done a GC too */
  94
  95 /* Recent activity flag.
  96  * Locks required  : Transition from MAYBE_NO to INACTIVE
  97  * happens in the timer signal, so it is atomic.  Trnasition from
  98  * INACTIVE to DONE_GC happens under sched_mutex.  No lock required
  99  * to set it to ACTIVITY_YES.
 100  */
 101 extern volatile StgWord recent_activity;
 102
 103 /* Thread queues.
 104  * Locks required  : sched_mutex
 105  *
 106  * In GranSim we have one run/blocked_queue per PE.
 107  */
 108 extern  StgTSO *RTS_VAR(blackhole_queue);
 109 #if !defined(THREADED_RTS)
 110 extern  StgTSO *RTS_VAR(blocked_queue_hd), *RTS_VAR(blocked_queue_tl);
 111 extern  StgTSO *RTS_VAR(sleeping_queue);
 112 #endif
 113
 114 /* Set to rtsTrue if there are threads on the blackhole_queue, and
 115  * it is possible that one or more of them may be available to run.
 116  * This flag is set to rtsFalse after we've checked the queue, and
 117  * set to rtsTrue just before we run some Haskell code.  It is used
 118  * to decide whether we should yield the Capability or not.
 119  * Locks required  : none (see scheduleCheckBlackHoles()).
 120  */
 121 extern rtsBool blackholes_need_checking;
 122
 123 extern rtsBool heap_overflow;
 124
 125 #if defined(THREADED_RTS)
 126 extern Mutex RTS_VAR(sched_mutex);
 127 #endif
 128
 129 SchedulerStatus rts_mainLazyIO(HaskellObj p, /*out*/HaskellObj *ret);
 130
 131 /* Called by shutdown_handler(). */
 132 void interruptStgRts (void);
 133
 134 nat  run_queue_len (void);
 135
 136 void resurrectThreads (StgTSO *);
 137 void performPendingThrowTos (StgTSO *);
 138
 139 void printAllThreads(void);
 140
 141 /* debugging only
 142  */
 143 #ifdef DEBUG
 144 void print_bq (StgClosure *node);
 145 #endif
 146
 147 /* -----------------------------------------------------------------------------
 148  * Some convenient macros/inline functions...
 149  */
 150
 151 #if !IN_STG_CODE
 152
 153 /* END_TSO_QUEUE and friends now defined in includes/StgMiscClosures.h */
 154
 155 /* Add a thread to the end of the run queue.
 156  * NOTE: tso->link should be END_TSO_QUEUE before calling this macro.
 157  * ASSUMES: cap->running_task is the current task.
 158  */
 159 INLINE_HEADER void
 160 appendToRunQueue (Capability *cap, StgTSO *tso)
 161 {
 162     ASSERT(tso->_link == END_TSO_QUEUE);
 163     if (cap->run_queue_hd == END_TSO_QUEUE) {
 164         cap->run_queue_hd = tso;
 165     } else {
 166         setTSOLink(cap, cap->run_queue_tl, tso);
 167     }
 168     cap->run_queue_tl = tso;
 169     postEvent (cap, EVENT_THREAD_RUNNABLE, tso->id, 0);
 170 }
 171
 172 /* Push a thread on the beginning of the run queue.
 173  * ASSUMES: cap->running_task is the current task.
 174  */
 175 INLINE_HEADER void
 176 pushOnRunQueue (Capability *cap, StgTSO *tso)
 177 {
 178     setTSOLink(cap, tso, cap->run_queue_hd);
 179     cap->run_queue_hd = tso;
 180     if (cap->run_queue_tl == END_TSO_QUEUE) {
 181         cap->run_queue_tl = tso;
 182     }
 183 }
 184
 185 /* Pop the first thread off the runnable queue.
 186  */
 187 INLINE_HEADER StgTSO *
 188 popRunQueue (Capability *cap)
 189 {
 190     StgTSO *t = cap->run_queue_hd;
 191     ASSERT(t != END_TSO_QUEUE);
 192     cap->run_queue_hd = t->_link;
 193     t->_link = END_TSO_QUEUE; // no write barrier req'd
 194     if (cap->run_queue_hd == END_TSO_QUEUE) {
 195         cap->run_queue_tl = END_TSO_QUEUE;
 196     }
 197     return t;
 198 }
 199
 200 /* Add a thread to the end of the blocked queue.
 201  */
 202 #if !defined(THREADED_RTS)
 203 INLINE_HEADER void
 204 appendToBlockedQueue(StgTSO *tso)
 205 {
 206     ASSERT(tso->_link == END_TSO_QUEUE);
 207     if (blocked_queue_hd == END_TSO_QUEUE) {
 208         blocked_queue_hd = tso;
 209     } else {
 210         setTSOLink(&MainCapability, blocked_queue_tl, tso);
 211     }
 212     blocked_queue_tl = tso;
 213 }
 214 #endif
 215
 216 #if defined(THREADED_RTS)
 217 // Assumes: my_cap is owned by the current Task.  We hold
 218 // other_cap->lock, but we do not necessarily own other_cap; another
 219 // Task may be running on it.
 220 INLINE_HEADER void
 221 appendToWakeupQueue (Capability *my_cap, Capability *other_cap, StgTSO *tso)
 222 {
 223     ASSERT(tso->_link == END_TSO_QUEUE);
 224     if (other_cap->wakeup_queue_hd == END_TSO_QUEUE) {
 225         other_cap->wakeup_queue_hd = tso;
 226     } else {
 227         // my_cap is passed to setTSOLink() because it may need to
 228         // write to the mutable list.
 229         setTSOLink(my_cap, other_cap->wakeup_queue_tl, tso);
 230     }
 231     other_cap->wakeup_queue_tl = tso;
 232 }
 233 #endif
 234
 235 /* Check whether various thread queues are empty
 236  */
 237 INLINE_HEADER rtsBool
 238 emptyQueue (StgTSO *q)
 239 {
 240     return (q == END_TSO_QUEUE);
 241 }
 242
 243 INLINE_HEADER rtsBool
 244 emptyRunQueue(Capability *cap)
 245 {
 246     return emptyQueue(cap->run_queue_hd);
 247 }
 248
 249 #if defined(THREADED_RTS)
 250 INLINE_HEADER rtsBool
 251 emptyWakeupQueue(Capability *cap)
 252 {
 253     return emptyQueue(cap->wakeup_queue_hd);
 254 }
 255 #endif
 256
 257 #if !defined(THREADED_RTS)
 258 #define EMPTY_BLOCKED_QUEUE()  (emptyQueue(blocked_queue_hd))
 259 #define EMPTY_SLEEPING_QUEUE() (emptyQueue(sleeping_queue))
 260 #endif
 261
 262 INLINE_HEADER rtsBool
 263 emptyThreadQueues(Capability *cap)
 264 {
 265     return emptyRunQueue(cap)
 266 #if !defined(THREADED_RTS)
 267         && EMPTY_BLOCKED_QUEUE() && EMPTY_SLEEPING_QUEUE()
 268 #endif
 269     ;
 270 }
 271
 272 #endif /* !IN_STG_CODE */
 273
 274 #endif /* SCHEDULE_H */
 275