rts/Sparks.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 2000-2006
   4  *
   5  * Sparking support for GRAN, PAR and THREADED_RTS versions of the RTS.
   6  *
   7  * ---------------------------------------------------------------------------*/
   8
   9 #ifndef SPARKS_H
  10 #define SPARKS_H
  11
  12 #if defined(PARALLEL_HASKELL)
  13 #error Sparks.c using new internal structure, needs major overhaul!
  14 #endif
  15
  16 /* typedef for SparkPool in RtsTypes.h */
  17
  18 #if defined(THREADED_RTS)
  19
  20 /* Spark pools: used to store pending sparks
  21  *  (THREADED_RTS & PARALLEL_HASKELL only)
  22  * Implementation uses a DeQue to enable concurrent read accesses at
  23  * the top end.
  24  */
  25 typedef struct  SparkPool_ {
  26   /* Size of elements array. Used for modulo calculation: we round up
  27      to powers of 2 and use the dyadic log (modulo == bitwise &) */
  28   StgWord size;
  29   StgWord moduloSize; /* bitmask for modulo */
  30
  31   /* top, index where multiple readers steal() (protected by a cas) */
  32   volatile StgWord top;
  33
  34   /* bottom, index of next free place where one writer can push
  35      elements. This happens unsynchronised. */
  36   volatile StgWord bottom;
  37   /* both position indices are continuously incremented, and used as
  38      an index modulo the current array size. */
  39
  40   /* lower bound on the current top value. This is an internal
  41      optimisation to avoid unnecessarily accessing the top field
  42      inside pushBottom */
  43   volatile StgWord topBound;
  44
  45   /* The elements array */
  46   StgClosurePtr* elements;
  47   /*  Please note: the dataspace cannot follow the admin fields
  48       immediately, as it should be possible to enlarge it without
  49       disposing the old one automatically (as realloc would)! */
  50
  51 } SparkPool;
  52
  53
  54 /* INVARIANTS, in this order: bottom/top consistent, reasonable size,
  55    topBound consistent, space pointer, space accessible to us */
  56 #define ASSERT_SPARK_POOL_INVARIANTS(p)         \
  57   ASSERT((p)->bottom >= (p)->top);              \
  58   ASSERT((p)->size > 0);                        \
  59   ASSERT((p)->size > (p)->bottom - (p)->top);   \
  60   ASSERT((p)->topBound <= (p)->top);            \
  61   ASSERT((p)->elements != NULL);                \
  62   ASSERT(*((p)->elements) || 1);                \
  63   ASSERT(*((p)->elements - 1  + ((p)->size)) || 1);
  64
  65 // Initialisation
  66 void initSparkPools (void);
  67
  68 // Take a spark from the "write" end of the pool.  Can be called
  69 // by the pool owner only.
  70 StgClosure* reclaimSpark(SparkPool *pool);
  71
  72 // Returns True if the spark pool is empty (can give a false positive
  73 // if the pool is almost empty).
  74 rtsBool looksEmpty(SparkPool* deque);
  75
  76 StgClosure * tryStealSpark     (Capability *cap);
  77 void         freeSparkPool     (SparkPool *pool);
  78 void         createSparkThread (Capability *cap);
  79 void         traverseSparkQueue(evac_fn evac, void *user, Capability *cap);
  80 void         pruneSparkQueue   (evac_fn evac, void *user, Capability *cap);
  81
  82 INLINE_HEADER void discardSparks  (SparkPool *pool);
  83 INLINE_HEADER nat  sparkPoolSize  (SparkPool *pool);
  84 #endif
  85
  86 /* -----------------------------------------------------------------------------
  87  * PRIVATE below here
  88  * -------------------------------------------------------------------------- */
  89
  90 #if defined(PARALLEL_HASKELL) || defined(THREADED_RTS)
  91
  92 INLINE_HEADER rtsBool
  93 emptySparkPool (SparkPool *pool)
  94 { return looksEmpty(pool); }
  95
  96 INLINE_HEADER nat
  97 sparkPoolSize (SparkPool *pool)
  98 { return (pool->bottom - pool->top); }
  99
 100 INLINE_HEADER void
 101 discardSparks (SparkPool *pool)
 102 {
 103     pool->top = pool->topBound = pool->bottom = 0;
 104 }
 105
 106 #endif
 107
 108 #endif /* SPARKS_H */