Reorganisation of the source tree
[ghc.git] / 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 taskStop (Task *task);
194
195 // Put the task back on the free list, mark it stopped. Used by
196 // forkProcess().
197 //
198 void discardTask (Task *task);
199
200 // Get the Task associated with the current OS thread (or NULL if none).
201 //
202 INLINE_HEADER Task *myTask (void);
203
204 // After a fork, the tasks are not carried into the child process, so
205 // we must tell the task manager.
206 // Requires: sched_mutex.
207 //
208 void resetTaskManagerAfterFork (void);
209
210 #if defined(THREADED_RTS)
211
212 // Workers are attached to the supplied Capability. This Capability
213 // should not currently have a running_task, because the new task
214 // will become the running_task for that Capability.
215 // Requires: sched_mutex.
216 //
217 void startWorkerTask (struct Capability_ *cap,
218 void OSThreadProcAttr (*taskStart)(Task *task));
219
220 #endif /* THREADED_RTS */
221
222 // -----------------------------------------------------------------------------
223 // INLINE functions... private from here on down:
224
225 // A thread-local-storage key that we can use to get access to the
226 // current thread's Task structure.
227 #if defined(THREADED_RTS)
228 extern ThreadLocalKey currentTaskKey;
229 #else
230 extern Task *my_task;
231 #endif
232
233 //
234 // myTask() uses thread-local storage to find the Task associated with
235 // the current OS thread. If the current OS thread has multiple
236 // Tasks, because it has re-entered the RTS, then the task->prev_stack
237 // field is used to store the previous Task.
238 //
239 INLINE_HEADER Task *
240 myTask (void)
241 {
242 #if defined(THREADED_RTS)
243 return getThreadLocalVar(&currentTaskKey);
244 #else
245 return my_task;
246 #endif
247 }
248
249 INLINE_HEADER void
250 setMyTask (Task *task)
251 {
252 #if defined(THREADED_RTS)
253 setThreadLocalVar(&currentTaskKey,task);
254 #else
255 my_task = task;
256 #endif
257 }
258
259 // This must be called when a new Task is associated with the current
260 // thread. It sets up the thread-local current task pointer so that
261 // myTask() can work.
262 INLINE_HEADER void
263 taskEnter (Task *task)
264 {
265 // save the current value, just in case this Task has been created
266 // as a result of re-entering the RTS (defaults to NULL):
267 task->prev_stack = myTask();
268 setMyTask(task);
269 }
270
271 #endif /* TASK_H */