Control.Monad.STM

Copyright (c) The University of Glasgow 2004
License BSD-style (see the file libraries/base/LICENSE)
Maintainer [email protected]
Stability experimental
Portability non-portable (requires STM)
Safe Haskell Trustworthy
Language Haskell2010

Contents

Description

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

data STM a Source

A monad supporting atomic memory transactions.

Instances
Instances details
Monad STM

Since: base-4.3.0.0

Instance details

Defined in GHC.Conc.Sync

Methods

(>>=) :: STM a -> (a -> STM b) -> STM b Source

(>>) :: STM a -> STM b -> STM b Source

return :: a -> STM a Source

Functor STM

Since: base-4.3.0.0

Instance details

Defined in GHC.Conc.Sync

Methods

fmap :: (a -> b) -> STM a -> STM b Source

(<$) :: a -> STM b -> STM a Source

MonadFix STM

Since: stm-2.3

Instance details

Defined in Control.Monad.STM

Methods

mfix :: (a -> STM a) -> STM a Source

Applicative STM

Since: base-4.8.0.0

Instance details

Defined in GHC.Conc.Sync

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: base-4.8.0.0

Instance details

Defined in GHC.Conc.Sync

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: base-4.3.0.0

Instance details

Defined in GHC.Conc.Sync

Methods

mzero :: STM a Source

mplus :: STM a -> STM a -> STM a Source

MArray TArray e STM
Instance details

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 :: STM a Source

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

catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a Source

Exception handling within STM actions.

catchSTM m f catches any exception thrown by m using 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 m persist.

Orphan instances

MonadFix STM

Since: stm-2.3

Instance details

Methods

mfix :: (a -> STM a) -> STM a Source

© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.10.2/docs/html/libraries/stm-2.5.0.0/Control-Monad-STM.html