Control.Monad.STM

stm-2.4.5.0: Software Transactional Memory

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

- Orphan instances

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

Synopsis

- data STM a
- atomically :: STM a -> IO a
- always :: STM Bool -> STM ()
- alwaysSucceeds :: STM a -> STM ()
- retry :: STM a
- orElse :: STM a -> STM a -> STM a
- check :: Bool -> STM ()
- throwSTM :: Exception e => e -> STM a
- catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a

# Documentation

data STM a Source #

A monad supporting atomic memory transactions.

Instances

Monad STM | Since: 4.3.0.0
Instance details Methods (>>=) :: STM a -> (a -> STM b) -> STM b Source # (>>) :: STM a -> STM b -> STM b Source # return :: a -> STM a Source # fail :: String -> STM a Source #
Functor STM | Since: 4.3.0.0
Instance details Methods fmap :: (a -> b) -> STM a -> STM b Source # (<$) :: a -> STM b -> STM a Source #
MonadFix STM # | Since: 2.3
Instance details Methods mfix :: (a -> STM a) -> STM a Source #
Applicative STM | Since: 4.8.0.0
Instance details Methods pure :: a -> STM a Source # (<*>) :: STM (a -> b) -> STM a -> STM b Source # liftA2 :: (a -> b -> c) -> STM a -> STM b -> STM c Source # (*>) :: STM a -> STM b -> STM b Source # (<*) :: STM a -> STM b -> STM a Source #
Alternative STM | Since: 4.8.0.0
Instance details Methods empty :: STM a Source # (<|>) :: STM a -> STM a -> STM a Source # some :: STM a -> STM [a] Source # many :: STM a -> STM [a] Source #
MonadPlus STM | Since: 4.3.0.0
Instance details Methods mzero :: STM a Source # mplus :: STM a -> STM a -> STM a Source #
MArray TArray e STM # |
Instance details 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 :: STM a Source #

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)

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, `retry`.

In other words, `check b = unless b retry`.

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

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.

# Orphan instances

MonadFix STM Source # | Since: 2.3
Instance details Methods mfix :: (a -> STM a) -> STM a Source #