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. 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
A monad supporting atomic memory transactions.
Instances
Monad STM | Since: 4.3.0.0 |
Functor STM | Since: 4.3.0.0 |
Applicative STM | Since: 4.8.0.0 |
Alternative STM | Since: 4.8.0.0 |
MonadPlus STM | Since: 4.3.0.0 |
MArray TArray e STM # | |
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.
always :: STM Bool -> STM () Source #
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 () Source #
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 TVar
s which mean that it should not continue (e.g. the TVar
s
represent a shared buffer that is now empty). The implementation may
block the thread until one of the TVar
s that it has read from has been
updated. (GHC only)
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.
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.
catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a Source #
Exception handling within STM actions.