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