-/*
- * Function: yieldCapability(Capability**)
- *
- * Purpose: when, upon entry to the Scheduler, an OS worker thread
- * spots that one or more threads are blocked waiting for
- * permission to return back their result, it gives up
- * its Capability.
+
+/* ----------------------------------------------------------------------------
+ * yieldCapability( Mutex* pMutex, Capability** pCap )
+ * ------------------------------------------------------------------------- */
+
+void
+yieldCapability( Capability** pCap )
+{
+ // Pre-condition: pMutex is assumed held, the current thread
+ // holds the capability pointed to by pCap.
+
+ if ( rts_n_waiting_workers > 0 || passingCapability || !ANY_WORK_TO_DO()) {
+ IF_DEBUG(scheduler,
+ if (rts_n_waiting_workers > 0) {
+ sched_belch("worker: giving up capability (returning wkr)");
+ } else if (passingCapability) {
+ sched_belch("worker: giving up capability (passing capability)");
+ } else {
+ sched_belch("worker: giving up capability (no threads to run)");
+ }
+ );
+ releaseCapability(*pCap);
+ *pCap = NULL;
+ }
+
+ // Post-condition: pMutex is assumed held, and either:
+ //
+ // 1. *pCap is NULL, in which case the current thread does not
+ // hold a capability now, or
+ // 2. *pCap is not NULL, in which case the current thread still
+ // holds the capability.
+ //
+ return;
+}
+
+
+/* ----------------------------------------------------------------------------
+ * waitForCapability( Mutex*, Capability**, Condition* )