1 /* ---------------------------------------------------------------------------
3 * (c) The GHC Team, 2003-2005
7 * A Capability represent the token required to execute STG code,
8 * and all the state an OS thread/task needs to run Haskell code:
9 * its STG registers, a pointer to its TSO, a nursery etc. During
10 * STG execution, a pointer to the capabilitity is kept in a
11 * register (BaseReg; actually it is a pointer to cap->r).
13 * Only in an SMP build will there be multiple capabilities, for
14 * the threaded RTS and other non-threaded builds, there is only
15 * one global capability, namely MainCapability.
17 * --------------------------------------------------------------------------*/
19 #include "PosixSource.h"
23 #include "OSThreads.h"
24 #include "Capability.h"
28 Capability MainCapability; // for non-SMP, we have one global capability
32 Capability *capabilities = NULL;
34 // Holds the Capability which last became free. This is used so that
35 // an in-call has a chance of quickly finding a free Capability.
36 // Maintaining a global free list of Capabilities would require global
37 // locking, so we don't do that.
38 Capability *last_free_capability;
41 #define UNUSED_IF_NOT_SMP
43 #define UNUSED_IF_NOT_SMP STG_UNUSED
46 #ifdef RTS_USER_SIGNALS
47 #define UNUSED_IF_NOT_THREADS
49 #define UNUSED_IF_NOT_THREADS STG_UNUSED
56 return blackholes_need_checking
58 #if defined(RTS_USER_SIGNALS)
64 #if defined(THREADED_RTS)
66 anyWorkForMe( Capability *cap, Task *task )
68 // If the run queue is not empty, then we only wake up the guy who
69 // can run the thread at the head, even if there is some other
70 // reason for this task to run (eg. interrupted=rtsTrue).
71 if (!emptyRunQueue(cap)) {
72 if (cap->run_queue_hd->bound == NULL) {
73 return (task->tso == NULL);
75 return (cap->run_queue_hd->bound == task);
78 return globalWorkToDo();
82 /* -----------------------------------------------------------------------------
83 * Manage the returning_tasks lists.
85 * These functions require cap->lock
86 * -------------------------------------------------------------------------- */
88 #if defined(THREADED_RTS)
90 newReturningTask (Capability *cap, Task *task)
92 ASSERT_LOCK_HELD(&cap->lock);
93 ASSERT(task->return_link == NULL);
94 if (cap->returning_tasks_hd) {
95 ASSERT(cap->returning_tasks_tl->return_link == NULL);
96 cap->returning_tasks_tl->return_link = task;
98 cap->returning_tasks_hd = task;
100 cap->returning_tasks_tl = task;
104 popReturningTask (Capability *cap)
106 ASSERT_LOCK_HELD(&cap->lock);
108 task = cap->returning_tasks_hd;
110 cap->returning_tasks_hd = task->return_link;
111 if (!cap->returning_tasks_hd) {
112 cap->returning_tasks_tl = NULL;
114 task->return_link = NULL;
119 /* ----------------------------------------------------------------------------
122 * The Capability is initially marked not free.
123 * ------------------------------------------------------------------------- */
126 initCapability( Capability *cap, nat i )
131 cap->in_haskell = rtsFalse;
133 cap->run_queue_hd = END_TSO_QUEUE;
134 cap->run_queue_tl = END_TSO_QUEUE;
136 #if defined(THREADED_RTS)
137 initMutex(&cap->lock);
138 cap->running_task = NULL; // indicates cap is free
139 cap->spare_workers = NULL;
140 cap->suspended_ccalling_tasks = NULL;
141 cap->returning_tasks_hd = NULL;
142 cap->returning_tasks_tl = NULL;
145 cap->f.stgGCEnter1 = (F_)__stg_gc_enter_1;
146 cap->f.stgGCFun = (F_)__stg_gc_fun;
148 cap->mut_lists = stgMallocBytes(sizeof(bdescr *) *
149 RtsFlags.GcFlags.generations,
151 for (g = 0; g < RtsFlags.GcFlags.generations; g++) {
152 cap->mut_lists[g] = NULL;
156 /* ---------------------------------------------------------------------------
157 * Function: initCapabilities()
159 * Purpose: set up the Capability handling. For the SMP build,
160 * we keep a table of them, the size of which is
161 * controlled by the user via the RTS flag -N.
163 * ------------------------------------------------------------------------- */
165 initCapabilities( void )
170 n_capabilities = n = RtsFlags.ParFlags.nNodes;
171 capabilities = stgMallocBytes(n * sizeof(Capability), "initCapabilities");
173 for (i = 0; i < n; i++) {
174 initCapability(&capabilities[i], i);
177 IF_DEBUG(scheduler, sched_belch("allocated %d capabilities", n));
180 capabilities = &MainCapability;
181 initCapability(&MainCapability, 0);
184 // There are no free capabilities to begin with. We will start
185 // a worker Task to each Capability, which will quickly put the
186 // Capability on the free list when it finds nothing to do.
187 last_free_capability = &capabilities[0];
190 /* ----------------------------------------------------------------------------
191 * Give a Capability to a Task. The task must currently be sleeping
192 * on its condition variable.
194 * Requires cap->lock (modifies cap->running_task).
196 * When migrating a Task, the migrater must take task->lock before
197 * modifying task->cap, to synchronise with the waking up Task.
198 * Additionally, the migrater should own the Capability (when
199 * migrating the run queue), or cap->lock (when migrating
200 * returning_workers).
202 * ------------------------------------------------------------------------- */
204 #if defined(THREADED_RTS)
206 giveCapabilityToTask (Capability *cap, Task *task)
208 ASSERT_LOCK_HELD(&cap->lock);
209 ASSERT(task->cap == cap);
210 // We are not modifying task->cap, so we do not need to take task->lock.
212 sched_belch("passing capability %d to %s %p",
213 cap->no, task->tso ? "bound task" : "worker",
215 ACQUIRE_LOCK(&task->lock);
216 task->wakeup = rtsTrue;
217 // the wakeup flag is needed because signalCondition() doesn't
218 // flag the condition if the thread is already runniing, but we want
220 signalCondition(&task->cond);
221 RELEASE_LOCK(&task->lock);
225 /* ----------------------------------------------------------------------------
226 * Function: releaseCapability(Capability*)
228 * Purpose: Letting go of a capability. Causes a
229 * 'returning worker' thread or a 'waiting worker'
230 * to wake up, in that order.
231 * ------------------------------------------------------------------------- */
233 #if defined(THREADED_RTS)
235 releaseCapability_ (Capability* cap)
239 task = cap->running_task;
241 ASSERT_CAPABILITY_INVARIANTS(cap,task);
243 cap->running_task = NULL;
245 // Check to see whether a worker thread can be given
246 // the go-ahead to return the result of an external call..
247 if (cap->returning_tasks_hd != NULL) {
248 giveCapabilityToTask(cap,cap->returning_tasks_hd);
249 // The Task pops itself from the queue (see waitForReturnCapability())
253 // If the next thread on the run queue is a bound thread,
254 // give this Capability to the appropriate Task.
255 if (!emptyRunQueue(cap) && cap->run_queue_hd->bound) {
256 // Make sure we're not about to try to wake ourselves up
257 ASSERT(task != cap->run_queue_hd->bound);
258 task = cap->run_queue_hd->bound;
259 giveCapabilityToTask(cap,task);
263 // If we have an unbound thread on the run queue, or if there's
264 // anything else to do, give the Capability to a worker thread.
265 if (!emptyRunQueue(cap) || globalWorkToDo()) {
266 if (cap->spare_workers) {
267 giveCapabilityToTask(cap,cap->spare_workers);
268 // The worker Task pops itself from the queue;
272 // Create a worker thread if we don't have one. If the system
273 // is interrupted, we only create a worker task if there
274 // are threads that need to be completed. If the system is
275 // shutting down, we never create a new worker.
276 if (!shutting_down_scheduler) {
278 sched_belch("starting new worker on capability %d", cap->no));
279 startWorkerTask(cap, workerStart);
284 last_free_capability = cap;
285 IF_DEBUG(scheduler, sched_belch("freeing capability %d", cap->no));
289 releaseCapability (Capability* cap UNUSED_IF_NOT_THREADS)
291 ACQUIRE_LOCK(&cap->lock);
292 releaseCapability_(cap);
293 RELEASE_LOCK(&cap->lock);
297 releaseCapabilityAndQueueWorker (Capability* cap UNUSED_IF_NOT_THREADS)
301 ACQUIRE_LOCK(&cap->lock);
303 task = cap->running_task;
305 // If the current task is a worker, save it on the spare_workers
306 // list of this Capability. A worker can mark itself as stopped,
307 // in which case it is not replaced on the spare_worker queue.
308 // This happens when the system is shutting down (see
309 // Schedule.c:workerStart()).
310 // Also, be careful to check that this task hasn't just exited
311 // Haskell to do a foreign call (task->suspended_tso).
312 if (!isBoundTask(task) && !task->stopped && !task->suspended_tso) {
313 task->next = cap->spare_workers;
314 cap->spare_workers = task;
316 // Bound tasks just float around attached to their TSOs.
318 releaseCapability_(cap);
320 RELEASE_LOCK(&cap->lock);
324 /* ----------------------------------------------------------------------------
325 * waitForReturnCapability( Task *task )
327 * Purpose: when an OS thread returns from an external call,
328 * it calls waitForReturnCapability() (via Schedule.resumeThread())
329 * to wait for permission to enter the RTS & communicate the
330 * result of the external call back to the Haskell thread that
333 * ------------------------------------------------------------------------- */
335 waitForReturnCapability (Capability **pCap,
336 Task *task UNUSED_IF_NOT_THREADS)
338 #if !defined(THREADED_RTS)
340 MainCapability.running_task = task;
341 task->cap = &MainCapability;
342 *pCap = &MainCapability;
345 Capability *cap = *pCap;
348 // Try last_free_capability first
349 cap = last_free_capability;
350 if (!cap->running_task) {
352 // otherwise, search for a free capability
353 for (i = 0; i < n_capabilities; i++) {
354 cap = &capabilities[i];
355 if (!cap->running_task) {
359 // Can't find a free one, use last_free_capability.
360 cap = last_free_capability;
363 // record the Capability as the one this Task is now assocated with.
367 ASSERT(task->cap == cap);
370 ACQUIRE_LOCK(&cap->lock);
373 sched_belch("returning; I want capability %d", cap->no));
375 if (!cap->running_task) {
376 // It's free; just grab it
377 cap->running_task = task;
378 RELEASE_LOCK(&cap->lock);
380 newReturningTask(cap,task);
381 RELEASE_LOCK(&cap->lock);
384 ACQUIRE_LOCK(&task->lock);
385 // task->lock held, cap->lock not held
386 if (!task->wakeup) waitCondition(&task->cond, &task->lock);
388 task->wakeup = rtsFalse;
389 RELEASE_LOCK(&task->lock);
391 // now check whether we should wake up...
392 ACQUIRE_LOCK(&cap->lock);
393 if (cap->running_task == NULL) {
394 if (cap->returning_tasks_hd != task) {
395 giveCapabilityToTask(cap,cap->returning_tasks_hd);
396 RELEASE_LOCK(&cap->lock);
399 cap->running_task = task;
400 popReturningTask(cap);
401 RELEASE_LOCK(&cap->lock);
404 RELEASE_LOCK(&cap->lock);
409 ASSERT_CAPABILITY_INVARIANTS(cap,task);
412 sched_belch("returning; got capability %d", cap->no));
418 #if defined(THREADED_RTS)
419 /* ----------------------------------------------------------------------------
421 * ------------------------------------------------------------------------- */
424 yieldCapability (Capability** pCap, Task *task)
426 Capability *cap = *pCap;
428 // The fast path; no locking
429 if ( cap->returning_tasks_hd == NULL && anyWorkForMe(cap,task) )
432 while ( cap->returning_tasks_hd != NULL || !anyWorkForMe(cap,task) ) {
433 IF_DEBUG(scheduler, sched_belch("giving up capability %d", cap->no));
435 // We must now release the capability and wait to be woken up
437 releaseCapabilityAndQueueWorker(cap);
440 ACQUIRE_LOCK(&task->lock);
441 // task->lock held, cap->lock not held
442 if (!task->wakeup) waitCondition(&task->cond, &task->lock);
444 task->wakeup = rtsFalse;
445 RELEASE_LOCK(&task->lock);
447 IF_DEBUG(scheduler, sched_belch("woken up on capability %d", cap->no));
448 ACQUIRE_LOCK(&cap->lock);
449 if (cap->running_task != NULL) {
450 RELEASE_LOCK(&cap->lock);
454 if (task->tso == NULL) {
455 ASSERT(cap->spare_workers != NULL);
456 // if we're not at the front of the queue, release it
457 // again. This is unlikely to happen.
458 if (cap->spare_workers != task) {
459 giveCapabilityToTask(cap,cap->spare_workers);
460 RELEASE_LOCK(&cap->lock);
463 cap->spare_workers = task->next;
466 cap->running_task = task;
467 RELEASE_LOCK(&cap->lock);
471 IF_DEBUG(scheduler, sched_belch("got capability %d", cap->no));
472 ASSERT(cap->running_task == task);
477 ASSERT_CAPABILITY_INVARIANTS(cap,task);
482 /* ----------------------------------------------------------------------------
485 * Used to indicate that the interrupted flag is now set, or some
486 * other global condition that might require waking up a Task on each
488 * ------------------------------------------------------------------------- */
491 prodCapabilities(rtsBool all)
497 for (i=0; i < n_capabilities; i++) {
498 cap = &capabilities[i];
499 ACQUIRE_LOCK(&cap->lock);
500 if (!cap->running_task) {
501 if (cap->spare_workers) {
502 task = cap->spare_workers;
503 ASSERT(!task->stopped);
504 giveCapabilityToTask(cap,task);
506 RELEASE_LOCK(&cap->lock);
511 RELEASE_LOCK(&cap->lock);
516 prodAllCapabilities (void)
518 prodCapabilities(rtsTrue);
521 /* ----------------------------------------------------------------------------
524 * Like prodAllCapabilities, but we only require a single Task to wake
525 * up in order to service some global event, such as checking for
526 * deadlock after some idle time has passed.
527 * ------------------------------------------------------------------------- */
530 prodOneCapability (void)
532 prodCapabilities(rtsFalse);
535 /* ----------------------------------------------------------------------------
538 * At shutdown time, we want to let everything exit as cleanly as
539 * possible. For each capability, we let its run queue drain, and
540 * allow the workers to stop.
542 * This function should be called when interrupted and
543 * shutting_down_scheduler = rtsTrue, thus any worker that wakes up
544 * will exit the scheduler and call taskStop(), and any bound thread
545 * that wakes up will return to its caller. Runnable threads are
548 * ------------------------------------------------------------------------- */
551 shutdownCapability (Capability *cap, Task *task)
555 ASSERT(interrupted && shutting_down_scheduler);
559 for (i = 0; i < 50; i++) {
560 IF_DEBUG(scheduler, sched_belch("shutting down capability %d, attempt %d", cap->no, i));
561 ACQUIRE_LOCK(&cap->lock);
562 if (cap->running_task) {
563 RELEASE_LOCK(&cap->lock);
564 IF_DEBUG(scheduler, sched_belch("not owner, yielding"));
568 cap->running_task = task;
569 if (!emptyRunQueue(cap) || cap->spare_workers) {
570 IF_DEBUG(scheduler, sched_belch("runnable threads or workers still alive, yielding"));
571 releaseCapability_(cap); // this will wake up a worker
572 RELEASE_LOCK(&cap->lock);
576 IF_DEBUG(scheduler, sched_belch("capability %d is stopped.", cap->no));
577 RELEASE_LOCK(&cap->lock);
580 // we now have the Capability, its run queue and spare workers
581 // list are both empty.
584 /* ----------------------------------------------------------------------------
587 * Attempt to gain control of a Capability if it is free.
589 * ------------------------------------------------------------------------- */
592 tryGrabCapability (Capability *cap, Task *task)
594 if (cap->running_task != NULL) return rtsFalse;
595 ACQUIRE_LOCK(&cap->lock);
596 if (cap->running_task != NULL) {
597 RELEASE_LOCK(&cap->lock);
601 cap->running_task = task;
602 RELEASE_LOCK(&cap->lock);
607 #endif /* THREADED_RTS */