Commit 8546afc5 authored by Artem Pelenitsyn's avatar Artem Pelenitsyn Committed by Ben Gamari

docs: "state transformer" -> "state monad" / "ST" (whichever is meant)

FIxes #15189.

Reviewers: hvr, bgamari, simonmar, simonpj

Reviewed By: simonpj

Subscribers: simonpj, rwbarton, thomie, carter

GHC Trac Issues: #15189

Differential Revision: https://phabricator.haskell.org/D5019
parent c6f4eb4f
......@@ -310,7 +310,7 @@ argument: there's no cost for adding another argument. But functions
can only return one result: the cost of adding a second ``result'' is
that the function must construct a tuple of ``results'' on the heap.
The asymmetry is rather galling and can make certain programming
styles quite expensive. For example, consider a simple state transformer
styles quite expensive. For example, consider a simple state
monad:
\begin{verbatim}
> type S a = State -> (a,State)
......@@ -321,7 +321,7 @@ monad:
\end{verbatim}
Here, every use of @returnS@, @getS@ or @setS@ constructs a new tuple
in the heap which is instantly taken apart (and becomes garbage) by
the case analysis in @bind@. Even a short state-transformer program
the case analysis in @bind@. Even a short program using the state monad
will construct a lot of these temporary tuples.
Unboxed tuples provide a way for the programmer to indicate that they
......
......@@ -188,7 +188,7 @@ forever a = let a' = a *> a' in a'
-- | The 'mapAndUnzipM' function maps its first argument over a list, returning
-- the result as a pair of lists. This function is mainly used with complicated
-- data structures or a state-transforming monad.
-- data structures or a state monad.
mapAndUnzipM :: (Applicative m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
{-# INLINE mapAndUnzipM #-}
mapAndUnzipM f xs = unzip <$> traverse f xs
......
......@@ -45,7 +45,7 @@ import Control.Exception.Base
( catch, throwIO, NonTermination (..)
, BlockedIndefinitelyOnMVar (..) )
-- | Allow the result of a state transformer computation to be used (lazily)
-- | Allow the result of an 'ST' computation to be used (lazily)
-- inside the computation.
--
-- Note that if @f@ is strict, @'fixST' f = _|_@.
......
......@@ -14,7 +14,7 @@
-- Portability : non-portable (requires universal quantification for runST)
--
-- This module presents an identical interface to "Control.Monad.ST",
-- except that the monad delays evaluation of state operations until
-- except that the monad delays evaluation of 'ST' operations until
-- a value depending on them is required.
--
-----------------------------------------------------------------------------
......@@ -46,10 +46,10 @@ import qualified GHC.ST as GHC.ST
import GHC.Base
import qualified Control.Monad.Fail as Fail
-- | The lazy 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
-- | The lazy @'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
--
......@@ -198,13 +198,13 @@ instance Monad (ST s) where
instance Fail.MonadFail (ST s) where
fail s = errorWithoutStackTrace s
-- | Return the value computed by a state transformer computation.
-- | Return the value computed by an 'ST' computation.
-- The @forall@ ensures that the internal state used by the 'ST'
-- computation is inaccessible to the rest of the program.
runST :: (forall s. ST s a) -> a
runST (ST st) = runRW# (\s -> case st (S# s) of (r, _) -> r)
-- | Allow the result of a state transformer computation to be used (lazily)
-- | Allow the result of an 'ST' computation to be used (lazily)
-- inside the computation.
-- Note that if @f@ is strict, @'fixST' f = _|_@.
fixST :: (a -> ST s a) -> ST s a
......@@ -243,7 +243,7 @@ lazyToStrictST :: ST s a -> ST.ST s a
lazyToStrictST (ST m) = GHC.ST.ST $ \s ->
case (m (S# s)) of (a, S# s') -> (# s', a #)
-- | A monad transformer embedding lazy state transformers in the 'IO'
-- | A monad transformer embedding lazy 'ST' 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'.
......
......@@ -11,7 +11,7 @@
-- Portability : non-portable (requires universal quantification for runST)
--
-- This module presents an identical interface to "Control.Monad.ST",
-- except that the monad delays evaluation of state operations until
-- except that the monad delays evaluation of 'ST' operations until
-- a value depending on them is required.
--
-- Safe API only.
......
......@@ -11,7 +11,7 @@
-- Portability : non-portable (requires universal quantification for runST)
--
-- This module presents an identical interface to "Control.Monad.ST",
-- except that the monad delays evaluation of state operations until
-- except that the monad delays evaluation of 'ST' operations until
-- a value depending on them is required.
--
-- Unsafe API.
......
......@@ -48,7 +48,7 @@ instance Ord a => Semigroup (Min a) where
instance Ord a => Monoid (Min a) where
mempty = Min Nothing
-- left-to-right state transformer
-- left-to-right state-transforming monad
newtype StateL s a = StateL { runStateL :: s -> (s, a) }
-- | @since 4.0
......@@ -67,7 +67,7 @@ instance Applicative (StateL s) where
(s'', y) = ky s'
in (s'', f x y)
-- right-to-left state transformer
-- right-to-left state-transforming monad
newtype StateR s a = StateR { runStateR :: s -> (s, a) }
-- | @since 4.0
......
......@@ -49,7 +49,7 @@ module GHC.Exts
-- * Ids with special behaviour
lazy, inline, oneShot,
-- * Running 'RealWorld' state transformers
-- * Running 'RealWorld' state thread
runRW#,
-- * Safe coercions
......
......@@ -53,8 +53,8 @@ import {-# SOURCE #-} GHC.IO.Exception ( userError, IOError )
-- The IO Monad
{-
The IO Monad is just an instance of the ST monad, where the state is
the real world. We use the exception mechanism (in GHC.Exception) to
The IO Monad is just an instance of the ST monad, where the state thread
is the real world. We use the exception mechanism (in GHC.Exception) to
implement IO exceptions.
NOTE: The IO representation is deeply wired in to various parts of the
......@@ -84,7 +84,7 @@ failIO s = IO (raiseIO# (toException (userError s)))
-- ---------------------------------------------------------------------------
-- Coercions between IO and ST
-- | Embed a strict state transformer in an 'IO'
-- | 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'.
......@@ -92,20 +92,20 @@ stToIO :: ST RealWorld a -> IO a
stToIO (ST m) = IO m
-- | Convert an 'IO' action into an 'ST' action. The type of the result
-- is constrained to use a 'RealWorld' state, and therefore the result cannot
-- be passed to 'runST'.
-- is constrained to use a 'RealWorld' state thread, and therefore the
-- result cannot be passed to 'runST'.
ioToST :: IO a -> ST RealWorld a
ioToST (IO m) = (ST m)
-- | Convert an 'IO' action to an 'ST' action.
-- This relies on 'IO' and 'ST' having the same representation modulo the
-- constraint on the type of the state.
-- constraint on the state thread type parameter.
unsafeIOToST :: IO a -> ST s a
unsafeIOToST (IO io) = ST $ \ s -> (unsafeCoerce# io) s
-- | Convert an 'ST' action to an 'IO' action.
-- This relies on 'IO' and 'ST' having the same representation modulo the
-- constraint on the type of the state.
-- 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
......
......@@ -30,13 +30,13 @@ import qualified Control.Monad.Fail as Fail
default ()
-- The state-transformer monad proper. By default the monad is strict;
-- The 'ST' monad proper. By default the monad is strict;
-- too many people got bitten by space leaks when it was lazy.
-- | 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
-- | 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
--
......@@ -131,7 +131,7 @@ instance Show (ST s a) where
showList = showList__ (showsPrec 0)
{-# INLINE runST #-}
-- | Return the value computed by a state transformer computation.
-- | 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.
runST :: (forall s. ST s a) -> a
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment