1 /*----------------------------------------------------------------------
3 * (c) The GHC Team, 1998-2004
5 * STM interface definition
7 *----------------------------------------------------------------------
9 STM.h defines the C-level interface to the STM.
11 The design follows that of the PPoPP 2005 paper "Composable memory
12 transactions" extended to include fine-grained locking of TVars.
14 Three different implementations can be built. In overview:
16 STM_UNIPROC -- no locking at all: not safe for concurrent invocations
18 STM_CG_LOCK -- coarse-grained locking : a single mutex protects all
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.
29 STM.C contains more details about the locking schemes used.
47 /*----------------------------------------------------------------------
53 extern void stmPreGCHook(void);
55 /*----------------------------------------------------------------------
57 Transaction context management
58 ------------------------------
62 /* Create and enter a new transaction context */
64 extern StgTRecHeader *stmStartTransaction(Capability *cap, StgTRecHeader *outer);
65 extern StgTRecHeader *stmStartNestedTransaction(Capability *cap, StgTRecHeader *outer
69 * Roll back the current transatcion context. NB: if this is a nested tx
70 * then we merge its read set into its parents. This is because a change
71 * to that read set could change whether or not the tx should abort.
74 extern void stmAbortTransaction(Capability *cap, StgTRecHeader *trec);
75 extern void stmFreeAbortedTRec(Capability *cap, StgTRecHeader *trec);
78 * Ensure that a subsequent commit / validation will fail. We use this
79 * in our current handling of transactions that may have become invalid
80 * and started looping. We strip their stack back to the ATOMICALLY_FRAME,
81 * and, when the thread is next scheduled, discover it to be invalid and
82 * re-execute it. However, we need to force the transaction to stay invalid
83 * in case other threads' updates make it valid in the mean time.
86 extern void stmCondemnTransaction(Capability *cap, StgTRecHeader *trec);
89 * Return the trec within which the specified trec was created (not
90 * valid if trec==NO_TREC).
93 extern StgTRecHeader *stmGetEnclosingTRec(StgTRecHeader *trec);
95 /*----------------------------------------------------------------------
100 Test whether the specified transaction record, and all those within which
101 it is nested, are still valid.
103 Note: the caller can assume that once stmValidateTransaction has
104 returned FALSE for a given trec then that transaction will never
105 again be valid -- we rely on this in Schedule.c when kicking invalid
106 threads at GC (in case they are stuck looping)
109 extern StgBool stmValidateNestOfTransactions(StgTRecHeader *trec);
111 /*----------------------------------------------------------------------
113 Commit/wait/rewait operations
114 -----------------------------
116 These four operations return boolean results which should be interpreted
119 true => The transaction record was definitely valid
121 false => The transaction record may not have been valid
123 Note that, for nested operations, validity here is solely in terms
124 of the specified trec: it does not say whether those that it may be
125 nested are themselves valid. Callers can check this with
126 stmValidateNestOfTransactions.
128 The user of the STM should ensure that it is always safe to assume that a
129 transaction context is not valid when in fact it is (i.e. to return false in
130 place of true, with side-effects as defined below). This may cause
131 needless retries of transactions (in the case of validate and commit), or it
132 may cause needless spinning instead of blocking (in the case of wait and
135 In defining the behaviour of wait and rewait we distinguish between two
136 different aspects of a thread's runnability:
138 - We say that a thread is "blocked" when it is not running or
139 runnable as far as the scheduler is concerned.
141 - We say that a thread is "waiting" when its StgTRecHeader is linked on an
144 Considering only STM operations, (blocked) => (waiting). The user of the STM
145 should ensure that they are prepared for threads to be unblocked spuriously
146 and for wait/reWait to return false even when the previous transaction context
147 is actually still valid.
151 * Fill in the trec's list of invariants that might be violated by the current
155 extern StgInvariantCheckQueue *stmGetInvariantsToCheck(Capability *cap,
156 StgTRecHeader *trec);
158 extern void stmAddInvariantToCheck(Capability *cap,
163 * Test whether the current transaction context is valid and, if so,
164 * commit its memory accesses to the heap. stmCommitTransaction must
165 * unblock any threads which are waiting on tvars that updates have
169 extern StgBool stmCommitTransaction(Capability *cap, StgTRecHeader *trec);
170 extern StgBool stmCommitNestedTransaction(Capability *cap, StgTRecHeader *trec);
173 * Test whether the current transaction context is valid and, if so,
174 * start the thread waiting for updates to any of the tvars it has
175 * ready from and mark it as blocked. It is an error to call stmWait
176 * if the thread is already waiting.
179 extern StgBool stmWait(Capability *cap,
181 StgTRecHeader *trec);
183 extern void stmWaitUnlock(Capability *cap, StgTRecHeader *trec);
186 * Test whether the current transaction context is valid and, if so,
187 * leave the thread waiting and mark it as blocked again. If the
188 * transaction context is no longer valid then stop the thread waiting
189 * and leave it as unblocked. It is an error to call stmReWait if the
190 * thread is not waiting.
193 extern StgBool stmReWait(Capability *cap, StgTSO *tso);
195 /*----------------------------------------------------------------------
197 TVar management operations
198 --------------------------
201 extern StgTVar *stmNewTVar(Capability *cap,
202 StgClosure *new_value);
204 /*----------------------------------------------------------------------
206 Data access operations
207 ----------------------
211 * Return the logical contents of 'tvar' within the context of the
212 * thread's current transaction.
215 extern StgClosure *stmReadTVar(Capability *cap,
219 /* Update the logical contents of 'tvar' within the context of the
220 * thread's current transaction.
223 extern void stmWriteTVar(Capability *cap,
226 StgClosure *new_value);
228 /*----------------------------------------------------------------------*/
232 #define END_STM_WATCH_QUEUE ((StgTVarWatchQueue *)(void *)&stg_END_STM_WATCH_QUEUE_closure)
233 #define END_INVARIANT_CHECK_QUEUE ((StgInvariantCheckQueue *)(void *)&stg_END_INVARIANT_CHECK_QUEUE_closure)
234 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
236 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
238 /*----------------------------------------------------------------------*/