1 /* ---------------------------------------------------------------------------
2 * (c) The GHC Team, 2003
6 * A Capability represent the token required to execute STG code,
7 * and all the state an OS thread/task needs to run Haskell code:
8 * its STG registers, a pointer to its TSO, a nursery etc. During
9 * STG execution, a pointer to the capabilitity is kept in a
12 * Only in an SMP build will there be multiple capabilities, for
13 * the threaded RTS and other non-threaded builds, there is only
14 * one global capability, namely MainCapability.
16 * --------------------------------------------------------------------------*/
18 #include "PosixSource.h"
22 #include "OSThreads.h"
23 #include "Capability.h"
24 #include "Schedule.h" /* to get at EMPTY_RUN_QUEUE() */
27 Capability MainCapability; /* for non-SMP, we have one global capability */
30 Capability *capabilities = NULL;
31 nat rts_n_free_capabilities;
33 #if defined(RTS_SUPPORTS_THREADS)
35 /* returning_worker_cond: when a worker thread returns from executing an
36 * external call, it needs to wait for an RTS Capability before passing
37 * on the result of the call to the Haskell thread that made it.
39 * returning_worker_cond is signalled in Capability.releaseCapability().
42 Condition returning_worker_cond = INIT_COND_VAR;
45 * To avoid starvation of threads blocked on worker_thread_cond,
46 * the task(s) that enter the Scheduler will check to see whether
47 * there are one or more worker threads blocked waiting on
48 * returning_worker_cond.
50 nat rts_n_waiting_workers = 0;
52 /* thread_ready_cond: when signalled, a thread has become runnable for a
55 * In the non-SMP case, it also implies that the thread that is woken up has
56 * exclusive access to the RTS and all its data structures (that are not
57 * locked by the Scheduler's mutex).
59 * thread_ready_cond is signalled whenever
60 * !noCapabilities && !EMPTY_RUN_QUEUE().
62 Condition thread_ready_cond = INIT_COND_VAR;
65 * To be able to make an informed decision about whether or not
66 * to create a new task when making an external call, keep track of
67 * the number of tasks currently blocked waiting on thread_ready_cond.
68 * (if > 0 => no need for a new task, just unblock an existing one).
70 * waitForWorkCapability() takes care of keeping it up-to-date;
71 * Task.startTask() uses its current value.
73 nat rts_n_waiting_tasks = 0;
75 static Condition *passTarget = NULL;
76 static rtsBool passingCapability = rtsFalse;
81 * Free capability list.
83 Capability *free_capabilities;
87 #define UNUSED_IF_NOT_SMP
89 #define UNUSED_IF_NOT_SMP STG_UNUSED
92 #if defined(RTS_USER_SIGNALS)
93 #define ANY_WORK_TO_DO() (!EMPTY_RUN_QUEUE() || interrupted || blackholes_need_checking || signals_pending())
95 #define ANY_WORK_TO_DO() (!EMPTY_RUN_QUEUE() || interrupted || blackholes_need_checking)
98 /* ----------------------------------------------------------------------------
100 ------------------------------------------------------------------------- */
103 initCapability( Capability *cap )
105 cap->r.rInHaskell = rtsFalse;
106 cap->f.stgGCEnter1 = (F_)__stg_gc_enter_1;
107 cap->f.stgGCFun = (F_)__stg_gc_fun;
110 /* ---------------------------------------------------------------------------
111 * Function: initCapabilities()
113 * Purpose: set up the Capability handling. For the SMP build,
114 * we keep a table of them, the size of which is
115 * controlled by the user via the RTS flag RtsFlags.ParFlags.nNodes
117 * ------------------------------------------------------------------------- */
119 initCapabilities( void )
124 n = RtsFlags.ParFlags.nNodes;
125 capabilities = stgMallocBytes(n * sizeof(Capability), "initCapabilities");
127 for (i = 0; i < n; i++) {
128 initCapability(&capabilities[i]);
129 capabilities[i].link = &capabilities[i+1];
131 capabilities[n-1].link = NULL;
133 free_capabilities = &capabilities[0];
134 rts_n_free_capabilities = n;
136 IF_DEBUG(scheduler, sched_belch("allocated %d capabilities", n));
138 capabilities = &MainCapability;
139 initCapability(&MainCapability);
140 rts_n_free_capabilities = 1;
143 #if defined(RTS_SUPPORTS_THREADS)
144 initCondition(&returning_worker_cond);
145 initCondition(&thread_ready_cond);
149 /* ----------------------------------------------------------------------------
150 grabCapability( Capability** )
152 (only externally visible when !RTS_SUPPORTS_THREADS. In the
153 threaded RTS, clients must use waitFor*Capability()).
154 ------------------------------------------------------------------------- */
156 #if defined(RTS_SUPPORTS_THREADS)
160 grabCapability( Capability** cap )
163 ASSERT(rts_n_free_capabilities > 0);
164 *cap = free_capabilities;
165 free_capabilities = (*cap)->link;
166 rts_n_free_capabilities--;
168 # if defined(RTS_SUPPORTS_THREADS)
169 ASSERT(rts_n_free_capabilities == 1);
170 rts_n_free_capabilities = 0;
172 *cap = &MainCapability;
174 #if defined(RTS_SUPPORTS_THREADS)
175 IF_DEBUG(scheduler, sched_belch("worker: got capability"));
179 /* ----------------------------------------------------------------------------
180 * Function: releaseCapability(Capability*)
182 * Purpose: Letting go of a capability. Causes a
183 * 'returning worker' thread or a 'waiting worker'
184 * to wake up, in that order.
185 * ------------------------------------------------------------------------- */
188 releaseCapability( Capability* cap UNUSED_IF_NOT_SMP )
190 // Precondition: sched_mutex is held.
191 #if defined(RTS_SUPPORTS_THREADS)
193 ASSERT(rts_n_free_capabilities == 0);
196 cap->link = free_capabilities;
197 free_capabilities = cap;
199 // Check to see whether a worker thread can be given
200 // the go-ahead to return the result of an external call..
201 if (rts_n_waiting_workers > 0) {
202 // Decrement the counter here to avoid livelock where the
203 // thread that is yielding its capability will repeatedly
204 // signal returning_worker_cond.
206 rts_n_waiting_workers--;
207 signalCondition(&returning_worker_cond);
208 IF_DEBUG(scheduler, sched_belch("worker: released capability to returning worker"));
209 } else if (passingCapability) {
210 if (passTarget == NULL) {
211 signalCondition(&thread_ready_cond);
212 startSchedulerTaskIfNecessary();
214 signalCondition(passTarget);
216 rts_n_free_capabilities++;
217 IF_DEBUG(scheduler, sched_belch("worker: released capability, passing it"));
220 rts_n_free_capabilities++;
221 // Signal that a capability is available
222 if (rts_n_waiting_tasks > 0 && ANY_WORK_TO_DO()) {
223 signalCondition(&thread_ready_cond);
225 startSchedulerTaskIfNecessary();
226 IF_DEBUG(scheduler, sched_belch("worker: released capability"));
232 #if defined(RTS_SUPPORTS_THREADS)
234 * When a native thread has completed the execution of an external
235 * call, it needs to communicate the result back. This is done
238 * - in resumeThread(), the thread calls waitForReturnCapability().
239 * - If no capabilities are readily available, waitForReturnCapability()
240 * increments a counter rts_n_waiting_workers, and blocks
241 * waiting for the condition returning_worker_cond to become
243 * - upon entry to the Scheduler, a worker thread checks the
244 * value of rts_n_waiting_workers. If > 0, the worker thread
245 * will yield its capability to let a returning worker thread
246 * proceed with returning its result -- this is done via
247 * yieldToReturningWorker().
248 * - the worker thread that yielded its capability then tries
249 * to re-grab a capability and re-enter the Scheduler.
252 /* ----------------------------------------------------------------------------
253 * waitForReturnCapability( Mutext *pMutex, Capability** )
255 * Purpose: when an OS thread returns from an external call,
256 * it calls grabReturnCapability() (via Schedule.resumeThread())
257 * to wait for permissions to enter the RTS & communicate the
258 * result of the external call back to the Haskell thread that
261 * ------------------------------------------------------------------------- */
264 waitForReturnCapability( Mutex* pMutex, Capability** pCap )
266 // Pre-condition: pMutex is held.
269 sched_belch("worker: returning; workers waiting: %d",
270 rts_n_waiting_workers));
272 if ( noCapabilities() || passingCapability ) {
273 rts_n_waiting_workers++;
274 context_switch = 1; // make sure it's our turn soon
275 waitCondition(&returning_worker_cond, pMutex);
277 *pCap = free_capabilities;
278 free_capabilities = (*pCap)->link;
279 ASSERT(pCap != NULL);
281 *pCap = &MainCapability;
282 ASSERT(rts_n_free_capabilities == 0);
285 grabCapability(pCap);
288 // Post-condition: pMutex is held, pCap points to a capability
289 // which is now held by the current thread.
294 /* ----------------------------------------------------------------------------
295 * yieldCapability( Mutex* pMutex, Capability** pCap )
296 * ------------------------------------------------------------------------- */
299 yieldCapability( Capability** pCap )
301 // Pre-condition: pMutex is assumed held, the current thread
302 // holds the capability pointed to by pCap.
304 if ( rts_n_waiting_workers > 0 || passingCapability || !ANY_WORK_TO_DO()) {
306 if (rts_n_waiting_workers > 0) {
307 sched_belch("worker: giving up capability (returning wkr)");
308 } else if (passingCapability) {
309 sched_belch("worker: giving up capability (passing capability)");
311 sched_belch("worker: giving up capability (no threads to run)");
314 releaseCapability(*pCap);
318 // Post-condition: either:
320 // 1. *pCap is NULL, in which case the current thread does not
321 // hold a capability now, or
322 // 2. *pCap is not NULL, in which case the current thread still
323 // holds the capability.
329 /* ----------------------------------------------------------------------------
330 * waitForCapability( Mutex*, Capability**, Condition* )
332 * Purpose: wait for a Capability to become available. In
333 * the process of doing so, updates the number
334 * of tasks currently blocked waiting for a capability/more
335 * work. That counter is used when deciding whether or
336 * not to create a new worker thread when an external
338 * If pThreadCond is not NULL, a capability can be specifically
339 * passed to this thread using passCapability.
340 * ------------------------------------------------------------------------- */
343 waitForCapability( Mutex* pMutex, Capability** pCap, Condition* pThreadCond )
345 // Pre-condition: pMutex is held.
347 while ( noCapabilities() ||
348 (passingCapability && passTarget != pThreadCond) ||
351 sched_belch("worker: wait for capability (cond: %p)",
354 if (pThreadCond != NULL) {
355 waitCondition(pThreadCond, pMutex);
356 IF_DEBUG(scheduler, sched_belch("worker: get passed capability"));
358 rts_n_waiting_tasks++;
359 waitCondition(&thread_ready_cond, pMutex);
360 rts_n_waiting_tasks--;
361 IF_DEBUG(scheduler, sched_belch("worker: get normal capability"));
364 passingCapability = rtsFalse;
365 grabCapability(pCap);
367 // Post-condition: pMutex is held and *pCap is held by the current thread
371 /* ----------------------------------------------------------------------------
372 passCapability, passCapabilityToWorker
373 ------------------------------------------------------------------------- */
376 passCapability( Condition *pTargetThreadCond )
378 // Pre-condition: pMutex is held and cap is held by the current thread
380 passTarget = pTargetThreadCond;
381 passingCapability = rtsTrue;
382 IF_DEBUG(scheduler, sched_belch("worker: passCapability"));
384 // Post-condition: pMutex is held; cap is still held, but will be
385 // passed to the target thread when next released.
389 passCapabilityToWorker( void )
391 // Pre-condition: pMutex is held and cap is held by the current thread
394 passingCapability = rtsTrue;
395 IF_DEBUG(scheduler, sched_belch("worker: passCapabilityToWorker"));
397 // Post-condition: pMutex is held; cap is still held, but will be
398 // passed to a worker thread when next released.
401 #endif /* RTS_SUPPORTS_THREADS */
403 /* ----------------------------------------------------------------------------
406 Signals that a thread has been placed on the run queue, so a worker
407 might need to be woken up to run it.
409 ToDo: should check whether the thread at the front of the queue is
410 bound, and if so wake up the appropriate worker.
411 -------------------------------------------------------------------------- */
413 threadRunnable ( void )
415 #if defined(RTS_SUPPORTS_THREADS)
416 if ( !noCapabilities() && ANY_WORK_TO_DO() && rts_n_waiting_tasks > 0 ) {
417 signalCondition(&thread_ready_cond);
419 startSchedulerTaskIfNecessary();
424 /* ----------------------------------------------------------------------------
427 Wake up... time to die.
428 -------------------------------------------------------------------------- */
432 #if defined(RTS_SUPPORTS_THREADS)
433 signalCondition(&thread_ready_cond);