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, the threaded
14 * RTS and other non-threaded builds, there is one global capability,
15 * namely MainRegTable.
17 * --------------------------------------------------------------------------*/
18 #include "PosixSource.h"
22 #include "Capability.h"
25 Capability MainCapability; /* for non-SMP, we have one global capability */
28 nat rts_n_free_capabilities;
30 #if defined(RTS_SUPPORTS_THREADS)
31 /* returning_worker_cond: when a worker thread returns from executing an
32 * external call, it needs to wait for an RTS Capability before passing
33 * on the result of the call to the Haskell thread that made it.
35 * returning_worker_cond is signalled in Capability.releaseCapability().
38 Condition returning_worker_cond = INIT_COND_VAR;
41 * To avoid starvation of threads blocked on worker_thread_cond,
42 * the task(s) that enter the Scheduler will check to see whether
43 * there are one or more worker threads blocked waiting on
44 * returning_worker_cond.
46 * Locks needed: sched_mutex
48 nat rts_n_waiting_workers = 0;
53 initCapability( Capability *cap )
55 cap->f.stgChk0 = (F_)__stg_chk_0;
56 cap->f.stgChk1 = (F_)__stg_chk_1;
57 cap->f.stgGCEnter1 = (F_)__stg_gc_enter_1;
58 cap->f.stgUpdatePAP = (F_)__stg_update_PAP;
62 static void initCapabilities_(nat n);
70 #if defined(RTS_SUPPORTS_THREADS)
71 initCondition(&returning_worker_cond);
75 initCapabilities_(RtsFlags.ParFlags.nNodes);
77 initCapability(&MainCapability);
78 rts_n_free_capabilities = 1;
84 /* Free capability list.
85 * Locks required: sched_mutex.
88 static Capability *free_capabilities; /* Available capabilities for running threads */
91 void grabCapability(Capability** cap)
94 rts_n_free_capabilities = 0;
95 *cap = &MainCapability;
97 *cap = free_capabilities;
98 free_capabilities = (*cap)->link;
99 rts_n_free_capabilities--;
104 * Function: releaseCapability(Capability*)
106 * Purpose: Letting go of a capability.
108 * Pre-condition: sched_mutex is assumed held by current thread.
111 void releaseCapability(Capability* cap
118 cap->link = free_capabilities;
119 free_capabilities = cap;
120 rts_n_free_capabilities++;
122 rts_n_free_capabilities = 1;
125 #if defined(RTS_SUPPORTS_THREADS)
126 /* Check to see whether a worker thread can be given
127 the go-ahead to return the result of an external call..*/
128 if (rts_n_waiting_workers > 0) {
129 /* Decrement the counter here to avoid livelock where the
130 * thread that is yielding its capability will repeatedly
131 * signal returning_worker_cond.
133 rts_n_waiting_workers--;
134 signalCondition(&returning_worker_cond);
135 } else if ( !EMPTY_RUN_QUEUE() ) {
136 /* Signal that work is available */
137 signalCondition(&thread_ready_cond);
143 #if defined(RTS_SUPPORTS_THREADS)
145 * When a native thread has completed the execution of an external
146 * call, it needs to communicate the result back. This is done
149 * - in resumeThread(), the thread calls grabReturnCapability().
150 * - If no capabilities are readily available, grabReturnCapability()
151 * increments a counter rts_n_waiting_workers, and blocks
152 * waiting for the condition returning_worker_cond to become
154 * - upon entry to the Scheduler, a worker thread checks the
155 * value of rts_n_waiting_workers. If > 0, the worker thread
156 * will yield its capability to let a returning worker thread
157 * proceed with returning its result -- this is done via
159 * - the worker thread that yielded its capability then tries
160 * to re-grab a capability and re-enter the Scheduler.
164 * Function: grabReturnCapability(Capability**)
166 * Purpose: when an OS thread returns from an external call,
167 * it calls grabReturningCapability() (via Schedule.resumeThread())
168 * to wait for permissions to enter the RTS & communicate the
169 * result of the ext. call back to the Haskell thread that
172 * Pre-condition: sched_mutex isn't held.
173 * Post-condition: sched_mutex is held and a capability has
174 * been assigned to the worker thread.
177 grabReturnCapability(Capability** pCap)
180 fprintf(stderr,"worker (%ld): returning, waiting for sched. lock.\n", osThreadId()));
181 ACQUIRE_LOCK(&sched_mutex);
182 rts_n_waiting_workers++;
184 fprintf(stderr,"worker (%ld): returning; workers waiting: %d\n",
185 osThreadId(), rts_n_waiting_workers));
186 while ( noCapabilities() ) {
187 waitCondition(&returning_worker_cond, &sched_mutex);
190 grabCapability(pCap);
195 * Function: yieldCapability(Capability**)
197 * Purpose: when, upon entry to the Scheduler, an OS worker thread
198 * spots that one or more threads are blocked waiting for
199 * permission to return back their result, it gives up
202 * Pre-condition: sched_mutex is held and the thread possesses
204 * Post-condition: sched_mutex isn't held and the Capability has
208 yieldCapability(Capability* cap)
211 fprintf(stderr,"worker thread (%ld): giving up RTS token\n", osThreadId()));
212 releaseCapability(cap);
213 RELEASE_LOCK(&sched_mutex);
215 /* At this point, sched_mutex has been given up & we've
216 * forced a thread context switch. Guaranteed to be
217 * enough for the signalled worker thread to race
223 #endif /* RTS_SUPPORTS_THREADS */
227 * Function: initCapabilities_(nat)
229 * Purpose: upon startup, allocate and fill in table
230 * holding 'n' Capabilities. Only for SMP, since
231 * it is the only build that supports multiple
232 * capabilities within the RTS.
234 * Pre-condition: sched_mutex is held.
238 initCapabilities_(nat n)
241 Capability *cap, *prev;
244 for (i = 0; i < n; i++) {
245 cap = stgMallocBytes(sizeof(Capability), "initCapabilities");
250 free_capabilities = cap;
251 rts_n_free_capabilities = n;
252 IF_DEBUG(scheduler,fprintf(stderr,"scheduler: Allocated %d capabilities\n", n_free_capabilities););