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	Unsafe
Language	Haskell2010

GHC.Internal.Control.Monad.ST.Imp

Contents

The ST Monad
Converting ST to IO
Unsafe operations

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
unsafeDupableInterleaveST :: 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 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) Source #	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) Source #	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) Source #	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) Source #	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) Source #	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) Source #	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) Source #	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.

Unsafe operations

unsafeInterleaveST :: ST s a -> ST s a Source #

unsafeInterleaveST allows an ST computation to be deferred lazily. When passed a value of type ST a, the ST computation will only be performed when the value of the a is demanded.

unsafeDupableInterleaveST :: ST s a -> ST s a Source #

unsafeDupableInterleaveST allows an ST computation to be deferred lazily. When passed a value of type ST a, the ST computation will only be performed when the value of the a is demanded.

The computation may be performed multiple times by different threads, possibly at the same time. To prevent this, use unsafeInterleaveST instead.

Since: base-4.11

unsafeIOToST :: IO a -> ST s a Source #

Convert an IO action to an ST action. This relies on IO and ST having the same representation modulo the constraint on the state thread type parameter.

unsafeSTToIO :: ST s a -> IO a Source #

Convert an ST action to an IO action. This relies on IO and ST having the same representation modulo the constraint on the state thread type parameter.

For an example demonstrating why this is unsafe, see https://mail.haskell.org/pipermail/haskell-cafe/2009-April/060719.html

The ST Monad

Instances

Converting ST to IO

Unsafe operations

The `ST` Monad

Converting `ST` to `IO`