rts/STM.h

   1 /*----------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 1998-2004
   4  *
   5  * STM interface definition
   6  *
   7  *----------------------------------------------------------------------
   8
   9   STM.h defines the C-level interface to the STM.
  10
  11   The design follows that of the PPoPP 2005 paper "Composable memory
  12   transactions" extended to include fine-grained locking of TVars.
  13
  14   Three different implementations can be built.  In overview:
  15
  16   STM_UNIPROC  -- no locking at all: not safe for concurrent invocations
  17
  18   STM_CG_LOCK  -- coarse-grained locking : a single mutex protects all
  19                   TVars
  20
  21   STM_FG_LOCKS -- per-TVar exclusion : each TVar can be owned by at
  22                   most one TRec at any time.  This allows dynamically
  23                   non-conflicting transactions to commit in parallel.
  24                   The implementation treats reads optimisitcally --
  25                   extra versioning information is retained in the
  26                   saw_update_by field of the TVars so that they do not
  27                   need to be locked for reading.
  28
  29   STM.C contains more details about the locking schemes used.
  30
  31 */
  32
  33 #ifndef STM_H
  34 #define STM_H
  35
  36 #ifdef THREADED_RTS
  37 //#define STM_CG_LOCK
  38 #define STM_FG_LOCKS
  39 #else
  40 #define STM_UNIPROC
  41 #endif
  42
  43 BEGIN_RTS_PRIVATE
  44
  45 /*----------------------------------------------------------------------
  46
  47    GC interaction
  48    --------------
  49 */
  50
  51 void stmPreGCHook(void);
  52
  53 /*----------------------------------------------------------------------
  54
  55    Transaction context management
  56    ------------------------------
  57
  58 */
  59
  60 /* Create and enter a new transaction context */
  61
  62 StgTRecHeader *stmStartTransaction(Capability *cap, StgTRecHeader *outer);
  63 StgTRecHeader *stmStartNestedTransaction(Capability *cap, StgTRecHeader *outer
  64 );
  65
  66 /*
  67  * Roll back the current transatcion context.  NB: if this is a nested tx
  68  * then we merge its read set into its parents.  This is because a change
  69  * to that read set could change whether or not the tx should abort.
  70  */
  71
  72 void stmAbortTransaction(Capability *cap, StgTRecHeader *trec);
  73 void stmFreeAbortedTRec(Capability *cap, StgTRecHeader *trec);
  74
  75 /*
  76  * Ensure that a subsequent commit / validation will fail.  We use this
  77  * in our current handling of transactions that may have become invalid
  78  * and started looping.  We strip their stack back to the ATOMICALLY_FRAME,
  79  * and, when the thread is next scheduled, discover it to be invalid and
  80  * re-execute it.  However, we need to force the transaction to stay invalid
  81  * in case other threads' updates make it valid in the mean time.
  82  */
  83
  84 void stmCondemnTransaction(Capability *cap, StgTRecHeader *trec);
  85
  86 /*
  87  * Return the trec within which the specified trec was created (not
  88  * valid if trec==NO_TREC).
  89  */
  90
  91 StgTRecHeader *stmGetEnclosingTRec(StgTRecHeader *trec);
  92
  93 /*----------------------------------------------------------------------
  94
  95    Validation
  96    ----------
  97
  98   Test whether the specified transaction record, and all those within which
  99   it is nested, are still valid.
 100
 101   Note: the caller can assume that once stmValidateTransaction has
 102   returned FALSE for a given trec then that transaction will never
 103   again be valid -- we rely on this in Schedule.c when kicking invalid
 104   threads at GC (in case they are stuck looping)
 105 */
 106
 107 StgBool stmValidateNestOfTransactions(StgTRecHeader *trec);
 108
 109 /*----------------------------------------------------------------------
 110
 111    Commit/wait/rewait operations
 112    -----------------------------
 113
 114    These four operations return boolean results which should be interpreted
 115    as follows:
 116
 117    true  => The transaction record was definitely valid
 118
 119    false => The transaction record may not have been valid
 120
 121    Note that, for nested operations, validity here is solely in terms
 122    of the specified trec: it does not say whether those that it may be
 123    nested are themselves valid.  Callers can check this with
 124    stmValidateNestOfTransactions.
 125
 126    The user of the STM should ensure that it is always safe to assume that a
 127    transaction context is not valid when in fact it is (i.e. to return false in
 128    place of true, with side-effects as defined below).  This may cause
 129    needless retries of transactions (in the case of validate and commit), or it
 130    may cause needless spinning instead of blocking (in the case of wait and
 131    rewait).
 132
 133    In defining the behaviour of wait and rewait we distinguish between two
 134    different aspects of a thread's runnability:
 135
 136     - We say that a thread is "blocked" when it is not running or
 137       runnable as far as the scheduler is concerned.
 138
 139     - We say that a thread is "waiting" when its StgTRecHeader is linked on an
 140       tvar's wait queue.
 141
 142    Considering only STM operations, (blocked) => (waiting).  The user of the STM
 143    should ensure that they are prepared for threads to be unblocked spuriously
 144    and for wait/reWait to return false even when the previous transaction context
 145    is actually still valid.
 146 */
 147
 148 /*
 149  * Fill in the trec's list of invariants that might be violated by the current
 150  * transaction.
 151  */
 152
 153 StgInvariantCheckQueue *stmGetInvariantsToCheck(Capability *cap,
 154                                                 StgTRecHeader *trec);
 155
 156 void stmAddInvariantToCheck(Capability *cap,
 157                             StgTRecHeader *trec,
 158                             StgClosure *code);
 159
 160 /*
 161  * Test whether the current transaction context is valid and, if so,
 162  * commit its memory accesses to the heap.  stmCommitTransaction must
 163  * unblock any threads which are waiting on tvars that updates have
 164  * been committed to.
 165  */
 166
 167 StgBool stmCommitTransaction(Capability *cap, StgTRecHeader *trec);
 168 StgBool stmCommitNestedTransaction(Capability *cap, StgTRecHeader *trec);
 169
 170 /*
 171  * Test whether the current transaction context is valid and, if so,
 172  * start the thread waiting for updates to any of the tvars it has
 173  * ready from and mark it as blocked.  It is an error to call stmWait
 174  * if the thread is already waiting.
 175  */
 176
 177 StgBool stmWait(Capability *cap, StgTSO *tso, StgTRecHeader *trec);
 178
 179 void stmWaitUnlock(Capability *cap, StgTRecHeader *trec);
 180
 181 /*
 182  * Test whether the current transaction context is valid and, if so,
 183  * leave the thread waiting and mark it as blocked again.  If the
 184  * transaction context is no longer valid then stop the thread waiting
 185  * and leave it as unblocked.  It is an error to call stmReWait if the
 186  * thread is not waiting.
 187  */
 188
 189 StgBool stmReWait(Capability *cap, StgTSO *tso);
 190
 191 /*----------------------------------------------------------------------
 192
 193    TVar management operations
 194    --------------------------
 195 */
 196
 197 StgTVar *stmNewTVar(Capability *cap, StgClosure *new_value);
 198
 199 /*----------------------------------------------------------------------
 200
 201    Data access operations
 202    ----------------------
 203 */
 204
 205 /*
 206  * Return the logical contents of 'tvar' within the context of the
 207  * thread's current transaction.
 208  */
 209
 210 StgClosure *stmReadTVar(Capability *cap,
 211                         StgTRecHeader *trec,
 212                         StgTVar *tvar);
 213
 214 /* Update the logical contents of 'tvar' within the context of the
 215  * thread's current transaction.
 216  */
 217
 218 void stmWriteTVar(Capability *cap,
 219                   StgTRecHeader *trec,
 220                   StgTVar *tvar,
 221                   StgClosure *new_value);
 222
 223 /*----------------------------------------------------------------------*/
 224
 225 /* NULLs */
 226
 227 #define END_STM_WATCH_QUEUE ((StgTVarWatchQueue *)(void *)&stg_END_STM_WATCH_QUEUE_closure)
 228 #define END_INVARIANT_CHECK_QUEUE ((StgInvariantCheckQueue *)(void *)&stg_END_INVARIANT_CHECK_QUEUE_closure)
 229 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
 230
 231 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
 232
 233 /*----------------------------------------------------------------------*/
 234
 235 END_RTS_PRIVATE
 236
 237 #endif /* STM_H */
 238