2 <label id="sec:IOExts">
5 This library provides the following extensions to the IO monad:
8 The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
9 described in <cite id="ImperativeFP">
12 References (aka mutable variables) and mutable arrays (but no form of
16 <tt/openFileEx/ extends the standard <tt/openFile/ action with support
17 for opening binary files.
20 <tt/performGC/ triggers an immediate garbage collection
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.
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!
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:
48 > cache :: (a -> b) -> (a -> b)
49 > cache f = \x -> unsafePerformIO (check x)
51 > ref = unsafePerformIO (newIORef (error "cache", error "cache"))
52 > check x = readIORef ref >>= \ (x',a) ->
53 > if x `unsafePtrEq` x' then
57 > writeIORef ref (x, a) >>
66 fixIO :: (a -> IO a) -> IO a
67 unsafePerformIO :: IO a -> a
68 unsafeInterleaveIO :: IO a -> IO a
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 ()
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)
85 openFileEx :: FilePath -> IOModeEx -> IO Handle
86 data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
88 instance Read IOModeEx
89 instance Show IOModeEx
92 trace :: String -> a -> a
93 unsafePtrEq :: a -> a -> Bool