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 </verb></tscreen>
  41
  42 Notes:
  43 <itemize>
  44
  45 <item>
  46 GHC also supports ByteArrays --- these aren't supported by Hugs yet.
  47
  48 <item>
  49 The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
  50 arrays to and from immutable arrays.  Semantically, they are identical
  51 to copying the array and they are usually implemented that way.  The
  52 operation <tt/unsafeFreezeSTArray/ is a faster version of
  53 <tt/freezeSTArray/ which omits the copying step.  It's a safe substitute for
  54 <tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
  55
  56 <item>
  57 In the current version of Hugs, the <tt/<idx/runST// operation,
  58 used to specify encapsulation, is implemented as a language construct,
  59 and <tt/runST/ is treated as a keyword.  We plan to change this to match
  60 GHC soon.
  61
  62 <!--
  63   <item>
  64      Note that it is possible to install Hugs 1.4 without support for lazy
  65      state threads, and hence the primitives described here may not be
  66      available in all implementations.  Also, in contrast with the
  67      implementation of lazy state threads in previous releases of Hugs and
  68      Gofer, there is no direct relationship between the
  69      <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
  70   -->
  71
  72 <item>
  73 Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
  74 import <tt/LazyST/ (say) and still use the strict instance in those
  75 places where it matters.  GHC implements LazyST and ST using different
  76 types, so this isn't possible.
  77 </item>
  78
  79 </itemize>