ghc/docs/libraries/IOExts.sgml

   1 <sect> <idx/IOExts/
   2 <label id="sec:IOExts">
   3 <p>
   4
   5 This library provides the following extensions to the IO monad:
   6 <itemize>
   7 <item>
   8 The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
   9 described in <cite id="ImperativeFP">
  10
  11 <item>
  12 References (aka mutable variables) and mutable arrays (but no form of
  13 mutable byte arrays)
  14
  15 <item>
  16 <tt/openFileEx/ extends the standard <tt/openFile/ action with support
  17 for opening binary files.
  18
  19 <item>
  20 <tt/performGC/ triggers an immediate garbage collection
  21
  22 <item>
  23 When called, <tt/trace/ prints the string in its first argument, and then
  24 returns the second argument as its result.  The <tt/trace/ function is not
  25 referentially transparent, and should only be used for debugging, or for
  26 monitoring execution.
  27
  28 <!--
  29   You should also be warned that, unless you understand some of the
  30   details about the way that Haskell programs are executed, results
  31   obtained using <tt/trace/ can be rather confusing.  For example, the
  32   messages may not appear in the order that you expect.  Even ignoring the
  33   output that they produce, adding calls to <tt/trace/ can change the
  34   semantics of your program.  Consider this a warning!
  35   -->
  36
  37 <item>
  38 <tt/unsafePtrEq/ compares two values for pointer equality without
  39 evaluating them.  The results are not referentially transparent and
  40 may vary significantly from one compiler to another or in the face of
  41 semantics-preserving program changes.  However, pointer equality is useful
  42 in creating a number of referentially transparent constructs such as this
  43 simplified memoisation function:
  44
  45 <tscreen><verb>
  46 > cache :: (a -> b) -> (a -> b)
  47 > cache f = \x -> unsafePerformIO (check x)
  48 >  where
  49 >   ref = unsafePerformIO (newIORef (error "cache", error "cache"))
  50 >   check x = readIORef ref >>= \ (x',a) ->
  51 >              if x `unsafePtrEq` x' then
  52 >                return a
  53 >              else
  54 >                let a = f x in
  55 >                writeIORef ref (x, a) >>
  56 >                return a
  57 </verb></tscreen>
  58
  59 <item>
  60 Operations for coercing an <tt/ST/ action into an <tt/IO/ one, and
  61 vice versa are also provided. Notice that coercing an <tt/IO action
  62 into an <tt/ST/ action is 'lossy', since any exception raised within the
  63 <tt/IO/ action will not be caught within the <tt/ST/ monad, as it
  64 doesn't support (monadic) exceptions.
  65 </itemize>
  66
  67 <tscreen><verb>
  68 module IOExts where
  69
  70 fixIO               :: (a -> IO a) -> IO a
  71 unsafePerformIO     :: IO a -> a
  72 unsafeInterleaveIO  :: IO a -> IO a
  73
  74 data IORef a        -- mutable variables containing values of type a
  75 newIORef            :: a -> IO (IORef a)
  76 readIORef           :: IORef a -> IO a
  77 writeIORef          :: IORef a -> a -> IO ()
  78 instance Eq (IORef a)
  79
  80 data IOArray ix elt -- mutable arrays indexed by values of type ix
  81                     -- containing values of type a.
  82 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
  83 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
  84 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
  85 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
  86 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
  87 instance Eq (IOArray ix elt)
  88
  89 openFileEx          :: FilePath -> IOModeEx -> IO Handle
  90 data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
  91 instance Eq IOModeEx
  92 instance Read IOModeEx
  93 instance Show IOModeEx
  94
  95 performGC           :: IO ()
  96 trace               :: String -> a -> a
  97 unsafePtrEq         :: a -> a -> Bool
  98
  99 unsafeIOToST        :: IO   a -> ST s a
 100 stToIO              :: ST s a -> IO a
 101 </verb></tscreen>
 102