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 #include "BeginPrivate.h"
  44
  45 /*----------------------------------------------------------------------
  46
  47    GC interaction
  48    --------------
  49 */
  50
  51 void stmPreGCHook(Capability *cap);
  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
  88    Validation
  89    ----------
  90
  91   Test whether the specified transaction record, and all those within which
  92   it is nested, are still valid.
  93
  94   Note: the caller can assume that once stmValidateTransaction has
  95   returned FALSE for a given trec then that transaction will never
  96   again be valid -- we rely on this in Schedule.c when kicking invalid
  97   threads at GC (in case they are stuck looping)
  98 */
  99
 100 StgBool stmValidateNestOfTransactions(StgTRecHeader *trec);
 101
 102 /*----------------------------------------------------------------------
 103
 104    Commit/wait/rewait operations
 105    -----------------------------
 106
 107    These four operations return boolean results which should be interpreted
 108    as follows:
 109
 110    true  => The transaction record was definitely valid
 111
 112    false => The transaction record may not have been valid
 113
 114    Note that, for nested operations, validity here is solely in terms
 115    of the specified trec: it does not say whether those that it may be
 116    nested are themselves valid.  Callers can check this with
 117    stmValidateNestOfTransactions.
 118
 119    The user of the STM should ensure that it is always safe to assume that a
 120    transaction context is not valid when in fact it is (i.e. to return false in
 121    place of true, with side-effects as defined below).  This may cause
 122    needless retries of transactions (in the case of validate and commit), or it
 123    may cause needless spinning instead of blocking (in the case of wait and
 124    rewait).
 125
 126    In defining the behaviour of wait and rewait we distinguish between two
 127    different aspects of a thread's runnability:
 128
 129     - We say that a thread is "blocked" when it is not running or
 130       runnable as far as the scheduler is concerned.
 131
 132     - We say that a thread is "waiting" when its StgTRecHeader is linked on an
 133       tvar's wait queue.
 134
 135    Considering only STM operations, (blocked) => (waiting).  The user of the STM
 136    should ensure that they are prepared for threads to be unblocked spuriously
 137    and for wait/reWait to return false even when the previous transaction context
 138    is actually still valid.
 139 */
 140
 141 /*
 142  * Fill in the trec's list of invariants that might be violated by the current
 143  * transaction.
 144  */
 145
 146 StgInvariantCheckQueue *stmGetInvariantsToCheck(Capability *cap,
 147                                                 StgTRecHeader *trec);
 148
 149 void stmAddInvariantToCheck(Capability *cap,
 150                             StgTRecHeader *trec,
 151                             StgClosure *code);
 152
 153 /*
 154  * Test whether the current transaction context is valid and, if so,
 155  * commit its memory accesses to the heap.  stmCommitTransaction must
 156  * unblock any threads which are waiting on tvars that updates have
 157  * been committed to.
 158  */
 159
 160 StgBool stmCommitTransaction(Capability *cap, StgTRecHeader *trec);
 161 StgBool stmCommitNestedTransaction(Capability *cap, StgTRecHeader *trec);
 162
 163 /*
 164  * Test whether the current transaction context is valid and, if so,
 165  * start the thread waiting for updates to any of the tvars it has
 166  * ready from and mark it as blocked.  It is an error to call stmWait
 167  * if the thread is already waiting.
 168  */
 169
 170 StgBool stmWait(Capability *cap, StgTSO *tso, StgTRecHeader *trec);
 171
 172 void stmWaitUnlock(Capability *cap, StgTRecHeader *trec);
 173
 174 /*
 175  * Test whether the current transaction context is valid and, if so,
 176  * leave the thread waiting and mark it as blocked again.  If the
 177  * transaction context is no longer valid then stop the thread waiting
 178  * and leave it as unblocked.  It is an error to call stmReWait if the
 179  * thread is not waiting.
 180  */
 181
 182 StgBool stmReWait(Capability *cap, StgTSO *tso);
 183
 184 /*----------------------------------------------------------------------
 185
 186    TVar management operations
 187    --------------------------
 188 */
 189
 190 StgTVar *stmNewTVar(Capability *cap, StgClosure *new_value);
 191
 192 /*----------------------------------------------------------------------
 193
 194    Data access operations
 195    ----------------------
 196 */
 197
 198 /*
 199  * Return the logical contents of 'tvar' within the context of the
 200  * thread's current transaction.
 201  */
 202
 203 StgClosure *stmReadTVar(Capability *cap,
 204                         StgTRecHeader *trec,
 205                         StgTVar *tvar);
 206
 207 /* Update the logical contents of 'tvar' within the context of the
 208  * thread's current transaction.
 209  */
 210
 211 void stmWriteTVar(Capability *cap,
 212                   StgTRecHeader *trec,
 213                   StgTVar *tvar,
 214                   StgClosure *new_value);
 215
 216 /*----------------------------------------------------------------------*/
 217
 218 /* NULLs */
 219
 220 #define END_STM_WATCH_QUEUE ((StgTVarWatchQueue *)(void *)&stg_END_STM_WATCH_QUEUE_closure)
 221 #define END_INVARIANT_CHECK_QUEUE ((StgInvariantCheckQueue *)(void *)&stg_END_INVARIANT_CHECK_QUEUE_closure)
 222 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
 223
 224 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
 225
 226 /*----------------------------------------------------------------------*/
 227
 228 #include "EndPrivate.h"
 229
 230 #endif /* STM_H */
 231