Make tidyProgram discard speculative specialisation rules
[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 #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(Capability *cap, 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 Data access operations
187 ----------------------
188 */
189
190 /*
191 * Return the logical contents of 'tvar' within the context of the
192 * thread's current transaction.
193 */
194
195 StgClosure *stmReadTVar(Capability *cap,
196 StgTRecHeader *trec,
197 StgTVar *tvar);
198
199 /* Update the logical contents of 'tvar' within the context of the
200 * thread's current transaction.
201 */
202
203 void stmWriteTVar(Capability *cap,
204 StgTRecHeader *trec,
205 StgTVar *tvar,
206 StgClosure *new_value);
207
208 /*----------------------------------------------------------------------*/
209
210 /* NULLs */
211
212 #define END_STM_WATCH_QUEUE ((StgTVarWatchQueue *)(void *)&stg_END_STM_WATCH_QUEUE_closure)
213 #define END_INVARIANT_CHECK_QUEUE ((StgInvariantCheckQueue *)(void *)&stg_END_INVARIANT_CHECK_QUEUE_closure)
214 #define END_STM_CHUNK_LIST ((StgTRecChunk *)(void *)&stg_END_STM_CHUNK_LIST_closure)
215
216 #define NO_TREC ((StgTRecHeader *)(void *)&stg_NO_TREC_closure)
217
218 /*----------------------------------------------------------------------*/
219
220 #include "EndPrivate.h"
221
222 #endif /* STM_H */
223
224
225 // Local Variables:
226 // mode: C
227 // fill-column: 80
228 // indent-tabs-mode: nil
229 // c-basic-offset: 4
230 // buffer-file-coding-system: utf-8-unix
231 // End: