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() */
30 Capability MainCapability; /* for non-SMP, we have one global capability */
33 Capability *capabilities = NULL;
34 nat rts_n_free_capabilities;
36 #if defined(RTS_SUPPORTS_THREADS)
38 /* returning_worker_cond: when a worker thread returns from executing an
39 * external call, it needs to wait for an RTS Capability before passing
40 * on the result of the call to the Haskell thread that made it.
42 * returning_worker_cond is signalled in Capability.releaseCapability().
45 Condition returning_worker_cond = INIT_COND_VAR;
48 * To avoid starvation of threads blocked on worker_thread_cond,
49 * the task(s) that enter the Scheduler will check to see whether
50 * there are one or more worker threads blocked waiting on
51 * returning_worker_cond.
53 nat rts_n_waiting_workers = 0;
55 /* thread_ready_cond: when signalled, a thread has become runnable for a
58 * In the non-SMP case, it also implies that the thread that is woken up has
59 * exclusive access to the RTS and all its data structures (that are not
60 * locked by the Scheduler's mutex).
62 * thread_ready_cond is signalled whenever
63 * !noCapabilities && !EMPTY_RUN_QUEUE().
65 Condition thread_ready_cond = INIT_COND_VAR;
68 * To be able to make an informed decision about whether or not
69 * to create a new task when making an external call, keep track of
70 * the number of tasks currently blocked waiting on thread_ready_cond.
71 * (if > 0 => no need for a new task, just unblock an existing one).
73 * waitForWorkCapability() takes care of keeping it up-to-date;
74 * Task.startTask() uses its current value.
76 nat rts_n_waiting_tasks = 0;
78 static Condition *passTarget = NULL;
79 static rtsBool passingCapability = rtsFalse;
84 * Free capability list.
86 Capability *free_capabilities;
89 * Maps OSThreadId to Capability *
91 HashTable *capability_hash;
95 #define UNUSED_IF_NOT_SMP
97 #define UNUSED_IF_NOT_SMP STG_UNUSED
100 #if defined(RTS_USER_SIGNALS)
101 #define ANY_WORK_TO_DO() (!EMPTY_RUN_QUEUE() || interrupted || blackholes_need_checking || signals_pending())
103 #define ANY_WORK_TO_DO() (!EMPTY_RUN_QUEUE() || interrupted || blackholes_need_checking)
106 /* ----------------------------------------------------------------------------
108 ------------------------------------------------------------------------- */
111 initCapability( Capability *cap )
113 cap->r.rInHaskell = rtsFalse;
114 cap->f.stgGCEnter1 = (F_)__stg_gc_enter_1;
115 cap->f.stgGCFun = (F_)__stg_gc_fun;
118 /* ---------------------------------------------------------------------------
119 * Function: initCapabilities()
121 * Purpose: set up the Capability handling. For the SMP build,
122 * we keep a table of them, the size of which is
123 * controlled by the user via the RTS flag RtsFlags.ParFlags.nNodes
125 * ------------------------------------------------------------------------- */
127 initCapabilities( void )
132 n = RtsFlags.ParFlags.nNodes;
133 capabilities = stgMallocBytes(n * sizeof(Capability), "initCapabilities");
135 for (i = 0; i < n; i++) {
136 initCapability(&capabilities[i]);
137 capabilities[i].link = &capabilities[i+1];
139 capabilities[n-1].link = NULL;
141 free_capabilities = &capabilities[0];
142 rts_n_free_capabilities = n;
144 capability_hash = allocHashTable();
146 IF_DEBUG(scheduler, sched_belch("allocated %d capabilities", n));
148 capabilities = &MainCapability;
149 initCapability(&MainCapability);
150 rts_n_free_capabilities = 1;
153 #if defined(RTS_SUPPORTS_THREADS)
154 initCondition(&returning_worker_cond);
155 initCondition(&thread_ready_cond);
159 /* ----------------------------------------------------------------------------
160 grabCapability( Capability** )
162 (only externally visible when !RTS_SUPPORTS_THREADS. In the
163 threaded RTS, clients must use waitFor*Capability()).
164 ------------------------------------------------------------------------- */
166 #if defined(RTS_SUPPORTS_THREADS)
170 grabCapability( Capability** cap )
173 ASSERT(rts_n_free_capabilities > 0);
174 *cap = free_capabilities;
175 free_capabilities = (*cap)->link;
176 rts_n_free_capabilities--;
177 insertHashTable(capability_hash, osThreadId(), *cap);
179 # if defined(RTS_SUPPORTS_THREADS)
180 ASSERT(rts_n_free_capabilities == 1);
181 rts_n_free_capabilities = 0;
183 *cap = &MainCapability;
185 #if defined(RTS_SUPPORTS_THREADS)
186 IF_DEBUG(scheduler, sched_belch("worker: got capability"));
190 /* ----------------------------------------------------------------------------
191 * Function: myCapability(void)
193 * Purpose: Return the capability owned by the current thread.
194 * Should not be used if the current thread does not
196 * ------------------------------------------------------------------------- */
201 return lookupHashTable(capability_hash, osThreadId());
203 return &MainCapability;
207 /* ----------------------------------------------------------------------------
208 * Function: releaseCapability(Capability*)
210 * Purpose: Letting go of a capability. Causes a
211 * 'returning worker' thread or a 'waiting worker'
212 * to wake up, in that order.
213 * ------------------------------------------------------------------------- */
216 releaseCapability( Capability* cap UNUSED_IF_NOT_SMP )
218 // Precondition: sched_mutex is held.
219 #if defined(RTS_SUPPORTS_THREADS)
221 ASSERT(rts_n_free_capabilities == 0);
224 cap->link = free_capabilities;
225 free_capabilities = cap;
226 ASSERT(myCapability() == cap);
227 removeHashTable(capability_hash, osThreadId(), NULL);
229 // Check to see whether a worker thread can be given
230 // the go-ahead to return the result of an external call..
231 if (rts_n_waiting_workers > 0) {
232 // Decrement the counter here to avoid livelock where the
233 // thread that is yielding its capability will repeatedly
234 // signal returning_worker_cond.
236 rts_n_waiting_workers--;
237 signalCondition(&returning_worker_cond);
238 IF_DEBUG(scheduler, sched_belch("worker: released capability to returning worker"));
239 } else if (passingCapability) {
240 if (passTarget == NULL) {
241 signalCondition(&thread_ready_cond);
242 startSchedulerTaskIfNecessary();
244 signalCondition(passTarget);
246 rts_n_free_capabilities++;
247 IF_DEBUG(scheduler, sched_belch("worker: released capability, passing it"));
250 rts_n_free_capabilities++;
251 // Signal that a capability is available
252 if (rts_n_waiting_tasks > 0 && ANY_WORK_TO_DO()) {
253 signalCondition(&thread_ready_cond);
255 startSchedulerTaskIfNecessary();
256 IF_DEBUG(scheduler, sched_belch("worker: released capability"));
262 #if defined(RTS_SUPPORTS_THREADS)
264 * When a native thread has completed the execution of an external
265 * call, it needs to communicate the result back. This is done
268 * - in resumeThread(), the thread calls waitForReturnCapability().
269 * - If no capabilities are readily available, waitForReturnCapability()
270 * increments a counter rts_n_waiting_workers, and blocks
271 * waiting for the condition returning_worker_cond to become
273 * - upon entry to the Scheduler, a worker thread checks the
274 * value of rts_n_waiting_workers. If > 0, the worker thread
275 * will yield its capability to let a returning worker thread
276 * proceed with returning its result -- this is done via
277 * yieldToReturningWorker().
278 * - the worker thread that yielded its capability then tries
279 * to re-grab a capability and re-enter the Scheduler.
282 /* ----------------------------------------------------------------------------
283 * waitForReturnCapability( Mutext *pMutex, Capability** )
285 * Purpose: when an OS thread returns from an external call,
286 * it calls grabReturnCapability() (via Schedule.resumeThread())
287 * to wait for permissions to enter the RTS & communicate the
288 * result of the external call back to the Haskell thread that
291 * ------------------------------------------------------------------------- */
294 waitForReturnCapability( Mutex* pMutex, Capability** pCap )
296 // Pre-condition: pMutex is held.
299 sched_belch("worker: returning; workers waiting: %d",
300 rts_n_waiting_workers));
302 if ( noCapabilities() || passingCapability ) {
303 rts_n_waiting_workers++;
304 context_switch = 1; // make sure it's our turn soon
305 waitCondition(&returning_worker_cond, pMutex);
307 *pCap = free_capabilities;
308 free_capabilities = (*pCap)->link;
309 ASSERT(pCap != NULL);
310 insertHashTable(capability_hash, osThreadId(), *pCap);
312 *pCap = &MainCapability;
313 ASSERT(rts_n_free_capabilities == 0);
316 grabCapability(pCap);
319 // Post-condition: pMutex is held, pCap points to a capability
320 // which is now held by the current thread.
325 /* ----------------------------------------------------------------------------
326 * yieldCapability( Mutex* pMutex, Capability** pCap )
327 * ------------------------------------------------------------------------- */
330 yieldCapability( Capability** pCap )
332 // Pre-condition: pMutex is assumed held, the current thread
333 // holds the capability pointed to by pCap.
335 if ( rts_n_waiting_workers > 0 || passingCapability || !ANY_WORK_TO_DO()) {
337 if (rts_n_waiting_workers > 0) {
338 sched_belch("worker: giving up capability (returning wkr)");
339 } else if (passingCapability) {
340 sched_belch("worker: giving up capability (passing capability)");
342 sched_belch("worker: giving up capability (no threads to run)");
345 releaseCapability(*pCap);
349 // Post-condition: either:
351 // 1. *pCap is NULL, in which case the current thread does not
352 // hold a capability now, or
353 // 2. *pCap is not NULL, in which case the current thread still
354 // holds the capability.
360 /* ----------------------------------------------------------------------------
361 * waitForCapability( Mutex*, Capability**, Condition* )
363 * Purpose: wait for a Capability to become available. In
364 * the process of doing so, updates the number
365 * of tasks currently blocked waiting for a capability/more
366 * work. That counter is used when deciding whether or
367 * not to create a new worker thread when an external
369 * If pThreadCond is not NULL, a capability can be specifically
370 * passed to this thread using passCapability.
371 * ------------------------------------------------------------------------- */
374 waitForCapability( Mutex* pMutex, Capability** pCap, Condition* pThreadCond )
376 // Pre-condition: pMutex is held.
378 while ( noCapabilities() ||
379 (passingCapability && passTarget != pThreadCond) ||
382 sched_belch("worker: wait for capability (cond: %p)",
385 if (pThreadCond != NULL) {
386 waitCondition(pThreadCond, pMutex);
387 IF_DEBUG(scheduler, sched_belch("worker: get passed capability"));
389 rts_n_waiting_tasks++;
390 waitCondition(&thread_ready_cond, pMutex);
391 rts_n_waiting_tasks--;
392 IF_DEBUG(scheduler, sched_belch("worker: get normal capability"));
395 passingCapability = rtsFalse;
396 grabCapability(pCap);
398 // Post-condition: pMutex is held and *pCap is held by the current thread
402 /* ----------------------------------------------------------------------------
403 passCapability, passCapabilityToWorker
404 ------------------------------------------------------------------------- */
407 passCapability( Condition *pTargetThreadCond )
409 // Pre-condition: pMutex is held and cap is held by the current thread
411 passTarget = pTargetThreadCond;
412 passingCapability = rtsTrue;
413 IF_DEBUG(scheduler, sched_belch("worker: passCapability"));
415 // Post-condition: pMutex is held; cap is still held, but will be
416 // passed to the target thread when next released.
420 passCapabilityToWorker( void )
422 // Pre-condition: pMutex is held and cap is held by the current thread
425 passingCapability = rtsTrue;
426 IF_DEBUG(scheduler, sched_belch("worker: passCapabilityToWorker"));
428 // Post-condition: pMutex is held; cap is still held, but will be
429 // passed to a worker thread when next released.
432 #endif /* RTS_SUPPORTS_THREADS */
434 /* ----------------------------------------------------------------------------
437 Signals that a thread has been placed on the run queue, so a worker
438 might need to be woken up to run it.
440 ToDo: should check whether the thread at the front of the queue is
441 bound, and if so wake up the appropriate worker.
442 -------------------------------------------------------------------------- */
444 threadRunnable ( void )
446 #if defined(RTS_SUPPORTS_THREADS)
447 if ( !noCapabilities() && ANY_WORK_TO_DO() && rts_n_waiting_tasks > 0 ) {
448 signalCondition(&thread_ready_cond);
450 startSchedulerTaskIfNecessary();
455 /* ----------------------------------------------------------------------------
458 Wake up... time to die.
459 -------------------------------------------------------------------------- */
463 #if defined(RTS_SUPPORTS_THREADS)
464 signalCondition(&thread_ready_cond);