ghc/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 /* Definition of a Task:
  13  *
  14  * A task is an OSThread that runs Haskell code.  Every OSThread
  15  * created by the RTS for the purposes of running Haskell code is a
  16  * Task.  We maintain information about Tasks mainly for the purposes
  17  * of stats gathering.
  18  *
  19  * There may exist OSThreads that run Haskell code, but which aren't
  20  * tasks (they don't have an associated TaskInfo structure).  This
  21  * happens when a thread makes an in-call to Haskell: we don't want to
  22  * create a Task for every in-call and register stats for all these
  23  * threads, so it is not therefore mandatory to have a Task for every
  24  * thread running Haskell code.
  25  *
  26  * The SMP build lets multiple tasks concurrently execute STG code,
  27  * all sharing vital internal RTS data structures in a controlled manner.
  28  *
  29  * The 'threaded' build has at any one time only one task executing STG
  30  * code, other tasks are either busy executing code outside the RTS
  31  * (e.g., a C call) or waiting for their turn to (again) evaluate some
  32  * STG code. A task relinquishes its RTS token when it is asked to
  33  * evaluate an external (C) call.
  34  */
  35
  36 #if defined(RTS_SUPPORTS_THREADS) /* to the end */
  37 /*
  38  * Tasks evaluate Haskell code; the TaskInfo structure collects together
  39  * misc metadata about a task.
  40  */
  41 typedef struct _TaskInfo {
  42   OSThreadId id;
  43   rtsBool    is_worker;         /* rtsFalse <=> is a bound thread */
  44   rtsBool    stopped;           /* this task has stopped or exited Haskell */
  45   long       elapsedtimestart;
  46   long       muttimestart;
  47   long       mut_time;
  48   long       mut_etime;
  49   long       gc_time;
  50   long       gc_etime;
  51 } TaskInfo;
  52
  53 extern TaskInfo *taskTable;
  54 extern nat taskCount;
  55
  56 /*
  57  * Start and stop the task manager.
  58  * Requires: sched_mutex.
  59  */
  60 extern void initTaskManager (void);
  61 extern void stopTaskManager (void);
  62
  63 /*
  64  * Two ways to start tasks: either singly or in a batch
  65  * Requires: sched_mutex.
  66  */
  67 extern rtsBool startTasks (nat num, void (*taskStart)(void));
  68 extern rtsBool startTask  (void (*taskStart)(void));
  69
  70 /*
  71  * Notify the task manager that a task has stopped.  This is used
  72  * mainly for stats-gathering purposes.
  73  * Requires: sched_mutex.
  74  */
  75 extern void taskStop (void);
  76
  77 /*
  78  * After a fork, the tasks are not carried into the child process, so
  79  * we must tell the task manager.
  80  * Requires: sched_mutex.
  81  */
  82 extern void resetTaskManagerAfterFork (void);
  83
  84 /*
  85  * Tell the task manager that the current OS thread is now a task,
  86  * because it has entered Haskell as a bound thread.
  87  * Requires: sched_mutex.
  88  */
  89 extern TaskInfo* threadIsTask (OSThreadId id);
  90
  91 /*
  92  * Get the TaskInfo structure corresponding to an OSThread.  Returns
  93  * NULL if the thread is not a task.
  94  * Requires: sched_mutex.
  95  */
  96 extern TaskInfo* taskOfId (OSThreadId id);
  97
  98 /*
  99  * Decides whether to call startTask() or not, based on how many
 100  * workers are already running and waiting for work.  Returns
 101  * rtsTrue if a worker was created.
 102  * Requires: sched_mutex.
 103  */
 104 extern rtsBool maybeStartNewWorker (void (*taskStart)(void));
 105
 106 #endif /* RTS_SUPPORTS_THREADS */
 107 #endif /* __TASK_H__ */