| Copyright | (c) The University of Glasgow 2004 |
|---|---|
| License | BSD-style (see the file libraries/base/LICENSE) |
| Maintainer | libraries@haskell.org |
| Stability | experimental |
| Portability | non-portable (requires STM) |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Control.Monad.STM
Contents
Description
Software Transactional Memory: a modular composable concurrency abstraction. See
- Composable memory transactions, by Tim Harris, Simon Marlow, Simon Peyton Jones, and Maurice Herlihy, in ACM Conference on Principles and Practice of Parallel Programming 2005. https://www.microsoft.com/en-us/research/publication/composable-memory-transactions/
This module only defines the STM monad; you probably want to
import Control.Concurrent.STM (which exports Control.Monad.STM).
Note that invariant checking (namely the always and alwaysSucceeds
functions) has been removed. See ticket #14324 and
the removal proposal.
Existing users are encouraged to encapsulate their STM operations in safe
abstractions which can perform the invariant checking without help from the
runtime system.
Documentation
A monad supporting atomic memory transactions.
Instances
| MonadFix STM # | Since: stm-2.3 |
| Alternative STM | Since: base-4.8.0.0 |
| Applicative STM | Since: base-4.8.0.0 |
| Functor STM | Since: base-4.3.0.0 |
| Monad STM | Since: base-4.3.0.0 |
| MonadPlus STM | Since: base-4.3.0.0 |
| MArray TArray e STM # | |
Defined in Control.Concurrent.STM.TArray Methods getBounds :: Ix i => TArray i e -> STM (i, i) Source # getNumElements :: Ix i => TArray i e -> STM Int newArray :: Ix i => (i, i) -> e -> STM (TArray i e) Source # newArray_ :: Ix i => (i, i) -> STM (TArray i e) Source # unsafeNewArray_ :: Ix i => (i, i) -> STM (TArray i e) unsafeRead :: Ix i => TArray i e -> Int -> STM e unsafeWrite :: Ix i => TArray i e -> Int -> e -> STM () | |
atomically :: STM a -> IO a Source #
Perform a series of STM actions atomically.
Using atomically inside an unsafePerformIO or unsafeInterleaveIO
subverts some of guarantees that STM provides. It makes it possible to
run a transaction inside of another transaction, depending on when the
thunk is evaluated. If a nested transaction is attempted, an exception
is thrown by the runtime. It is possible to safely use atomically inside
unsafePerformIO or unsafeInterleaveIO, but the typechecker does not
rule out programs that may attempt nested transactions, meaning that
the programmer must take special care to prevent these.
However, there are functions for creating transactional variables that
can always be safely called in unsafePerformIO. See: newTVarIO,
newTChanIO,
newBroadcastTChanIO,
newTQueueIO,
newTBQueueIO, and
newTMVarIO.
Using unsafePerformIO inside of atomically is also dangerous but for
different reasons. See unsafeIOToSTM for more on this.
Retry execution of the current memory transaction because it has seen
values in TVars which mean that it should not continue (e.g. the TVars
represent a shared buffer that is now empty). The implementation may
block the thread until one of the TVars that it has read from has been
updated. (GHC only)
Check that the boolean condition is true and, if not, retry.
In other words, check b = unless b retry.
Since: stm-2.1.1
throwSTM :: Exception e => e -> STM a Source #
A variant of throw that can only be used within the STM monad.
Throwing an exception in STM aborts the transaction and propagates the
exception. If the exception is caught via catchSTM, only the changes
enclosed by the catch are rolled back; changes made outside of catchSTM
persist.
If the exception is not caught inside of the STM, it is re-thrown by
atomically, and the entire STM is rolled back.
Although throwSTM has a type that is an instance of the type of throw, the
two functions are subtly different:
throw e `seq` x ===> throw e throwSTM e `seq` x ===> x
The first example will cause the exception e to be raised,
whereas the second one won't. In fact, throwSTM will only cause
an exception to be raised when it is used within the STM monad.
The throwSTM variant should be used in preference to throw to
raise an exception within the STM monad because it guarantees
ordering with respect to other STM operations, whereas throw
does not.