cpp: Use #pragma once instead of #ifndef guards
[ghc.git] / 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 #pragma once
34
35 #ifdef THREADED_RTS
36 //#define STM_CG_LOCK
37 #define STM_FG_LOCKS
38 #else
39 #define STM_UNIPROC
40 #endif
41
42 #include "BeginPrivate.h"
43
44 /*----------------------------------------------------------------------
45
46 GC interaction
47 --------------
48 */
49
50 void stmPreGCHook(Capability *cap);
51
52 /*----------------------------------------------------------------------
53
54 Transaction context management
55 ------------------------------
56
57 */
58
59 /* Create and enter a new transaction context */
60
61 StgTRecHeader *stmStartTransaction(Capability *cap, StgTRecHeader *outer);
62 StgTRecHeader *stmStartNestedTransaction(Capability *cap, StgTRecHeader *outer
63 );
64
65 /*
66 * Roll back the current transatcion context. NB: if this is a nested tx
67 * then we merge its read set into its parents. This is because a change
68 * to that read set could change whether or not the tx should abort.
69 */
70
71 void stmAbortTransaction(Capability *cap, StgTRecHeader *trec);
72 void stmFreeAbortedTRec(Capability *cap, StgTRecHeader *trec);
73
74 /*
75 * Ensure that a subsequent commit / validation will fail. We use this
76 * in our current handling of transactions that may have become invalid
77 * and started looping. We strip their stack back to the ATOMICALLY_FRAME,
78 * and, when the thread is next scheduled, discover it to be invalid and
79 * re-execute it. However, we need to force the transaction to stay invalid
80 * in case other threads' updates make it valid in the mean time.
81 */
82
83 void stmCondemnTransaction(Capability *cap, StgTRecHeader *trec);
84
85 /*----------------------------------------------------------------------
86
87 Validation
88 ----------
89
90 Test whether the specified transaction record, and all those within which
91 it is nested, are still valid.
92
93 Note: the caller can assume that once stmValidateTransaction has
94 returned false for a given trec then that transaction will never
95 again be valid -- we rely on this in Schedule.c when kicking invalid
96 threads at GC (in case they are stuck looping)
97 */
98
99 StgBool stmValidateNestOfTransactions(Capability *cap, StgTRecHeader *trec);
100
101 /*----------------------------------------------------------------------
102
103 Commit/wait/rewait operations
104 -----------------------------
105
106 These four operations return boolean results which should be interpreted
107 as follows:
108
109 true => The transaction record was definitely valid
110
111 false => The transaction record may not have been valid
112
113 Note that, for nested operations, validity here is solely in terms
114 of the specified trec: it does not say whether those that it may be
115 nested are themselves valid. Callers can check this with
116 stmValidateNestOfTransactions.
117
118 The user of the STM should ensure that it is always safe to assume that a
119 transaction context is not valid when in fact it is (i.e. to return false in
120 place of true, with side-effects as defined below). This may cause
121 needless retries of transactions (in the case of validate and commit), or it
122 may cause needless spinning instead of blocking (in the case of wait and
123 rewait).
124
125 In defining the behaviour of wait and rewait we distinguish between two
126 different aspects of a thread's runnability:
127
128 - We say that a thread is "blocked" when it is not running or
129 runnable as far as the scheduler is concerned.
130
131 - We say that a thread is "waiting" when its StgTRecHeader is linked on an
132 tvar's wait queue.
133
134 Considering only STM operations, (blocked) => (waiting). The user of the STM
135 should ensure that they are prepared for threads to be unblocked spuriously
136 and for wait/reWait to return false even when the previous transaction context
137 is actually still valid.
138 */
139
140 /*
141 * Fill in the trec's list of invariants that might be violated by the current
142 * transaction.
143 */
144
145 StgInvariantCheckQueue *stmGetInvariantsToCheck(Capability *cap,
146 StgTRecHeader *trec);
147
148 void stmAddInvariantToCheck(Capability *cap,
149 StgTRecHeader *trec,
150 StgClosure *code);
151
152 /*
153 * Test whether the current transaction context is valid and, if so,
154 * commit its memory accesses to the heap. stmCommitTransaction must
155 * unblock any threads which are waiting on tvars that updates have
156 * been committed to.
157 */
158
159 StgBool stmCommitTransaction(Capability *cap, StgTRecHeader *trec);
160 StgBool stmCommitNestedTransaction(Capability *cap, StgTRecHeader *trec);
161
162 /*
163 * Test whether the current transaction context is valid and, if so,
164 * start the thread waiting for updates to any of the tvars it has
165 * ready from and mark it as blocked. It is an error to call stmWait
166 * if the thread is already waiting.
167 */
168
169 StgBool stmWait(Capability *cap, StgTSO *tso, StgTRecHeader *trec);
170
171 void stmWaitUnlock(Capability *cap, StgTRecHeader *trec);
172
173 /*
174 * Test whether the current transaction context is valid and, if so,
175 * leave the thread waiting and mark it as blocked again. If the
176 * transaction context is no longer valid then stop the thread waiting
177 * and leave it as unblocked. It is an error to call stmReWait if the
178 * thread is not waiting.
179 */
180
181 StgBool stmReWait(Capability *cap, StgTSO *tso);
182
183 /*----------------------------------------------------------------------
184
185 Data access operations
186 ----------------------
187 */
188
189 /*
190 * Return the logical contents of 'tvar' within the context of the
191 * thread's current transaction.
192 */
193
194 StgClosure *stmReadTVar(Capability *cap,
195 StgTRecHeader *trec,
196 StgTVar *tvar);
197
198 /* Update the logical contents of 'tvar' within the context of the
199 * thread's current transaction.
200 */
201
202 void stmWriteTVar(Capability *cap,
203 StgTRecHeader *trec,
204 StgTVar *tvar,
205 StgClosure *new_value);
206
207 /*----------------------------------------------------------------------*/
208
209 /* NULLs */
210
211 #define END_STM_WATCH_QUEUE ((StgTVarWatchQueue *)(void *)&stg_END_STM_WATCH_QUEUE_closure)
212 #define END_INVARIANT_CHECK_QUEUE ((StgInvariantCheckQueue *)(void *)&stg_END_INVARIANT_CHECK_QUEUE_closure)
213 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
214
215 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
216
217 /*----------------------------------------------------------------------*/
218
219 #include "EndPrivate.h"