ghc/docs/libraries/ST.sgml

   1 <sect> <idx/ST/
   2 <label id="sec:ST">
   3 <p>
   4
   5 This library provides support for <em/strict/ state threads, as
   6 described in the PLDI '94 paper by John Launchbury and Simon Peyton
   7 Jones <cite id="LazyStateThreads">.  In addition to the monad <tt/ST/,
   8 it also provides mutable variables <tt/STRef/ and mutable arrays
   9 <tt/STArray/.
  10
  11 <tscreen><verb>
  12 module ST( module ST, module Monad ) where
  13 import Monad
  14
  15 data ST s a        -- abstract type
  16 runST              :: forall a. (forall s. ST s a) -> a
  17 fixST              :: (a -> ST s a) -> ST s a
  18 unsafeInterleaveST :: ST s a -> ST s a
  19 instance Functor (ST s)
  20 instance Monad   (ST s)
  21
  22 data STRef s a     -- mutable variables in state thread s
  23                    -- containing values of type a.
  24 newSTRef           :: a -> ST s (STRef s a)
  25 readSTRef          :: STRef s a -> ST s a
  26 writeSTRef         :: STRef s a -> a -> ST s ()
  27 instance Eq (STRef s a)
  28
  29 data STArray s ix elt -- mutable arrays in state thread s
  30                       -- indexed by values of type ix
  31                       -- containing values of type a.
  32 newSTArray          :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
  33 boundsSTArray       :: Ix ix => STArray s ix elt -> (ix, ix)
  34 readSTArray         :: Ix ix => STArray s ix elt -> ix -> ST s elt
  35 writeSTArray        :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
  36 thawSTArray         :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
  37 freezeSTArray       :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
  38 unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
  39 instance Eq (STArray s ix elt)
  40
  41 unsafeIOToST        :: IO   a -> ST s a
  42 stToIO              :: ST s a -> IO a
  43 </verb></tscreen>
  44
  45 Notes:
  46 <itemize>
  47
  48 <item>
  49 GHC also supports ByteArrays --- these aren't supported by Hugs yet.
  50
  51 <item>
  52 The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
  53 arrays to and from immutable arrays.  Semantically, they are identical
  54 to copying the array and they are usually implemented that way.  The
  55 operation <tt/unsafeFreezeSTArray/ is a faster version of
  56 <tt/freezeSTArray/ which omits the copying step.  It's a safe substitute for
  57 <tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
  58
  59 <!--
  60   <item>
  61      Note that it is possible to install Hugs 1.4 without support for lazy
  62      state threads, and hence the primitives described here may not be
  63      available in all implementations.  Also, in contrast with the
  64      implementation of lazy state threads in previous releases of Hugs and
  65      Gofer, there is no direct relationship between the
  66      <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
  67   -->
  68
  69 <item>
  70 Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
  71 import <tt/LazyST/ (say) and still use the strict instance in those
  72 places where it matters.  GHC implements LazyST and ST using different
  73 types, so this isn't possible.
  74 </item>
  75
  76 <item>
  77 Operations for coercing an <tt/ST/ action into an <tt/IO/ one, and
  78 vice versa are also provided. Notice that coercing an <tt/IO/ action
  79 into an <tt/ST/ action is 'lossy', since any exception raised within the
  80 <tt/IO/ action will not be caught within the <tt/ST/ monad, as it
  81 doesn't support (monadic) exceptions.
  82 </itemize>