1 /* ---------------------------------------------------------------------------
3 * (c) The GHC Team, 2002
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
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 * --------------------------------------------------------------------------*/
18 #include "PosixSource.h"
21 #include "OSThreads.h"
22 #include "Capability.h"
23 #include "Schedule.h" /* to get at EMPTY_RUN_QUEUE() */
26 Capability MainCapability; /* for non-SMP, we have one global capability */
29 nat rts_n_free_capabilities;
31 #if defined(RTS_SUPPORTS_THREADS)
32 /* returning_worker_cond: when a worker thread returns from executing an
33 * external call, it needs to wait for an RTS Capability before passing
34 * on the result of the call to the Haskell thread that made it.
36 * returning_worker_cond is signalled in Capability.releaseCapability().
39 Condition returning_worker_cond = INIT_COND_VAR;
42 * To avoid starvation of threads blocked on worker_thread_cond,
43 * the task(s) that enter the Scheduler will check to see whether
44 * there are one or more worker threads blocked waiting on
45 * returning_worker_cond.
47 static nat rts_n_waiting_workers = 0;
49 /* thread_ready_cond: when signalled, a thread has become runnable for a
52 * In the non-SMP case, it also implies that the thread that is woken up has
53 * exclusive access to the RTS and all its data structures (that are not
54 * locked by the Scheduler's mutex).
56 * thread_ready_cond is signalled whenever COND_NO_THREADS_READY doesn't hold.
59 Condition thread_ready_cond = INIT_COND_VAR;
61 /* For documentation purposes only */
62 #define COND_NO_THREADS_READY() (noCapabilities() || EMPTY_RUN_QUEUE())
66 * To be able to make an informed decision about whether or not
67 * to create a new task when making an external call, keep track of
68 * the number of tasks currently blocked waiting on thread_ready_cond.
69 * (if > 0 => no need for a new task, just unblock an existing one).
71 * waitForWorkCapability() takes care of keeping it up-to-date;
72 * Task.startTask() uses its current value.
74 nat rts_n_waiting_tasks = 0;
77 /* -----------------------------------------------------------------------------
79 -------------------------------------------------------------------------- */
82 initCapability( Capability *cap )
84 cap->f.stgChk0 = (F_)__stg_chk_0;
85 cap->f.stgChk1 = (F_)__stg_chk_1;
86 cap->f.stgGCEnter1 = (F_)__stg_gc_enter_1;
87 cap->f.stgUpdatePAP = (F_)__stg_update_PAP;
91 static void initCapabilities_(nat n);
95 * Function: initCapabilities()
97 * Purpose: set up the Capability handling. For the SMP build,
98 * we keep a table of them, the size of which is
99 * controlled by the user via the RTS flag RtsFlags.ParFlags.nNodes
101 * Pre-conditions: no locks assumed held.
106 #if defined(RTS_SUPPORTS_THREADS)
107 initCondition(&returning_worker_cond);
108 initCondition(&thread_ready_cond);
112 initCapabilities_(RtsFlags.ParFlags.nNodes);
114 initCapability(&MainCapability);
115 rts_n_free_capabilities = 1;
122 /* Free capability list. */
123 static Capability *free_capabilities; /* Available capabilities for running threads */
126 /* -----------------------------------------------------------------------------
127 Acquiring capabilities
128 -------------------------------------------------------------------------- */
131 * Function: grabCapability(Capability**)
133 * Purpose: the act of grabbing a capability is easy; just
134 * remove one from the free capabilities list (which
135 * may just have one entry). In threaded builds, worker
136 * threads are prevented from doing so willy-nilly
137 * via the condition variables thread_ready_cond and
138 * returning_worker_cond.
141 void grabCapability(Capability** cap)
144 rts_n_free_capabilities = 0;
145 *cap = &MainCapability;
147 *cap = free_capabilities;
148 free_capabilities = (*cap)->link;
149 rts_n_free_capabilities--;
154 * Function: releaseCapability(Capability*)
156 * Purpose: Letting go of a capability. Causes a
157 * 'returning worker' thread or a 'waiting worker'
158 * to wake up, in that order.
161 void releaseCapability(Capability* cap
168 cap->link = free_capabilities;
169 free_capabilities = cap;
170 rts_n_free_capabilities++;
172 rts_n_free_capabilities = 1;
175 #if defined(RTS_SUPPORTS_THREADS)
176 /* Check to see whether a worker thread can be given
177 the go-ahead to return the result of an external call..*/
178 if (rts_n_waiting_workers > 0) {
179 /* Decrement the counter here to avoid livelock where the
180 * thread that is yielding its capability will repeatedly
181 * signal returning_worker_cond.
183 rts_n_waiting_workers--;
184 signalCondition(&returning_worker_cond);
185 } else if ( !EMPTY_RUN_QUEUE() ) {
186 /* Signal that work is available */
187 signalCondition(&thread_ready_cond);
193 #if defined(RTS_SUPPORTS_THREADS)
195 * When a native thread has completed the execution of an external
196 * call, it needs to communicate the result back. This is done
199 * - in resumeThread(), the thread calls grabReturnCapability().
200 * - If no capabilities are readily available, grabReturnCapability()
201 * increments a counter rts_n_waiting_workers, and blocks
202 * waiting for the condition returning_worker_cond to become
204 * - upon entry to the Scheduler, a worker thread checks the
205 * value of rts_n_waiting_workers. If > 0, the worker thread
206 * will yield its capability to let a returning worker thread
207 * proceed with returning its result -- this is done via
208 * yieldToReturningWorker().
209 * - the worker thread that yielded its capability then tries
210 * to re-grab a capability and re-enter the Scheduler.
214 * Function: grabReturnCapability(Capability**)
216 * Purpose: when an OS thread returns from an external call,
217 * it calls grabReturningCapability() (via Schedule.resumeThread())
218 * to wait for permissions to enter the RTS & communicate the
219 * result of the ext. call back to the Haskell thread that
222 * Pre-condition: pMutex isn't held.
223 * Post-condition: pMutex is held and a capability has
224 * been assigned to the worker thread.
227 grabReturnCapability(Mutex* pMutex, Capability** pCap)
230 fprintf(stderr,"worker (%ld): returning, waiting for lock.\n", osThreadId()));
231 ACQUIRE_LOCK(pMutex);
232 rts_n_waiting_workers++;
234 fprintf(stderr,"worker (%ld): returning; workers waiting: %d\n",
235 osThreadId(), rts_n_waiting_workers));
236 while ( noCapabilities() ) {
237 waitCondition(&returning_worker_cond, pMutex);
240 grabCapability(pCap);
245 /* -----------------------------------------------------------------------------
246 Yielding/waiting for capabilities
247 -------------------------------------------------------------------------- */
250 * Function: yieldToReturningWorker(Mutex*,Capability*)
252 * Purpose: when, upon entry to the Scheduler, an OS worker thread
253 * spots that one or more threads are blocked waiting for
254 * permission to return back their result, it gives up
257 * Pre-condition: pMutex is assumed held and the thread possesses
259 * Post-condition: pMutex isn't held and the Capability has
263 yieldToReturningWorker(Mutex* pMutex, Capability* cap)
265 if ( rts_n_waiting_workers > 0 && noCapabilities() ) {
267 fprintf(stderr,"worker thread (%ld): giving up RTS token\n", osThreadId()));
268 releaseCapability(cap);
269 RELEASE_LOCK(pMutex);
271 /* At this point, pMutex has been given up & we've
272 * forced a thread context switch. Guaranteed to be
273 * enough for the signalled worker thread to race
277 /* Re-grab the mutex */
278 ACQUIRE_LOCK(pMutex);
285 * Function: waitForWorkCapability(Mutex*, Capability**, rtsBool)
287 * Purpose: wait for a Capability to become available. In
288 * the process of doing so, updates the number
289 * of tasks currently blocked waiting for a capability/more
290 * work. That counter is used when deciding whether or
291 * not to create a new worker thread when an external
294 * Pre-condition: pMutex is held.
297 waitForWorkCapability(Mutex* pMutex, Capability** pCap, rtsBool runnable)
299 while ( noCapabilities() || (runnable && EMPTY_RUN_QUEUE()) ) {
300 rts_n_waiting_tasks++;
301 waitCondition(&thread_ready_cond, pMutex);
302 rts_n_waiting_tasks--;
304 grabCapability(pCap);
307 #endif /* RTS_SUPPORTS_THREADS */
311 * Function: initCapabilities_(nat)
313 * Purpose: upon startup, allocate and fill in table
314 * holding 'n' Capabilities. Only for SMP, since
315 * it is the only build that supports multiple
316 * capabilities within the RTS.
319 initCapabilities_(nat n)
322 Capability *cap, *prev;
325 for (i = 0; i < n; i++) {
326 cap = stgMallocBytes(sizeof(Capability), "initCapabilities");
331 free_capabilities = cap;
332 rts_n_free_capabilities = n;
333 IF_DEBUG(scheduler,fprintf(stderr,"scheduler: Allocated %d capabilities\n", n_free_capabilities););