rts/Task.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team 2001-2005
   4  *
   5  * Tasks
   6  *
   7  * -------------------------------------------------------------------------*/
   8
   9 #ifndef TASK_H
  10 #define TASK_H
  11
  12 #include "GetTime.h"
  13
  14 /*
  15    Definition of a Task
  16    --------------------
  17
  18    A task is an OSThread that runs Haskell code.  Every OSThread
  19    created by the RTS for the purposes of running Haskell code is a
  20    Task, and OS threads that enter the Haskell RTS for the purposes of
  21    making a call-in are also Tasks.
  22
  23    The relationship between the number of tasks and capabilities, and
  24    the runtime build (-threaded, -smp etc.) is summarised by the
  25    following table:
  26
  27      build        Tasks   Capabilities
  28      ---------------------------------
  29      normal         1          1
  30      -threaded      N          N
  31
  32    The non-threaded build has a single Task and a single global
  33    Capability.
  34
  35    The THREADED_RTS build allows multiple tasks and mulitple Capabilities.
  36    Multiple Tasks may all be running Haskell code simultaneously. A task
  37    relinquishes its Capability when it is asked to evaluate an external
  38    (C) call.
  39
  40    In general, there may be multiple Tasks for an OS thread.  This
  41    happens if one Task makes a foreign call from Haskell, and
  42    subsequently calls back in to create a new bound thread.
  43
  44    A particular Task structure can belong to more than one OS thread
  45    over its lifetime.  This is to avoid creating an unbounded number
  46    of Task structures.  The stats just accumulate.
  47
  48    Ownership of Task
  49    -----------------
  50
  51    The OS thread named in the Task structure has exclusive access to
  52    the structure, as long as it is the running_task of its Capability.
  53    That is, if (task->cap->running_task == task), then task->id owns
  54    the Task.  Otherwise the Task is owned by the owner of the parent
  55    data structure on which it is sleeping; for example, if the task is
  56    sleeping on spare_workers field of a Capability, then the owner of the
  57    Capability has access to the Task.
  58
  59    When a task is migrated from sleeping on one Capability to another,
  60    its task->cap field must be modified.  When the task wakes up, it
  61    will read the new value of task->cap to find out which Capability
  62    it belongs to.  Hence some synchronisation is required on
  63    task->cap, and this is why we have task->lock.
  64
  65    If the Task is not currently owned by task->id, then the thread is
  66    either
  67
  68       (a) waiting on the condition task->cond.  The Task is either
  69          (1) a bound Task, the TSO will be on a queue somewhere
  70          (2) a worker task, on the spare_workers queue of task->cap.
  71
  72      (b) making a foreign call.  The Task will be on the
  73          suspended_ccalling_tasks list.
  74
  75    We re-establish ownership in each case by respectively
  76
  77       (a) the task is currently blocked in yieldCapability().
  78           This call will return when we have ownership of the Task and
  79           a Capability.  The Capability we get might not be the same
  80           as the one we had when we called yieldCapability().
  81
  82       (b) we must call resumeThread(task), which will safely establish
  83           ownership of the Task and a Capability.
  84 */
  85
  86 typedef struct Task_ {
  87 #if defined(THREADED_RTS)
  88     OSThreadId id;              // The OS Thread ID of this task
  89 #endif
  90
  91     // This points to the Capability that the Task "belongs" to.  If
  92     // the Task owns a Capability, then task->cap points to it.  If
  93     // the task does not own a Capability, then either (a) if the task
  94     // is a worker, then task->cap points to the Capability it belongs
  95     // to, or (b) it is returning from a foreign call, then task->cap
  96     // points to the Capability with the returning_worker queue that this
  97     // this Task is on.
  98     //
  99     // When a task goes to sleep, it may be migrated to a different
 100     // Capability.  Hence, we always check task->cap on wakeup.  To
 101     // syncrhonise between the migrater and the migratee, task->lock
 102     // must be held when modifying task->cap.
 103     struct Capability_ *cap;
 104
 105     rtsBool    stopped;         // this task has stopped or exited Haskell
 106     StgTSO *   suspended_tso;   // the TSO is stashed here when we
 107                                 // make a foreign call (NULL otherwise);
 108
 109     // The following 3 fields are used by bound threads:
 110     StgTSO *   tso;             // the bound TSO (or NULL)
 111     SchedulerStatus  stat;      // return status
 112     StgClosure **    ret;       // return value
 113
 114 #if defined(THREADED_RTS)
 115     Condition cond;             // used for sleeping & waking up this task
 116     Mutex lock;                 // lock for the condition variable
 117
 118     // this flag tells the task whether it should wait on task->cond
 119     // or just continue immediately.  It's a workaround for the fact
 120     // that signalling a condition variable doesn't do anything if the
 121     // thread is already running, but we want it to be sticky.
 122     rtsBool wakeup;
 123 #endif
 124
 125     // Stats that we collect about this task
 126     // ToDo: we probably want to put this in a separate TaskStats
 127     // structure, so we can share it between multiple Tasks.  We don't
 128     // really want separate stats for each call in a nested chain of
 129     // foreign->haskell->foreign->haskell calls, but we'll get a
 130     // separate Task for each of the haskell calls.
 131     Ticks       elapsedtimestart;
 132     Ticks       muttimestart;
 133     Ticks       mut_time;
 134     Ticks       mut_etime;
 135     Ticks       gc_time;
 136     Ticks       gc_etime;
 137
 138     // Links tasks onto various lists. (ToDo: do we need double
 139     // linking now?)
 140     struct Task_ *prev;
 141     struct Task_ *next;
 142
 143     // Links tasks on the returning_tasks queue of a Capability.
 144     struct Task_ *return_link;
 145
 146     // Links tasks on the all_tasks list
 147     struct Task_ *all_link;
 148
 149     // When a Haskell thread makes a foreign call that re-enters
 150     // Haskell, we end up with another Task associated with the
 151     // current thread.  We have to remember the whole stack of Tasks
 152     // associated with the current thread so that we can correctly
 153     // save & restore the thread-local current task pointer.
 154     struct Task_ *prev_stack;
 155 } Task;
 156
 157 INLINE_HEADER rtsBool
 158 isBoundTask (Task *task)
 159 {
 160     return (task->tso != NULL);
 161 }
 162
 163
 164 // Linked list of all tasks.
 165 //
 166 extern Task *all_tasks;
 167
 168 // Start and stop the task manager.
 169 // Requires: sched_mutex.
 170 //
 171 void initTaskManager (void);
 172 void stopTaskManager (void);
 173
 174 // Create a new Task for a bound thread
 175 // Requires: sched_mutex.
 176 //
 177 Task *newBoundTask (void);
 178
 179 // The current task is a bound task that is exiting.
 180 // Requires: sched_mutex.
 181 //
 182 void boundTaskExiting (Task *task);
 183
 184 // This must be called when a new Task is associated with the current
 185 // thread.  It sets up the thread-local current task pointer so that
 186 // myTask() can work.
 187 INLINE_HEADER void taskEnter (Task *task);
 188
 189 // Notify the task manager that a task has stopped.  This is used
 190 // mainly for stats-gathering purposes.
 191 // Requires: sched_mutex.
 192 //
 193 void workerTaskStop (Task *task);
 194
 195 // Record the time spent in this Task.
 196 // This is called by workerTaskStop() but not by boundTaskExiting(),
 197 // because it would impose an extra overhead on call-in.
 198 //
 199 void taskTimeStamp (Task *task);
 200
 201 // Put the task back on the free list, mark it stopped.  Used by
 202 // forkProcess().
 203 //
 204 void discardTask (Task *task);
 205
 206 // Get the Task associated with the current OS thread (or NULL if none).
 207 //
 208 INLINE_HEADER Task *myTask (void);
 209
 210 // After a fork, the tasks are not carried into the child process, so
 211 // we must tell the task manager.
 212 // Requires: sched_mutex.
 213 //
 214 void resetTaskManagerAfterFork (void);
 215
 216 #if defined(THREADED_RTS)
 217
 218 // Workers are attached to the supplied Capability.  This Capability
 219 // should not currently have a running_task, because the new task
 220 // will become the running_task for that Capability.
 221 // Requires: sched_mutex.
 222 //
 223 void startWorkerTask  (struct Capability_ *cap,
 224                        void OSThreadProcAttr (*taskStart)(Task *task));
 225
 226 #endif /* THREADED_RTS */
 227
 228 // -----------------------------------------------------------------------------
 229 // INLINE functions... private from here on down:
 230
 231 // A thread-local-storage key that we can use to get access to the
 232 // current thread's Task structure.
 233 #if defined(THREADED_RTS)
 234 extern ThreadLocalKey currentTaskKey;
 235 #else
 236 extern Task *my_task;
 237 #endif
 238
 239 //
 240 // myTask() uses thread-local storage to find the Task associated with
 241 // the current OS thread.  If the current OS thread has multiple
 242 // Tasks, because it has re-entered the RTS, then the task->prev_stack
 243 // field is used to store the previous Task.
 244 //
 245 INLINE_HEADER Task *
 246 myTask (void)
 247 {
 248 #if defined(THREADED_RTS)
 249     return getThreadLocalVar(&currentTaskKey);
 250 #else
 251     return my_task;
 252 #endif
 253 }
 254
 255 INLINE_HEADER void
 256 setMyTask (Task *task)
 257 {
 258 #if defined(THREADED_RTS)
 259     setThreadLocalVar(&currentTaskKey,task);
 260 #else
 261     my_task = task;
 262 #endif
 263 }
 264
 265 // This must be called when a new Task is associated with the current
 266 // thread.  It sets up the thread-local current task pointer so that
 267 // myTask() can work.
 268 INLINE_HEADER void
 269 taskEnter (Task *task)
 270 {
 271     // save the current value, just in case this Task has been created
 272     // as a result of re-entering the RTS (defaults to NULL):
 273     task->prev_stack = myTask();
 274     setMyTask(task);
 275 }
 276
 277 #endif /* TASK_H */