| Portability | non-portable (requires STM) |
|---|---|
| Stability | experimental |
| Maintainer | libraries@haskell.org |
| Safe Haskell | Trustworthy |
Control.Monad.STM
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. http://research.microsoft.com/Users/simonpj/papers/stm/index.htm
This module only defines the STM monad; you probably want to
import Control.Concurrent.STM (which exports Control.Monad.STM).
Documentation
data STM a
A monad supporting atomic memory transactions.
atomically :: STM a -> IO a
Perform a series of STM actions atomically.
You cannot use atomically inside an unsafePerformIO or unsafeInterleaveIO.
Any attempt to do so will result in a runtime error. (Reason: allowing
this would effectively allow a transaction inside a transaction, depending
on exactly when the thunk is evaluated.)
However, see newTVarIO, which can be called inside unsafePerformIO,
and which allows top-level TVars to be allocated.
always is a variant of alwaysSucceeds in which the invariant is expressed as an STM Bool action that must return True. Returning False or raising an exception are both treated as invariant failures.
alwaysSucceeds :: STM a -> STM ()
alwaysSucceeds adds a new invariant that must be true when passed to alwaysSucceeds, at the end of the current transaction, and at the end of every subsequent transaction. If it fails at any of those points then the transaction violating it is aborted and the exception raised by the invariant is propagated.
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 udpated. (GHC only)
orElse :: STM a -> STM a -> STM a
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.
throwSTM :: Exception e => e -> STM a
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.
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.