From: sof <unknown>
Date: Thu, 14 Feb 2002 18:20:37 +0000 (+0000)
Subject: [project @ 2002-02-14 18:20:37 by sof]
X-Git-Tag: Approximately_9120_patches~41
X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=f7e5d55c32e6b21f21d88b582e3ba9ccd39aad8a

[project @ 2002-02-14 18:20:37 by sof]
more comments
---

diff --git a/ghc/rts/Capability.c b/ghc/rts/Capability.c
index e979507..6f4a945 100644
--- a/ghc/rts/Capability.c
+++ b/ghc/rts/Capability.c
@@ -6,13 +6,13 @@
  *
  * A Capability represent the token required to execute STG code,
  * and all the state an OS thread/task needs to run Haskell code:
- * its STG registers, a pointer to its  TSO, a nursery etc. During
+ * its STG registers, a pointer to its TSO, a nursery etc. During
  * STG execution, a pointer to the capabilitity is kept in a
  * register (BaseReg).
  *
- * Only in an SMP build will there be multiple capabilities, the threaded
- * RTS and other non-threaded builds, there is one global capability,
- * namely MainRegTable.
+ * Only in an SMP build will there be multiple capabilities, for
+ * the threaded RTS and other non-threaded builds, there is only
+ * one global capability, namely MainCapability.
  * 
  * --------------------------------------------------------------------------*/
 #include "PosixSource.h"
@@ -58,11 +58,18 @@ initCapability( Capability *cap )
     cap->f.stgUpdatePAP    = (F_)__stg_update_PAP;
 }
 
-#ifdef SMP
+#if defined(SMP)
 static void initCapabilities_(nat n);
 #endif
 
 /* 
+ * Function:  initCapabilities()
+ *
+ * Purpose:   set up the Capability handling. For the SMP build,
+ *            we keep a table of them, the size of which is
+ *            controlled by the user via the RTS flag RtsFlags.ParFlags.nNodes
+ *
+ * Pre-conditions: no locks assumed held.
  */
 void
 initCapabilities()
@@ -88,6 +95,20 @@ initCapabilities()
 static Capability *free_capabilities; /* Available capabilities for running threads */
 #endif
 
+/*
+ * Function:  grabCapability(Capability**)
+ * 
+ * Purpose:   the act of grabbing a capability is easy; just 
+ *            remove one from the free capabilities list (which
+ *            may just have one entry). In threaded builds, worker
+ *            threads are prevented from doing so willy-nilly
+ *            through the use of the sched_mutex lock along with
+ *            condition variables thread_ready_cond and
+ *            returning_worker_cond.
+ *
+ * Pre-condition:  sched_mutex is held (in threaded builds only).
+ *
+ */ 
 void grabCapability(Capability** cap)
 {
 #if !defined(SMP)