ghc/includes/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 interface is designed so that all of the operations return
  12   directly: if the specified StgTSO should block then the Haskell
  13   scheduler's data structures are updated within the STM
  14   implementation, rather than blocking the native thread.
  15
  16   This interface can be supported by many different implementations,
  17   in particular it is left unspecified:
  18
  19    - Whether nested transactions are fully supported.
  20
  21      A simple implementation would count the number of
  22      stmStartTransaction operations that a thread invokes and only
  23      attempt to really commit it to the heap when the corresponding
  24      number of stmCommitTransaction calls have been made.  This
  25      prevents enclosed transactions from being aborted without also
  26      aborting all of the outer ones.
  27
  28      The current implementation does support proper nesting.
  29
  30    - Whether stmWait and stmReWait are blocking.
  31
  32      A simple implementation would always return 'false' from these
  33      operations, signalling that the calling thread should immediately
  34      retry its transaction.
  35
  36      A fuller implementation would block the thread and return 'True'
  37      when it is safe for the thread to block.
  38
  39      The current implementation does provide stmWait and stmReWait
  40      operations which can block the caller's TSO.
  41
  42    - Whether the transactional read, write, commit and validate
  43      operations are blocking or non-blocking.
  44
  45      A simple implementation would use an internal lock to prevent
  46      concurrent execution of any STM operations.  (This does not
  47      prevent multiple threads having concurrent transactions, merely
  48      the concurrent execution of say stmCommitTransaction by two
  49      threads at the same time).
  50
  51      A fuller implementation would offer obstruction-free or lock-free
  52      progress guarantees, as in our OOPSLA 2003 paper.
  53
  54      The current implementation is lock-free for simple uncontended
  55      operations, but uses an internal lock on SMP systems in some
  56      cases.  This aims to provide good performance on uniprocessors:
  57      it substantially streamlines the design, when compared with the
  58      OOPSLA paper, and on a uniprocessor we can be sure that threads
  59      are never pre-empted within STM operations.
  60 */
  61
  62 #ifndef STM_H
  63 #define STM_H
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /*----------------------------------------------------------------------
  70
  71    Start of day
  72    ------------
  73
  74 */
  75
  76 extern void initSTM(void);
  77
  78 extern void stmPreGCHook(void);
  79
  80 /*----------------------------------------------------------------------
  81
  82    Transaction context management
  83    ------------------------------
  84
  85 */
  86
  87 // Create and enter a new transaction context
  88
  89 extern StgTRecHeader *stmStartTransaction(StgTRecHeader *outer);
  90
  91 // Exit the current transaction context, abandoning any read/write
  92 // operations performed within it and removing the thread from any
  93 // tvar wait queues if it was waitin.  Note that if nested transactions
  94 // are not fully supported then this may leave the enclosing
  95 // transaction contexts doomed to abort.
  96
  97 extern void stmAbortTransaction(StgTRecHeader *trec);
  98
  99 // Return the trec within which the specified trec was created (not
 100 // valid if trec==NO_TREC).
 101
 102 extern StgTRecHeader *stmGetEnclosingTRec(StgTRecHeader *trec);
 103
 104 /*----------------------------------------------------------------------
 105
 106    Validate/commit/wait/rewait operations
 107    --------------------------------------
 108
 109
 110    These four operations return boolean results which should be interpreted
 111    as follows:
 112
 113    true  => The transaction context was definitely valid
 114
 115    false => The transaction context may not have been valid
 116
 117    The user of the STM should ensure that it is always safe to assume that a
 118    transaction context is not valid when in fact it is (i.e. to return false in
 119    place of true, with side-effects as defined below).  This may cause
 120    needless retries of transactions (in the case of validate and commit), or it
 121    may cause needless spinning instead of blocking (in the case of wait and
 122    rewait).
 123
 124    In defining the behaviour of wait and rewait we distinguish between two
 125    different aspects of a thread's runnability:
 126
 127     - We say that a thread is "blocked" when it is not running or
 128       runnable as far as the scheduler is concerned.
 129
 130     - We say that a thread is "waiting" when its StgTRecHeader is linked on an
 131       tvar's wait queue.
 132
 133    Considering only STM operations, (blocked) => (waiting).  The user of the STM
 134    should ensure that they are prepared for threads to be unblocked spuriously
 135    and for wait/reWait to return false even when the previous transaction context
 136    is actually still valid.
 137 */
 138
 139 // Test whether the current transaction context is valid, i.e. whether
 140 // it is still possible for it to commit successfully.  Note: we assume that
 141 // once stmValidateTransaction has returned FALSE for a given transaction then
 142 // that transaction will never again be valid -- we rely on this in Schedule.c when
 143 // kicking invalid threads at GC (in case they are stuck looping)
 144
 145 extern StgBool stmValidateTransaction(StgTRecHeader *trec);
 146
 147 // Test whether the current transaction context is valid and, if so,
 148 // commit its memory accesses to the heap.  stmCommitTransaction must
 149 // unblock any threads which are waiting on tvars that updates have
 150 // been committed to.
 151
 152 extern StgBool stmCommitTransaction(StgTRecHeader *trec);
 153
 154 // Test whether the current transaction context is valid and, if so,
 155 // start the thread waiting for updates to any of the tvars it has
 156 // ready from and mark it as blocked.  It is an error to call stmWait
 157 // if the thread is already waiting.
 158
 159 extern StgBool stmWait(StgTSO *tso, StgTRecHeader *trec);
 160
 161 // Test whether the current transaction context is valid and, if so,
 162 // leave the thread waiting and mark it as blocked again.  If the
 163 // transaction context is no longer valid then stop the thread waiting
 164 // and leave it as unblocked.  It is an error to call stmReWait if the
 165 // thread is not waiting.
 166
 167 extern StgBool stmReWait(StgTRecHeader *trec);
 168
 169 // Merge the accesses made so far in the second trec into the first trec.
 170 // Note that the resulting trec is only intended to be used in wait operations.
 171 // This avoids defining what happens if "trec" and "other" contain conflicting
 172 // updates.
 173
 174 extern StgBool stmMergeForWaiting(StgTRecHeader *trec, StgTRecHeader *other);
 175
 176
 177 /*----------------------------------------------------------------------
 178
 179    Data access operations
 180    ----------------------
 181 */
 182
 183 // Return the logical contents of 'tvar' within the context of the
 184 // thread's current transaction.
 185
 186 extern StgClosure *stmReadTVar(StgTRecHeader *trec,
 187                                StgTVar *tvar);
 188
 189 // Update the logical contents of 'tvar' within the context of the
 190 // thread's current transaction.
 191
 192 extern void stmWriteTVar(StgTRecHeader *trec,
 193                          StgTVar *tvar,
 194                          StgClosure *new_value);
 195
 196 /*----------------------------------------------------------------------*/
 197
 198 // NULLs
 199
 200 #define END_STM_WAIT_QUEUE ((StgTVarWaitQueue *)(void *)&stg_END_STM_WAIT_QUEUE_closure)
 201 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
 202 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
 203
 204 /*----------------------------------------------------------------------*/
 205
 206 #ifdef __cplusplus
 207 }
 208 #endif
 209
 210 #endif /* STM_H */
 211