| 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.