1 /* -----------------------------------------------------------------------------
3 * (c) The GHC Team 2001-2005
7 * -------------------------------------------------------------------------*/
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.
23 In the THREADED_RTS build, multiple Tasks may all be running
24 Haskell code simultaneously. A task relinquishes its Capability
25 when it is asked to evaluate an external (C) call.
27 In general, there may be multiple Tasks associated with a given OS
28 thread. A second Task is created when one Task makes a foreign
29 call from Haskell, and subsequently calls back in to Haskell,
30 creating a new bound thread.
32 A particular Task structure can belong to more than one OS thread
33 over its lifetime. This is to avoid creating an unbounded number
34 of Task structures. The stats just accumulate.
39 The OS thread named in the Task structure has exclusive access to
40 the structure, as long as it is the running_task of its Capability.
41 That is, if (task->cap->running_task == task), then task->id owns
42 the Task. Otherwise the Task is owned by the owner of the parent
43 data structure on which it is sleeping; for example, if the task is
44 sleeping on spare_workers field of a Capability, then the owner of the
45 Capability has access to the Task.
47 When a task is migrated from sleeping on one Capability to another,
48 its task->cap field must be modified. When the task wakes up, it
49 will read the new value of task->cap to find out which Capability
50 it belongs to. Hence some synchronisation is required on
51 task->cap, and this is why we have task->lock.
53 If the Task is not currently owned by task->id, then the thread is
56 (a) waiting on the condition task->cond. The Task is either
57 (1) a bound Task, the TSO will be on a queue somewhere
58 (2) a worker task, on the spare_workers queue of task->cap.
60 (b) making a foreign call. The Task will be on the
61 suspended_ccalling_tasks list.
63 We re-establish ownership in each case by respectively
65 (a) the task is currently blocked in yieldCapability().
66 This call will return when we have ownership of the Task and
67 a Capability. The Capability we get might not be the same
68 as the one we had when we called yieldCapability().
70 (b) we must call resumeThread(task), which will safely establish
71 ownership of the Task and a Capability.
74 typedef struct Task_ {
75 #if defined(THREADED_RTS)
76 OSThreadId id; // The OS Thread ID of this task
79 // This points to the Capability that the Task "belongs" to. If
80 // the Task owns a Capability, then task->cap points to it. If
81 // the task does not own a Capability, then either (a) if the task
82 // is a worker, then task->cap points to the Capability it belongs
83 // to, or (b) it is returning from a foreign call, then task->cap
84 // points to the Capability with the returning_worker queue that this
87 // When a task goes to sleep, it may be migrated to a different
88 // Capability. Hence, we always check task->cap on wakeup. To
89 // syncrhonise between the migrater and the migratee, task->lock
90 // must be held when modifying task->cap.
91 struct Capability_ *cap;
93 rtsBool stopped; // this task has stopped or exited Haskell
94 StgTSO * suspended_tso; // the TSO is stashed here when we
95 // make a foreign call (NULL otherwise);
97 // The following 3 fields are used by bound threads:
98 StgTSO * tso; // the bound TSO (or NULL)
99 SchedulerStatus stat; // return status
100 StgClosure ** ret; // return value
102 #if defined(THREADED_RTS)
103 Condition cond; // used for sleeping & waking up this task
104 Mutex lock; // lock for the condition variable
106 // this flag tells the task whether it should wait on task->cond
107 // or just continue immediately. It's a workaround for the fact
108 // that signalling a condition variable doesn't do anything if the
109 // thread is already running, but we want it to be sticky.
113 // Stats that we collect about this task
114 // ToDo: we probably want to put this in a separate TaskStats
115 // structure, so we can share it between multiple Tasks. We don't
116 // really want separate stats for each call in a nested chain of
117 // foreign->haskell->foreign->haskell calls, but we'll get a
118 // separate Task for each of the haskell calls.
119 Ticks elapsedtimestart;
126 // Links tasks onto various lists. (ToDo: do we need double
131 // Links tasks on the returning_tasks queue of a Capability.
132 struct Task_ *return_link;
134 // Links tasks on the all_tasks list
135 struct Task_ *all_link;
137 // When a Haskell thread makes a foreign call that re-enters
138 // Haskell, we end up with another Task associated with the
139 // current thread. We have to remember the whole stack of Tasks
140 // associated with the current thread so that we can correctly
141 // save & restore the thread-local current task pointer.
142 struct Task_ *prev_stack;
145 INLINE_HEADER rtsBool
146 isBoundTask (Task *task)
148 return (task->tso != NULL);
152 // Linked list of all tasks.
154 extern Task *all_tasks;
156 // Start and stop the task manager.
157 // Requires: sched_mutex.
159 void initTaskManager (void);
160 nat freeTaskManager (void);
162 // Create a new Task for a bound thread
163 // Requires: sched_mutex.
165 Task *newBoundTask (void);
167 // The current task is a bound task that is exiting.
168 // Requires: sched_mutex.
170 void boundTaskExiting (Task *task);
172 // This must be called when a new Task is associated with the current
173 // thread. It sets up the thread-local current task pointer so that
174 // myTask() can work.
175 INLINE_HEADER void taskEnter (Task *task);
177 // Notify the task manager that a task has stopped. This is used
178 // mainly for stats-gathering purposes.
179 // Requires: sched_mutex.
181 #if defined(THREADED_RTS)
182 // In the non-threaded RTS, tasks never stop.
183 void workerTaskStop (Task *task);
186 // Record the time spent in this Task.
187 // This is called by workerTaskStop() but not by boundTaskExiting(),
188 // because it would impose an extra overhead on call-in.
190 void taskTimeStamp (Task *task);
192 // Put the task back on the free list, mark it stopped. Used by
195 void discardTask (Task *task);
197 // Get the Task associated with the current OS thread (or NULL if none).
199 INLINE_HEADER Task *myTask (void);
201 #if defined(THREADED_RTS)
203 // Workers are attached to the supplied Capability. This Capability
204 // should not currently have a running_task, because the new task
205 // will become the running_task for that Capability.
206 // Requires: sched_mutex.
208 void startWorkerTask (struct Capability_ *cap,
209 void OSThreadProcAttr (*taskStart)(Task *task));
211 #endif /* THREADED_RTS */
213 // -----------------------------------------------------------------------------
214 // INLINE functions... private from here on down:
216 // A thread-local-storage key that we can use to get access to the
217 // current thread's Task structure.
218 #if defined(THREADED_RTS)
219 extern ThreadLocalKey currentTaskKey;
221 extern Task *my_task;
225 // myTask() uses thread-local storage to find the Task associated with
226 // the current OS thread. If the current OS thread has multiple
227 // Tasks, because it has re-entered the RTS, then the task->prev_stack
228 // field is used to store the previous Task.
233 #if defined(THREADED_RTS)
234 return getThreadLocalVar(¤tTaskKey);
241 setMyTask (Task *task)
243 #if defined(THREADED_RTS)
244 setThreadLocalVar(¤tTaskKey,task);
250 // This must be called when a new Task is associated with the current
251 // thread. It sets up the thread-local current task pointer so that
252 // myTask() can work.
254 taskEnter (Task *task)
256 // save the current value, just in case this Task has been created
257 // as a result of re-entering the RTS (defaults to NULL):
258 task->prev_stack = myTask();