base-4.20.2.0: Core data structures and operations

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | stable
Portability | non-portable (requires universal quantification for runST)
Safe Haskell | Safe
Language | Haskell2010

Control.Monad.ST

Contents

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

Description

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

References (variables) that can be used within the `ST` monad are provided by Data.STRef, and arrays are provided by Data.Array.ST.

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

# The `ST` Monad

data ST s a Source #

The strict `ST` monad. The `ST` monad allows for destructive updates, but is escapable (unlike IO). A computation of type ``ST` s a` returns a value of type `a`, and execute in "thread" `s`. 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

Instances details

Applicative (ST s) | Since: base-4.4.0.0
Instance details Defined in GHC.Internal.ST Methods pure :: a -> ST s a Source # (<*>) :: ST s (a -> b) -> ST s a -> ST s b Source # liftA2 :: (a -> b -> c) -> ST s a -> ST s b -> ST s c Source # (*>) :: ST s a -> ST s b -> ST s b Source # (<*) :: ST s a -> ST s b -> ST s a Source #
Functor (ST s) | Since: base-2.1
Instance details Defined in GHC.Internal.ST Methods fmap :: (a -> b) -> ST s a -> ST s b Source # (<$) :: a -> ST s b -> ST s a Source #
Monad (ST s) | Since: base-2.1
Instance details Defined in GHC.Internal.ST Methods (>>=) :: ST s a -> (a -> ST s b) -> ST s b Source # (>>) :: ST s a -> ST s b -> ST s b Source # return :: a -> ST s a Source #
MonadFix (ST s) | Since: base-2.1
Instance details Defined in GHC.Internal.Control.Monad.Fix Methods mfix :: (a -> ST s a) -> ST s a Source #
Monoid a => Monoid (ST s a) | Since: base-4.11.0.0
Instance details Defined in GHC.Internal.ST Methods mempty :: ST s a Source # mappend :: ST s a -> ST s a -> ST s a Source # mconcat :: [ST s a] -> ST s a Source #
Semigroup a => Semigroup (ST s a) | Since: base-4.11.0.0
Instance details Defined in GHC.Internal.ST Methods (<>) :: ST s a -> ST s a -> ST s a Source # sconcat :: NonEmpty (ST s a) -> ST s a Source # stimes :: Integral b => b -> ST s a -> ST s a Source #
Show (ST s a) | Since: base-2.1
Instance details Defined in GHC.Internal.ST Methods showsPrec :: Int -> ST s a -> ShowS Source # show :: ST s a -> String Source # showList :: [ST s a] -> ShowS Source #

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

Return the value computed by a state thread. 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 Source #

Allow the result of an `ST` 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#`.

stToIO :: ST RealWorld a -> IO a Source #

Embed a strict state thread in an `IO` action. 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`.