ghc/rts/Capability.h

   1 /* ---------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 2001
   4  *
   5  * Capabilities
   6  *
   7  * The notion of a capability is used when operating in multi-threaded
   8  * environments (which the SMP and Threads builds of the RTS do), to
   9  * hold all the state an OS thread/task needs to run Haskell code:
  10  * its STG registers, a pointer to its  TSO, a nursery etc. During
  11  * STG execution, a pointer to the capabilitity is kept in a
  12  * register (BaseReg).
  13  *
  14  * Only in an SMP build will there be multiple capabilities, the threaded
  15  * RTS and other non-threaded builds, there is one global capability,
  16  * namely MainRegTable.
  17  *
  18  * This header file contains the functions for working with capabilities.
  19  * (the main, and only, consumer of this interface is the scheduler).
  20  *
  21  * --------------------------------------------------------------------------*/
  22 #ifndef __CAPABILITY_H__
  23 #define __CAPABILITY_H__
  24 #include "RtsFlags.h"
  25 /* ToDo: assume that RtsFlags.h has been included at usage sites of Capability.h? */
  26
  27 #if !defined(SMP)
  28 extern Capability MainCapability;
  29 #endif
  30
  31 extern void initCapabilities(void);
  32 extern void grabCapability(Capability** pCap);
  33 extern void releaseCapability(Capability* cap);
  34
  35 extern nat rts_n_free_capabilities;
  36 #if defined(RTS_SUPPORTS_THREADS)
  37 /* number of worker threads waiting for a return capability
  38  */
  39 extern nat rts_n_waiting_workers;
  40
  41 extern void grabReturnCapability(Mutex* pMutex, Capability** pCap);
  42 extern void yieldToReturningWorker(Mutex* pMutex, Capability** pCap, Condition *pThreadCond);
  43 extern void waitForWorkCapability(Mutex* pMutex, Capability** pCap, Condition *pThreadCond);
  44 extern void passCapability(Mutex* pMutex, Capability* cap, Condition *pTargetThreadCond);
  45 extern void passCapabilityToWorker(Mutex* pMutex, Capability* cap);
  46
  47 static inline rtsBool needToYieldToReturningWorker(void)
  48 {
  49         return rts_n_waiting_workers > 0;
  50 }
  51
  52 static inline nat getFreeCapabilities (void)
  53 {
  54   return rts_n_free_capabilities;
  55 }
  56
  57 static inline rtsBool noCapabilities (void)
  58 {
  59   return (rts_n_free_capabilities == 0);
  60 }
  61
  62 static inline rtsBool allFreeCapabilities (void)
  63 {
  64 # if defined(SMP)
  65   return (rts_n_free_capabilities == RtsFlags.ParFlags.nNodes);
  66 # else
  67   return (rts_n_free_capabilities == 1);
  68 # endif
  69 }
  70
  71 #endif /* RTS_SUPPORTS_THREADS */
  72
  73 #endif /* __CAPABILITY_H__ */