|Copyright||(c) The University of Glasgow 2004|
|License||BSD-style (see the file libraries/base/LICENSE)|
|Portability||non-portable (requires STM)|
Software Transactional Memory: a modular composable concurrency abstraction. See
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
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.
A monad supporting atomic memory transactions.
Defined in Control.Monad.STM
|MArray TArray e STM|
Defined in Control.Concurrent.STM.TArray
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.
atomically inside an
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
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 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)
orElse :: STM a -> STM a -> STM a Source
Compose two alternative STM actions (GHC only).
If the first action completes without retrying then it forms the result of the
orElse. Otherwise, if the first action retries, then the second action is tried in its place. If both actions retry then the
orElse as a whole retries.
check :: Bool -> STM () Source
Check that the boolean condition is true and, if not,
In other words,
check b = unless b retry.
throwSTM :: Exception e => e -> STM a Source
A variant of
throw that can only be used within the
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
If the exception is not caught inside of the
STM, it is re-thrown by
atomically, and the entire
STM is rolled back.
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.
catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a Source
Exception handling within STM actions.
catchSTM m f catches any exception thrown by
throwSTM, using the function
f to handle the exception. If an exception is thrown, any changes made by
m are rolled back, but changes prior to
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).