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 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.
16 This interface can be supported by many different implementations,
17 in particular it is left unspecified:
19 - Whether nested transactions are fully supported.
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.
28 The current implementation does support proper nesting.
30 - Whether stmWait and stmReWait are blocking.
32 A simple implementation would always return 'false' from these
33 operations, signalling that the calling thread should immediately
34 retry its transaction.
36 A fuller implementation would block the thread and return 'True'
37 when it is safe for the thread to block.
39 The current implementation does provide stmWait and stmReWait
40 operations which can block the caller's TSO.
42 - Whether the transactional read, write, commit and validate
43 operations are blocking or non-blocking.
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).
51 A fuller implementation would offer obstruction-free or lock-free
52 progress guarantees, as in our OOPSLA 2003 paper.
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.
69 /*----------------------------------------------------------------------
76 extern void initSTM(void);
78 extern void stmPreGCHook(void);
80 /*----------------------------------------------------------------------
82 Transaction context management
83 ------------------------------
87 // Create and enter a new transaction context
89 extern StgTRecHeader *stmStartTransaction(StgTRecHeader *outer);
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.
97 extern void stmAbortTransaction(StgTRecHeader *trec);
99 // Return the trec within which the specified trec was created (not
100 // valid if trec==NO_TREC).
102 extern StgTRecHeader *stmGetEnclosingTRec(StgTRecHeader *trec);
104 /*----------------------------------------------------------------------
106 Validate/commit/wait/rewait operations
107 --------------------------------------
110 These four operations return boolean results which should be interpreted
113 true => The transaction context was definitely valid
115 false => The transaction context may not have been valid
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
124 In defining the behaviour of wait and rewait we distinguish between two
125 different aspects of a thread's runnability:
127 - We say that a thread is "blocked" when it is not running or
128 runnable as far as the scheduler is concerned.
130 - We say that a thread is "waiting" when its StgTRecHeader is linked on an
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.
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)
145 extern StgBool stmValidateTransaction(StgTRecHeader *trec);
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.
152 extern StgBool stmCommitTransaction(StgTRecHeader *trec);
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.
159 extern StgBool stmWait(StgTSO *tso, StgTRecHeader *trec);
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.
167 extern StgBool stmReWait(StgTRecHeader *trec);
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
174 extern StgBool stmMergeForWaiting(StgTRecHeader *trec, StgTRecHeader *other);
177 /*----------------------------------------------------------------------
179 Data access operations
180 ----------------------
183 // Return the logical contents of 'tvar' within the context of the
184 // thread's current transaction.
186 extern StgClosure *stmReadTVar(StgTRecHeader *trec,
189 // Update the logical contents of 'tvar' within the context of the
190 // thread's current transaction.
192 extern void stmWriteTVar(StgTRecHeader *trec,
194 StgClosure *new_value);
196 /*----------------------------------------------------------------------*/
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)
204 /*----------------------------------------------------------------------*/