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 to
  24 standard error, before returning the second argument as its result.
  25 The <tt/trace/ function is not referentially transparent, and should
  26 only be used for debugging, or for monitoring execution. Some
  27 implementations of <tt/trace/ may decorate the string that's output
  28 to indicate that you're tracing.
  29
  30 <!--
  31   You should also be warned that, unless you understand some of the
  32   details about the way that Haskell programs are executed, results
  33   obtained using <tt/trace/ can be rather confusing.  For example, the
  34   messages may not appear in the order that you expect.  Even ignoring the
  35   output that they produce, adding calls to <tt/trace/ can change the
  36   semantics of your program.  Consider this a warning!
  37   -->
  38
  39 <item>
  40 <tt/unsafePtrEq/ compares two values for pointer equality without
  41 evaluating them.  The results are not referentially transparent and
  42 may vary significantly from one compiler to another or in the face of
  43 semantics-preserving program changes.  However, pointer equality is useful
  44 in creating a number of referentially transparent constructs such as this
  45 simplified memoisation function:
  46
  47 <tscreen><verb>
  48 > cache :: (a -> b) -> (a -> b)
  49 > cache f = \x -> unsafePerformIO (check x)
  50 >  where
  51 >   ref = unsafePerformIO (newIORef (error "cache", error "cache"))
  52 >   check x = readIORef ref >>= \ (x',a) ->
  53 >              if x `unsafePtrEq` x' then
  54 >                return a
  55 >              else
  56 >                let a = f x in
  57 >                writeIORef ref (x, a) >>
  58 >                return a
  59 </verb></tscreen>
  60
  61 </itemize>
  62
  63 <tscreen><verb>
  64 module IOExts where
  65
  66 fixIO               :: (a -> IO a) -> IO a
  67 unsafePerformIO     :: IO a -> a
  68 unsafeInterleaveIO  :: IO a -> IO a
  69
  70 data IORef a        -- mutable variables containing values of type a
  71 newIORef            :: a -> IO (IORef a)
  72 readIORef           :: IORef a -> IO a
  73 writeIORef          :: IORef a -> a -> IO ()
  74 instance Eq (IORef a)
  75
  76 data IOArray ix elt -- mutable arrays indexed by values of type ix
  77                     -- containing values of type a.
  78 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
  79 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
  80 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
  81 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
  82 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
  83 instance Eq (IOArray ix elt)
  84
  85 openFileEx          :: FilePath -> IOModeEx -> IO Handle
  86 data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
  87 instance Eq IOModeEx
  88 instance Read IOModeEx
  89 instance Show IOModeEx
  90
  91 performGC           :: IO ()
  92 trace               :: String -> a -> a
  93 unsafePtrEq         :: a -> a -> Bool
  94
  95 </verb></tscreen>
  96