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: reasonable size,
  55    topBound consistent, space pointer, space accessible to us.
  56
  57    NB. This is safe to use only (a) on a spark pool owned by the
  58    current thread, or (b) when there's only one thread running, or no
  59    stealing going on (e.g. during GC).
  60 */
  61 #define ASSERT_SPARK_POOL_INVARIANTS(p)         \
  62   ASSERT((p)->size > 0);                        \
  63   ASSERT((p)->topBound <= (p)->top);            \
  64   ASSERT((p)->elements != NULL);                \
  65   ASSERT(*((p)->elements) || 1);                \
  66   ASSERT(*((p)->elements - 1  + ((p)->size)) || 1);
  67
  68 // No: it is possible that top > bottom when using reclaimSpark()
  69 //  ASSERT((p)->bottom >= (p)->top);
  70 //  ASSERT((p)->size > (p)->bottom - (p)->top);
  71
  72 // Initialisation
  73 void initSparkPools (void);
  74
  75 // Take a spark from the "write" end of the pool.  Can be called
  76 // by the pool owner only.
  77 StgClosure* reclaimSpark(SparkPool *pool);
  78
  79 // Returns True if the spark pool is empty (can give a false positive
  80 // if the pool is almost empty).
  81 rtsBool looksEmpty(SparkPool* deque);
  82
  83 StgClosure * tryStealSpark     (Capability *cap);
  84 void         freeSparkPool     (SparkPool *pool);
  85 void         createSparkThread (Capability *cap);
  86 void         traverseSparkQueue(evac_fn evac, void *user, Capability *cap);
  87 void         pruneSparkQueue   (evac_fn evac, void *user, Capability *cap);
  88
  89 INLINE_HEADER void discardSparks  (SparkPool *pool);
  90 INLINE_HEADER nat  sparkPoolSize  (SparkPool *pool);
  91 #endif
  92
  93 /* -----------------------------------------------------------------------------
  94  * PRIVATE below here
  95  * -------------------------------------------------------------------------- */
  96
  97 #if defined(PARALLEL_HASKELL) || defined(THREADED_RTS)
  98
  99 INLINE_HEADER rtsBool
 100 emptySparkPool (SparkPool *pool)
 101 { return looksEmpty(pool); }
 102
 103 INLINE_HEADER nat
 104 sparkPoolSize (SparkPool *pool)
 105 { return (pool->bottom - pool->top); }
 106
 107 INLINE_HEADER void
 108 discardSparks (SparkPool *pool)
 109 {
 110     pool->top = pool->topBound = pool->bottom = 0;
 111 }
 112
 113 #endif
 114
 115 #endif /* SPARKS_H */