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
  60 </itemize>
  61
  62 <tscreen><verb>
  63 module IOExts where
  64
  65 fixIO               :: (a -> IO a) -> IO a
  66 unsafePerformIO     :: IO a -> a
  67 unsafeInterleaveIO  :: IO a -> IO a
  68
  69 data IORef a        -- mutable variables containing values of type a
  70 newIORef            :: a -> IO (IORef a)
  71 readIORef           :: IORef a -> IO a
  72 writeIORef          :: IORef a -> a -> IO ()
  73 instance Eq (IORef a)
  74
  75 data IOArray ix elt -- mutable arrays indexed by values of type ix
  76                     -- containing values of type a.
  77 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
  78 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
  79 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
  80 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
  81 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
  82 instance Eq (IOArray ix elt)
  83
  84 openFileEx          :: FilePath -> IOModeEx -> IO Handle
  85 data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
  86 instance Eq IOModeEx
  87 instance Read IOModeEx
  88 instance Show IOModeEx
  89
  90 performGC           :: IO ()
  91 trace               :: String -> a -> a
  92 unsafePtrEq         :: a -> a -> Bool
  93 </verb></tscreen>
  94