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 to do good work within
  38    the RTS. Used by Task.c (only) to determine whether or not
  39    new worker threads needs to be created (when an external call
  40    is made).
  41  */
  42 extern nat rts_n_waiting_workers; /* used by Task.c to determine */
  43
  44 extern void grabReturnCapability(Mutex* pMutex, Capability** pCap);
  45 extern void yieldToReturningWorker(Mutex* pMutex, Capability** pCap);
  46 extern void waitForWorkCapability(Mutex* pMutex, Capability** pCap, rtsBool runnable);
  47
  48 static inline nat getFreeCapabilities (void)
  49 {
  50   return rts_n_free_capabilities;
  51 }
  52
  53 static inline rtsBool noCapabilities (void)
  54 {
  55   return (rts_n_free_capabilities == 0);
  56 }
  57
  58 static inline rtsBool allFreeCapabilities (void)
  59 {
  60 # if defined(SMP)
  61   return (rts_n_free_capabilities == RtsFlags.ParFlags.nNodes);
  62 # else
  63   return (rts_n_free_capabilities == 1);
  64 # endif
  65 }
  66
  67 #endif /* RTS_SUPPORTS_THREADS */
  68
  69 #endif /* __CAPABILITY_H__ */