base-4.6.0.1: Basic libraries

Portability | non-portable (requires universal quantification for runST)
Stability | experimental
Maintainer | libraries@haskell.org
Safe Haskell | Unsafe

Control.Monad.ST

Contents

- The `ST` Monad
- Converting `ST` to `IO`
- Unsafe Functions

Description

This library provides support for strict state threads, as described in the PLDI '94 paper by John Launchbury and Simon Peyton Jones Lazy Functional State Threads.

Synopsis

- data ST s a
- runST :: (forall s. ST s a) -> a
- fixST :: (a -> ST s a) -> ST s a
- data RealWorld
- stToIO :: ST RealWorld a -> IO a
- unsafeInterleaveST :: ST s a -> ST s a
- unsafeIOToST :: IO a -> ST s a
- unsafeSTToIO :: ST s a -> IO a

# The `ST` Monad

data ST s a

The strict state-transformer monad. A computation of type ``ST` s a` transforms an internal state indexed by `s`, and returns a value of type `a`. The `s` parameter is either

- an uninstantiated type variable (inside invocations of `runST`), or
- `RealWorld` (inside invocations of `stToIO`).

It serves to keep the internal states of different invocations of `runST` separate from each other and from invocations of `stToIO`.

The `>>=` and `>>` operations are strict in the state (though not in values stored in the state). For example,

    runST (writeSTRef _|_ v >>= f) = _|_

Instances

Typeable2 ST |
Monad (ST s) |
Functor (ST s) |
MonadFix (ST s) |
Applicative (ST s) |
Show (ST s a) |

runST :: (forall s. ST s a) -> a

Return the value computed by a state transformer computation. The `forall` ensures that the internal state used by the `ST` computation is inaccessible to the rest of the program.

fixST :: (a -> ST s a) -> ST s a

Allow the result of a state transformer computation to be used (lazily) inside the computation. Note that if `f` is strict, ``fixST` f = _|_`.

# Converting `ST` to `IO`

data RealWorld Source

`RealWorld` is deeply magical. It is primitive, but it is not unlifted (hence `ptrArg`). We never manipulate values of type `RealWorld`; it's only used in the type system, to parameterise `State#`.

Instances

Typeable RealWorld |

stToIO :: ST RealWorld a -> IO a

A monad transformer embedding strict state transformers in the `IO` monad. The `RealWorld` parameter indicates that the internal state used by the `ST` computation is a special one supplied by the `IO` monad, and thus distinct from those used by invocations of `runST`.

# Unsafe Functions

unsafeInterleaveST :: ST s a -> ST s a

Deprecated: Please import from Control.Monad.ST.Unsafe instead; This will be removed in the next release

unsafeIOToST :: IO a -> ST s a

Deprecated: Please import from Control.Monad.ST.Unsafe instead; This will be removed in the next release

unsafeSTToIO :: ST s a -> IO a

Deprecated: Please import from Control.Monad.ST.Unsafe instead; This will be removed in the next release