Fix warnings
[ghc-base.git] / GHC / IOBase.lhs
1 \begin{code}
2 {-# OPTIONS_GHC -XNoImplicitPrelude -funbox-strict-fields #-}
3 {-# OPTIONS_HADDOCK hide #-}
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module      :  GHC.IOBase
7 -- Copyright   :  (c) The University of Glasgow 1994-2002
8 -- License     :  see libraries/base/LICENSE
9 -- 
10 -- Maintainer  :  cvs-ghc@haskell.org
11 -- Stability   :  internal
12 -- Portability :  non-portable (GHC Extensions)
13 --
14 -- Definitions for the 'IO' monad and its friends.
15 --
16 -----------------------------------------------------------------------------
17
18 -- #hide
19 module GHC.IOBase(
20     IO(..), unIO, failIO, liftIO, bindIO, thenIO, returnIO, 
21     unsafePerformIO, unsafeInterleaveIO,
22     unsafeDupablePerformIO, unsafeDupableInterleaveIO,
23     noDuplicate,
24
25         -- To and from from ST
26     stToIO, ioToST, unsafeIOToST, unsafeSTToIO,
27
28         -- References
29     IORef(..), newIORef, readIORef, writeIORef, 
30     IOArray(..), newIOArray, readIOArray, writeIOArray, unsafeReadIOArray, unsafeWriteIOArray,
31     MVar(..),
32
33         -- Handles, file descriptors,
34     FilePath,  
35     Handle(..), Handle__(..), HandleType(..), IOMode(..), FD, 
36     isReadableHandleType, isWritableHandleType, isReadWriteHandleType, showHandle,
37
38         -- Buffers
39     Buffer(..), RawBuffer, BufferState(..), BufferList(..), BufferMode(..),
40     bufferIsWritable, bufferEmpty, bufferFull, 
41
42         -- Exceptions
43     Exception(..), ArithException(..), AsyncException(..), ArrayException(..),
44     stackOverflow, heapOverflow, ioException, 
45     IOError, IOException(..), IOErrorType(..), ioError, userError,
46     ExitCode(..),
47     throwIO, block, unblock, blocked, catchAny, catchException,
48     evaluate,
49     ErrorCall(..), AssertionFailed(..), assertError, untangle,
50     BlockedOnDeadMVar(..), BlockedIndefinitely(..), Deadlock(..)
51   ) where
52
53 import GHC.ST
54 import GHC.Arr  -- to derive Ix class
55 import GHC.Enum -- to derive Enum class
56 import GHC.STRef
57 import GHC.Base
58 --  import GHC.Num      -- To get fromInteger etc, needed because of -XNoImplicitPrelude
59 import Data.Maybe  ( Maybe(..) )
60 import GHC.Show
61 import GHC.List
62 import GHC.Read
63 import Foreign.C.Types (CInt)
64 import GHC.Exception
65
66 #ifndef __HADDOCK__
67 import {-# SOURCE #-} Data.Typeable     ( Typeable )
68 import {-# SOURCE #-} Data.Dynamic      ( Dynamic )
69 #endif
70
71 -- ---------------------------------------------------------------------------
72 -- The IO Monad
73
74 {-
75 The IO Monad is just an instance of the ST monad, where the state is
76 the real world.  We use the exception mechanism (in GHC.Exception) to
77 implement IO exceptions.
78
79 NOTE: The IO representation is deeply wired in to various parts of the
80 system.  The following list may or may not be exhaustive:
81
82 Compiler  - types of various primitives in PrimOp.lhs
83
84 RTS       - forceIO (StgMiscClosures.hc)
85           - catchzh_fast, (un)?blockAsyncExceptionszh_fast, raisezh_fast 
86             (Exceptions.hc)
87           - raiseAsync (Schedule.c)
88
89 Prelude   - GHC.IOBase.lhs, and several other places including
90             GHC.Exception.lhs.
91
92 Libraries - parts of hslibs/lang.
93
94 --SDM
95 -}
96
97 {-|
98 A value of type @'IO' a@ is a computation which, when performed,
99 does some I\/O before returning a value of type @a@.  
100
101 There is really only one way to \"perform\" an I\/O action: bind it to
102 @Main.main@ in your program.  When your program is run, the I\/O will
103 be performed.  It isn't possible to perform I\/O from an arbitrary
104 function, unless that function is itself in the 'IO' monad and called
105 at some point, directly or indirectly, from @Main.main@.
106
107 'IO' is a monad, so 'IO' actions can be combined using either the do-notation
108 or the '>>' and '>>=' operations from the 'Monad' class.
109 -}
110 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
111
112 unIO :: IO a -> (State# RealWorld -> (# State# RealWorld, a #))
113 unIO (IO a) = a
114
115 instance  Functor IO where
116    fmap f x = x >>= (return . f)
117
118 instance  Monad IO  where
119     {-# INLINE return #-}
120     {-# INLINE (>>)   #-}
121     {-# INLINE (>>=)  #-}
122     m >> k      =  m >>= \ _ -> k
123     return x    = returnIO x
124
125     m >>= k     = bindIO m k
126     fail s      = failIO s
127
128 failIO :: String -> IO a
129 failIO s = ioError (userError s)
130
131 liftIO :: IO a -> State# RealWorld -> STret RealWorld a
132 liftIO (IO m) = \s -> case m s of (# s', r #) -> STret s' r
133
134 bindIO :: IO a -> (a -> IO b) -> IO b
135 bindIO (IO m) k = IO ( \ s ->
136   case m s of 
137     (# new_s, a #) -> unIO (k a) new_s
138   )
139
140 thenIO :: IO a -> IO b -> IO b
141 thenIO (IO m) k = IO ( \ s ->
142   case m s of 
143     (# new_s, _ #) -> unIO k new_s
144   )
145
146 returnIO :: a -> IO a
147 returnIO x = IO (\ s -> (# s, x #))
148
149 -- ---------------------------------------------------------------------------
150 -- Coercions between IO and ST
151
152 -- | A monad transformer embedding strict state transformers in the 'IO'
153 -- monad.  The 'RealWorld' parameter indicates that the internal state
154 -- used by the 'ST' computation is a special one supplied by the 'IO'
155 -- monad, and thus distinct from those used by invocations of 'runST'.
156 stToIO        :: ST RealWorld a -> IO a
157 stToIO (ST m) = IO m
158
159 ioToST        :: IO a -> ST RealWorld a
160 ioToST (IO m) = (ST m)
161
162 -- This relies on IO and ST having the same representation modulo the
163 -- constraint on the type of the state
164 --
165 unsafeIOToST        :: IO a -> ST s a
166 unsafeIOToST (IO io) = ST $ \ s -> (unsafeCoerce# io) s
167
168 unsafeSTToIO :: ST s a -> IO a
169 unsafeSTToIO (ST m) = IO (unsafeCoerce# m)
170
171 -- ---------------------------------------------------------------------------
172 -- Unsafe IO operations
173
174 {-|
175 This is the \"back door\" into the 'IO' monad, allowing
176 'IO' computation to be performed at any time.  For
177 this to be safe, the 'IO' computation should be
178 free of side effects and independent of its environment.
179
180 If the I\/O computation wrapped in 'unsafePerformIO'
181 performs side effects, then the relative order in which those side
182 effects take place (relative to the main I\/O trunk, or other calls to
183 'unsafePerformIO') is indeterminate.  You have to be careful when 
184 writing and compiling modules that use 'unsafePerformIO':
185
186   * Use @{\-\# NOINLINE foo \#-\}@ as a pragma on any function @foo@
187         that calls 'unsafePerformIO'.  If the call is inlined,
188         the I\/O may be performed more than once.
189
190   * Use the compiler flag @-fno-cse@ to prevent common sub-expression
191         elimination being performed on the module, which might combine
192         two side effects that were meant to be separate.  A good example
193         is using multiple global variables (like @test@ in the example below).
194
195   * Make sure that the either you switch off let-floating, or that the 
196         call to 'unsafePerformIO' cannot float outside a lambda.  For example, 
197         if you say:
198         @
199            f x = unsafePerformIO (newIORef [])
200         @
201         you may get only one reference cell shared between all calls to @f@.
202         Better would be
203         @
204            f x = unsafePerformIO (newIORef [x])
205         @
206         because now it can't float outside the lambda.
207
208 It is less well known that
209 'unsafePerformIO' is not type safe.  For example:
210
211 >     test :: IORef [a]
212 >     test = unsafePerformIO $ newIORef []
213 >     
214 >     main = do
215 >             writeIORef test [42]
216 >             bang <- readIORef test
217 >             print (bang :: [Char])
218
219 This program will core dump.  This problem with polymorphic references
220 is well known in the ML community, and does not arise with normal
221 monadic use of references.  There is no easy way to make it impossible
222 once you use 'unsafePerformIO'.  Indeed, it is
223 possible to write @coerce :: a -> b@ with the
224 help of 'unsafePerformIO'.  So be careful!
225 -}
226 unsafePerformIO :: IO a -> a
227 unsafePerformIO m = unsafeDupablePerformIO (noDuplicate >> m)
228
229 {-| 
230 This version of 'unsafePerformIO' is slightly more efficient,
231 because it omits the check that the IO is only being performed by a
232 single thread.  Hence, when you write 'unsafeDupablePerformIO',
233 there is a possibility that the IO action may be performed multiple
234 times (on a multiprocessor), and you should therefore ensure that
235 it gives the same results each time.
236 -}
237 {-# NOINLINE unsafeDupablePerformIO #-}
238 unsafeDupablePerformIO  :: IO a -> a
239 unsafeDupablePerformIO (IO m) = lazy (case m realWorld# of (# _, r #) -> r)
240
241 -- Why do we NOINLINE unsafeDupablePerformIO?  See the comment with
242 -- GHC.ST.runST.  Essentially the issue is that the IO computation
243 -- inside unsafePerformIO must be atomic: it must either all run, or
244 -- not at all.  If we let the compiler see the application of the IO
245 -- to realWorld#, it might float out part of the IO.
246
247 -- Why is there a call to 'lazy' in unsafeDupablePerformIO?
248 -- If we don't have it, the demand analyser discovers the following strictness
249 -- for unsafeDupablePerformIO:  C(U(AV))
250 -- But then consider
251 --      unsafeDupablePerformIO (\s -> let r = f x in 
252 --                             case writeIORef v r s of (# s1, _ #) ->
253 --                             (# s1, r #)
254 -- The strictness analyser will find that the binding for r is strict,
255 -- (becuase of uPIO's strictness sig), and so it'll evaluate it before 
256 -- doing the writeIORef.  This actually makes tests/lib/should_run/memo002
257 -- get a deadlock!  
258 --
259 -- Solution: don't expose the strictness of unsafeDupablePerformIO,
260 --           by hiding it with 'lazy'
261
262 {-|
263 'unsafeInterleaveIO' allows 'IO' computation to be deferred lazily.
264 When passed a value of type @IO a@, the 'IO' will only be performed
265 when the value of the @a@ is demanded.  This is used to implement lazy
266 file reading, see 'System.IO.hGetContents'.
267 -}
268 {-# INLINE unsafeInterleaveIO #-}
269 unsafeInterleaveIO :: IO a -> IO a
270 unsafeInterleaveIO m = unsafeDupableInterleaveIO (noDuplicate >> m)
271
272 -- We believe that INLINE on unsafeInterleaveIO is safe, because the
273 -- state from this IO thread is passed explicitly to the interleaved
274 -- IO, so it cannot be floated out and shared.
275
276 {-# INLINE unsafeDupableInterleaveIO #-}
277 unsafeDupableInterleaveIO :: IO a -> IO a
278 unsafeDupableInterleaveIO (IO m)
279   = IO ( \ s -> let
280                    r = case m s of (# _, res #) -> res
281                 in
282                 (# s, r #))
283
284 {-| 
285 Ensures that the suspensions under evaluation by the current thread
286 are unique; that is, the current thread is not evaluating anything
287 that is also under evaluation by another thread that has also executed
288 'noDuplicate'.
289
290 This operation is used in the definition of 'unsafePerformIO' to
291 prevent the IO action from being executed multiple times, which is usually
292 undesirable.
293 -}
294 noDuplicate :: IO ()
295 noDuplicate = IO $ \s -> case noDuplicate# s of s' -> (# s', () #)
296
297 -- ---------------------------------------------------------------------------
298 -- Handle type
299
300 data MVar a = MVar (MVar# RealWorld a)
301 {- ^
302 An 'MVar' (pronounced \"em-var\") is a synchronising variable, used
303 for communication between concurrent threads.  It can be thought of
304 as a a box, which may be empty or full.
305 -}
306
307 -- pull in Eq (Mvar a) too, to avoid GHC.Conc being an orphan-instance module
308 instance Eq (MVar a) where
309         (MVar mvar1#) == (MVar mvar2#) = sameMVar# mvar1# mvar2#
310
311 --  A Handle is represented by (a reference to) a record 
312 --  containing the state of the I/O port/device. We record
313 --  the following pieces of info:
314
315 --    * type (read,write,closed etc.)
316 --    * the underlying file descriptor
317 --    * buffering mode 
318 --    * buffer, and spare buffers
319 --    * user-friendly name (usually the
320 --      FilePath used when IO.openFile was called)
321
322 -- Note: when a Handle is garbage collected, we want to flush its buffer
323 -- and close the OS file handle, so as to free up a (precious) resource.
324
325 -- | Haskell defines operations to read and write characters from and to files,
326 -- represented by values of type @Handle@.  Each value of this type is a
327 -- /handle/: a record used by the Haskell run-time system to /manage/ I\/O
328 -- with file system objects.  A handle has at least the following properties:
329 -- 
330 --  * whether it manages input or output or both;
331 --
332 --  * whether it is /open/, /closed/ or /semi-closed/;
333 --
334 --  * whether the object is seekable;
335 --
336 --  * whether buffering is disabled, or enabled on a line or block basis;
337 --
338 --  * a buffer (whose length may be zero).
339 --
340 -- Most handles will also have a current I\/O position indicating where the next
341 -- input or output operation will occur.  A handle is /readable/ if it
342 -- manages only input or both input and output; likewise, it is /writable/ if
343 -- it manages only output or both input and output.  A handle is /open/ when
344 -- first allocated.
345 -- Once it is closed it can no longer be used for either input or output,
346 -- though an implementation cannot re-use its storage while references
347 -- remain to it.  Handles are in the 'Show' and 'Eq' classes.  The string
348 -- produced by showing a handle is system dependent; it should include
349 -- enough information to identify the handle for debugging.  A handle is
350 -- equal according to '==' only to itself; no attempt
351 -- is made to compare the internal state of different handles for equality.
352 --
353 -- GHC note: a 'Handle' will be automatically closed when the garbage
354 -- collector detects that it has become unreferenced by the program.
355 -- However, relying on this behaviour is not generally recommended:
356 -- the garbage collector is unpredictable.  If possible, use explicit
357 -- an explicit 'hClose' to close 'Handle's when they are no longer
358 -- required.  GHC does not currently attempt to free up file
359 -- descriptors when they have run out, it is your responsibility to
360 -- ensure that this doesn't happen.
361
362 data Handle 
363   = FileHandle                          -- A normal handle to a file
364         FilePath                        -- the file (invariant)
365         !(MVar Handle__)
366
367   | DuplexHandle                        -- A handle to a read/write stream
368         FilePath                        -- file for a FIFO, otherwise some
369                                         --   descriptive string.
370         !(MVar Handle__)                -- The read side
371         !(MVar Handle__)                -- The write side
372
373 -- NOTES:
374 --    * A 'FileHandle' is seekable.  A 'DuplexHandle' may or may not be
375 --      seekable.
376
377 instance Eq Handle where
378  (FileHandle _ h1)     == (FileHandle _ h2)     = h1 == h2
379  (DuplexHandle _ h1 _) == (DuplexHandle _ h2 _) = h1 == h2
380  _ == _ = False 
381
382 type FD = CInt
383
384 data Handle__
385   = Handle__ {
386       haFD          :: !FD,                  -- file descriptor
387       haType        :: HandleType,           -- type (read/write/append etc.)
388       haIsBin       :: Bool,                 -- binary mode?
389       haIsStream    :: Bool,                 -- Windows : is this a socket?
390                                              -- Unix    : is O_NONBLOCK set?
391       haBufferMode  :: BufferMode,           -- buffer contains read/write data?
392       haBuffer      :: !(IORef Buffer),      -- the current buffer
393       haBuffers     :: !(IORef BufferList),  -- spare buffers
394       haOtherSide   :: Maybe (MVar Handle__) -- ptr to the write side of a 
395                                              -- duplex handle.
396     }
397
398 -- ---------------------------------------------------------------------------
399 -- Buffers
400
401 -- The buffer is represented by a mutable variable containing a
402 -- record, where the record contains the raw buffer and the start/end
403 -- points of the filled portion.  We use a mutable variable so that
404 -- the common operation of writing (or reading) some data from (to)
405 -- the buffer doesn't need to modify, and hence copy, the handle
406 -- itself, it just updates the buffer.  
407
408 -- There will be some allocation involved in a simple hPutChar in
409 -- order to create the new Buffer structure (below), but this is
410 -- relatively small, and this only has to be done once per write
411 -- operation.
412
413 -- The buffer contains its size - we could also get the size by
414 -- calling sizeOfMutableByteArray# on the raw buffer, but that tends
415 -- to be rounded up to the nearest Word.
416
417 type RawBuffer = MutableByteArray# RealWorld
418
419 -- INVARIANTS on a Buffer:
420 --
421 --   * A handle *always* has a buffer, even if it is only 1 character long
422 --     (an unbuffered handle needs a 1 character buffer in order to support
423 --      hLookAhead and hIsEOF).
424 --   * r <= w
425 --   * if r == w, then r == 0 && w == 0
426 --   * if state == WriteBuffer, then r == 0
427 --   * a write buffer is never full.  If an operation
428 --     fills up the buffer, it will always flush it before 
429 --     returning.
430 --   * a read buffer may be full as a result of hLookAhead.  In normal
431 --     operation, a read buffer always has at least one character of space.
432
433 data Buffer 
434   = Buffer {
435         bufBuf   :: RawBuffer,
436         bufRPtr  :: !Int,
437         bufWPtr  :: !Int,
438         bufSize  :: !Int,
439         bufState :: BufferState
440   }
441
442 data BufferState = ReadBuffer | WriteBuffer deriving (Eq)
443
444 -- we keep a few spare buffers around in a handle to avoid allocating
445 -- a new one for each hPutStr.  These buffers are *guaranteed* to be the
446 -- same size as the main buffer.
447 data BufferList 
448   = BufferListNil 
449   | BufferListCons RawBuffer BufferList
450
451
452 bufferIsWritable :: Buffer -> Bool
453 bufferIsWritable Buffer{ bufState=WriteBuffer } = True
454 bufferIsWritable _other = False
455
456 bufferEmpty :: Buffer -> Bool
457 bufferEmpty Buffer{ bufRPtr=r, bufWPtr=w } = r == w
458
459 -- only makes sense for a write buffer
460 bufferFull :: Buffer -> Bool
461 bufferFull b@Buffer{ bufWPtr=w } = w >= bufSize b
462
463 --  Internally, we classify handles as being one
464 --  of the following:
465
466 data HandleType
467  = ClosedHandle
468  | SemiClosedHandle
469  | ReadHandle
470  | WriteHandle
471  | AppendHandle
472  | ReadWriteHandle
473
474 isReadableHandleType :: HandleType -> Bool
475 isReadableHandleType ReadHandle         = True
476 isReadableHandleType ReadWriteHandle    = True
477 isReadableHandleType _                  = False
478
479 isWritableHandleType :: HandleType -> Bool
480 isWritableHandleType AppendHandle    = True
481 isWritableHandleType WriteHandle     = True
482 isWritableHandleType ReadWriteHandle = True
483 isWritableHandleType _               = False
484
485 isReadWriteHandleType :: HandleType -> Bool
486 isReadWriteHandleType ReadWriteHandle{} = True
487 isReadWriteHandleType _                 = False
488
489 -- | File and directory names are values of type 'String', whose precise
490 -- meaning is operating system dependent. Files can be opened, yielding a
491 -- handle which can then be used to operate on the contents of that file.
492
493 type FilePath = String
494
495 -- ---------------------------------------------------------------------------
496 -- Buffering modes
497
498 -- | Three kinds of buffering are supported: line-buffering, 
499 -- block-buffering or no-buffering.  These modes have the following
500 -- effects. For output, items are written out, or /flushed/,
501 -- from the internal buffer according to the buffer mode:
502 --
503 --  * /line-buffering/: the entire output buffer is flushed
504 --    whenever a newline is output, the buffer overflows, 
505 --    a 'System.IO.hFlush' is issued, or the handle is closed.
506 --
507 --  * /block-buffering/: the entire buffer is written out whenever it
508 --    overflows, a 'System.IO.hFlush' is issued, or the handle is closed.
509 --
510 --  * /no-buffering/: output is written immediately, and never stored
511 --    in the buffer.
512 --
513 -- An implementation is free to flush the buffer more frequently,
514 -- but not less frequently, than specified above.
515 -- The output buffer is emptied as soon as it has been written out.
516 --
517 -- Similarly, input occurs according to the buffer mode for the handle:
518 --
519 --  * /line-buffering/: when the buffer for the handle is not empty,
520 --    the next item is obtained from the buffer; otherwise, when the
521 --    buffer is empty, characters up to and including the next newline
522 --    character are read into the buffer.  No characters are available
523 --    until the newline character is available or the buffer is full.
524 --
525 --  * /block-buffering/: when the buffer for the handle becomes empty,
526 --    the next block of data is read into the buffer.
527 --
528 --  * /no-buffering/: the next input item is read and returned.
529 --    The 'System.IO.hLookAhead' operation implies that even a no-buffered
530 --    handle may require a one-character buffer.
531 --
532 -- The default buffering mode when a handle is opened is
533 -- implementation-dependent and may depend on the file system object
534 -- which is attached to that handle.
535 -- For most implementations, physical files will normally be block-buffered 
536 -- and terminals will normally be line-buffered.
537
538 data BufferMode  
539  = NoBuffering  -- ^ buffering is disabled if possible.
540  | LineBuffering
541                 -- ^ line-buffering should be enabled if possible.
542  | BlockBuffering (Maybe Int)
543                 -- ^ block-buffering should be enabled if possible.
544                 -- The size of the buffer is @n@ items if the argument
545                 -- is 'Just' @n@ and is otherwise implementation-dependent.
546    deriving (Eq, Ord, Read, Show)
547
548 -- ---------------------------------------------------------------------------
549 -- IORefs
550
551 -- |A mutable variable in the 'IO' monad
552 newtype IORef a = IORef (STRef RealWorld a)
553
554 -- explicit instance because Haddock can't figure out a derived one
555 instance Eq (IORef a) where
556   IORef x == IORef y = x == y
557
558 -- |Build a new 'IORef'
559 newIORef    :: a -> IO (IORef a)
560 newIORef v = stToIO (newSTRef v) >>= \ var -> return (IORef var)
561
562 -- |Read the value of an 'IORef'
563 readIORef   :: IORef a -> IO a
564 readIORef  (IORef var) = stToIO (readSTRef var)
565
566 -- |Write a new value into an 'IORef'
567 writeIORef  :: IORef a -> a -> IO ()
568 writeIORef (IORef var) v = stToIO (writeSTRef var v)
569
570 -- ---------------------------------------------------------------------------
571 -- | An 'IOArray' is a mutable, boxed, non-strict array in the 'IO' monad.  
572 -- The type arguments are as follows:
573 --
574 --  * @i@: the index type of the array (should be an instance of 'Ix')
575 --
576 --  * @e@: the element type of the array.
577 --
578 -- 
579
580 newtype IOArray i e = IOArray (STArray RealWorld i e)
581
582 -- explicit instance because Haddock can't figure out a derived one
583 instance Eq (IOArray i e) where
584   IOArray x == IOArray y = x == y
585
586 -- |Build a new 'IOArray'
587 newIOArray :: Ix i => (i,i) -> e -> IO (IOArray i e)
588 {-# INLINE newIOArray #-}
589 newIOArray lu initial  = stToIO $ do {marr <- newSTArray lu initial; return (IOArray marr)}
590
591 -- | Read a value from an 'IOArray'
592 unsafeReadIOArray  :: Ix i => IOArray i e -> Int -> IO e
593 {-# INLINE unsafeReadIOArray #-}
594 unsafeReadIOArray (IOArray marr) i = stToIO (unsafeReadSTArray marr i)
595
596 -- | Write a new value into an 'IOArray'
597 unsafeWriteIOArray :: Ix i => IOArray i e -> Int -> e -> IO ()
598 {-# INLINE unsafeWriteIOArray #-}
599 unsafeWriteIOArray (IOArray marr) i e = stToIO (unsafeWriteSTArray marr i e)
600
601 -- | Read a value from an 'IOArray'
602 readIOArray  :: Ix i => IOArray i e -> i -> IO e
603 readIOArray (IOArray marr) i = stToIO (readSTArray marr i)
604
605 -- | Write a new value into an 'IOArray'
606 writeIOArray :: Ix i => IOArray i e -> i -> e -> IO ()
607 writeIOArray (IOArray marr) i e = stToIO (writeSTArray marr i e)
608
609
610 -- ---------------------------------------------------------------------------
611 -- Show instance for Handles
612
613 -- handle types are 'show'n when printing error msgs, so
614 -- we provide a more user-friendly Show instance for it
615 -- than the derived one.
616
617 instance Show HandleType where
618   showsPrec _ t =
619     case t of
620       ClosedHandle      -> showString "closed"
621       SemiClosedHandle  -> showString "semi-closed"
622       ReadHandle        -> showString "readable"
623       WriteHandle       -> showString "writable"
624       AppendHandle      -> showString "writable (append)"
625       ReadWriteHandle   -> showString "read-writable"
626
627 instance Show Handle where 
628   showsPrec _ (FileHandle   file _)   = showHandle file
629   showsPrec _ (DuplexHandle file _ _) = showHandle file
630
631 showHandle :: FilePath -> String -> String
632 showHandle file = showString "{handle: " . showString file . showString "}"
633
634 -- ------------------------------------------------------------------------
635 -- Exception datatypes and operations
636
637 data ErrorCall = ErrorCall String
638     deriving Typeable
639
640 instance Exception ErrorCall
641
642 instance Show ErrorCall where
643     showsPrec _ (ErrorCall err) = showString err
644
645 -----
646
647 data BlockedOnDeadMVar = BlockedOnDeadMVar
648     deriving Typeable
649
650 instance Exception BlockedOnDeadMVar
651
652 instance Show BlockedOnDeadMVar where
653     showsPrec _ BlockedOnDeadMVar = showString "thread blocked indefinitely"
654
655 -----
656
657 data BlockedIndefinitely = BlockedIndefinitely
658     deriving Typeable
659
660 instance Exception BlockedIndefinitely
661
662 instance Show BlockedIndefinitely where
663     showsPrec _ BlockedIndefinitely = showString "thread blocked indefinitely"
664
665 -----
666
667 data Deadlock = Deadlock
668     deriving Typeable
669
670 instance Exception Deadlock
671
672 instance Show Deadlock where
673     showsPrec _ Deadlock = showString "<<deadlock>>"
674
675 -----
676
677 data AssertionFailed = AssertionFailed String
678     deriving Typeable
679
680 instance Exception AssertionFailed
681
682 instance Show AssertionFailed where
683     showsPrec _ (AssertionFailed err) = showString err
684
685 -----
686
687 -- |The type of arithmetic exceptions
688 data ArithException
689   = Overflow
690   | Underflow
691   | LossOfPrecision
692   | DivideByZero
693   | Denormal
694   deriving (Eq, Ord, Typeable)
695
696 instance Exception ArithException
697
698 -- |Asynchronous exceptions
699 data AsyncException
700   = StackOverflow
701         -- ^The current thread\'s stack exceeded its limit.
702         -- Since an exception has been raised, the thread\'s stack
703         -- will certainly be below its limit again, but the
704         -- programmer should take remedial action
705         -- immediately.
706   | HeapOverflow
707         -- ^The program\'s heap is reaching its limit, and
708         -- the program should take action to reduce the amount of
709         -- live data it has. Notes:
710         --
711         --      * It is undefined which thread receives this exception.
712         --
713         --      * GHC currently does not throw 'HeapOverflow' exceptions.
714   | ThreadKilled
715         -- ^This exception is raised by another thread
716         -- calling 'Control.Concurrent.killThread', or by the system
717         -- if it needs to terminate the thread for some
718         -- reason.
719   | UserInterrupt
720         -- ^This exception is raised by default in the main thread of
721         -- the program when the user requests to terminate the program
722         -- via the usual mechanism(s) (e.g. Control-C in the console).
723   deriving (Eq, Ord, Typeable)
724
725 instance Exception AsyncException
726
727 -- | Exceptions generated by array operations
728 data ArrayException
729   = IndexOutOfBounds    String
730         -- ^An attempt was made to index an array outside
731         -- its declared bounds.
732   | UndefinedElement    String
733         -- ^An attempt was made to evaluate an element of an
734         -- array that had not been initialized.
735   deriving (Eq, Ord, Typeable)
736
737 instance Exception ArrayException
738
739 stackOverflow, heapOverflow :: SomeException -- for the RTS
740 stackOverflow = toException StackOverflow
741 heapOverflow  = toException HeapOverflow
742
743 instance Show ArithException where
744   showsPrec _ Overflow        = showString "arithmetic overflow"
745   showsPrec _ Underflow       = showString "arithmetic underflow"
746   showsPrec _ LossOfPrecision = showString "loss of precision"
747   showsPrec _ DivideByZero    = showString "divide by zero"
748   showsPrec _ Denormal        = showString "denormal"
749
750 instance Show AsyncException where
751   showsPrec _ StackOverflow   = showString "stack overflow"
752   showsPrec _ HeapOverflow    = showString "heap overflow"
753   showsPrec _ ThreadKilled    = showString "thread killed"
754   showsPrec _ UserInterrupt   = showString "user interrupt"
755
756 instance Show ArrayException where
757   showsPrec _ (IndexOutOfBounds s)
758         = showString "array index out of range"
759         . (if not (null s) then showString ": " . showString s
760                            else id)
761   showsPrec _ (UndefinedElement s)
762         = showString "undefined array element"
763         . (if not (null s) then showString ": " . showString s
764                            else id)
765
766 -- -----------------------------------------------------------------------------
767 -- The ExitCode type
768
769 -- We need it here because it is used in ExitException in the
770 -- Exception datatype (above).
771
772 data ExitCode
773   = ExitSuccess -- ^ indicates successful termination;
774   | ExitFailure Int
775                 -- ^ indicates program failure with an exit code.
776                 -- The exact interpretation of the code is
777                 -- operating-system dependent.  In particular, some values
778                 -- may be prohibited (e.g. 0 on a POSIX-compliant system).
779   deriving (Eq, Ord, Read, Show, Typeable)
780
781 instance Exception ExitCode
782
783 ioException     :: IOException -> IO a
784 ioException err = throwIO err
785
786 -- | Raise an 'IOError' in the 'IO' monad.
787 ioError         :: IOError -> IO a 
788 ioError         =  ioException
789
790 -- ---------------------------------------------------------------------------
791 -- IOError type
792
793 -- | The Haskell 98 type for exceptions in the 'IO' monad.
794 -- Any I\/O operation may raise an 'IOError' instead of returning a result.
795 -- For a more general type of exception, including also those that arise
796 -- in pure code, see 'Control.Exception.Exception'.
797 --
798 -- In Haskell 98, this is an opaque type.
799 type IOError = IOException
800
801 -- |Exceptions that occur in the @IO@ monad.
802 -- An @IOException@ records a more specific error type, a descriptive
803 -- string and maybe the handle that was used when the error was
804 -- flagged.
805 data IOException
806  = IOError {
807      ioe_handle   :: Maybe Handle,   -- the handle used by the action flagging 
808                                      -- the error.
809      ioe_type     :: IOErrorType,    -- what it was.
810      ioe_location :: String,         -- location.
811      ioe_description :: String,      -- error type specific information.
812      ioe_filename :: Maybe FilePath  -- filename the error is related to.
813    }
814     deriving Typeable
815
816 instance Exception IOException
817
818 instance Eq IOException where
819   (IOError h1 e1 loc1 str1 fn1) == (IOError h2 e2 loc2 str2 fn2) = 
820     e1==e2 && str1==str2 && h1==h2 && loc1==loc2 && fn1==fn2
821
822 -- | An abstract type that contains a value for each variant of 'IOError'.
823 data IOErrorType
824   -- Haskell 98:
825   = AlreadyExists
826   | NoSuchThing
827   | ResourceBusy
828   | ResourceExhausted
829   | EOF
830   | IllegalOperation
831   | PermissionDenied
832   | UserError
833   -- GHC only:
834   | UnsatisfiedConstraints
835   | SystemError
836   | ProtocolError
837   | OtherError
838   | InvalidArgument
839   | InappropriateType
840   | HardwareFault
841   | UnsupportedOperation
842   | TimeExpired
843   | ResourceVanished
844   | Interrupted
845   | DynIOError Dynamic -- cheap&cheerful extensible IO error type.
846
847 instance Eq IOErrorType where
848    x == y = 
849      case x of
850        DynIOError{} -> False -- from a strictness POV, compatible with a derived Eq inst?
851        _ -> getTag x ==# getTag y
852  
853 instance Show IOErrorType where
854   showsPrec _ e =
855     showString $
856     case e of
857       AlreadyExists     -> "already exists"
858       NoSuchThing       -> "does not exist"
859       ResourceBusy      -> "resource busy"
860       ResourceExhausted -> "resource exhausted"
861       EOF               -> "end of file"
862       IllegalOperation  -> "illegal operation"
863       PermissionDenied  -> "permission denied"
864       UserError         -> "user error"
865       HardwareFault     -> "hardware fault"
866       InappropriateType -> "inappropriate type"
867       Interrupted       -> "interrupted"
868       InvalidArgument   -> "invalid argument"
869       OtherError        -> "failed"
870       ProtocolError     -> "protocol error"
871       ResourceVanished  -> "resource vanished"
872       SystemError       -> "system error"
873       TimeExpired       -> "timeout"
874       UnsatisfiedConstraints -> "unsatisified constraints" -- ultra-precise!
875       UnsupportedOperation -> "unsupported operation"
876       DynIOError{}      -> "unknown IO error"
877
878 -- | Construct an 'IOError' value with a string describing the error.
879 -- The 'fail' method of the 'IO' instance of the 'Monad' class raises a
880 -- 'userError', thus:
881 --
882 -- > instance Monad IO where 
883 -- >   ...
884 -- >   fail s = ioError (userError s)
885 --
886 userError       :: String  -> IOError
887 userError str   =  IOError Nothing UserError "" str Nothing
888
889 -- ---------------------------------------------------------------------------
890 -- Showing IOErrors
891
892 instance Show IOException where
893     showsPrec p (IOError hdl iot loc s fn) =
894       (case fn of
895          Nothing -> case hdl of
896                         Nothing -> id
897                         Just h  -> showsPrec p h . showString ": "
898          Just name -> showString name . showString ": ") .
899       (case loc of
900          "" -> id
901          _  -> showString loc . showString ": ") .
902       showsPrec p iot . 
903       (case s of
904          "" -> id
905          _  -> showString " (" . showString s . showString ")")
906
907 -- -----------------------------------------------------------------------------
908 -- IOMode type
909
910 data IOMode      =  ReadMode | WriteMode | AppendMode | ReadWriteMode
911                     deriving (Eq, Ord, Ix, Enum, Read, Show)
912 \end{code}
913
914 %*********************************************************
915 %*                                                      *
916 \subsection{Primitive catch and throwIO}
917 %*                                                      *
918 %*********************************************************
919
920 catchException used to handle the passing around of the state to the
921 action and the handler.  This turned out to be a bad idea - it meant
922 that we had to wrap both arguments in thunks so they could be entered
923 as normal (remember IO returns an unboxed pair...).
924
925 Now catch# has type
926
927     catch# :: IO a -> (b -> IO a) -> IO a
928
929 (well almost; the compiler doesn't know about the IO newtype so we
930 have to work around that in the definition of catchException below).
931
932 \begin{code}
933 catchException :: Exception e => IO a -> (e -> IO a) -> IO a
934 catchException (IO io) handler = IO $ catch# io handler'
935     where handler' e = case fromException e of
936                        Just e' -> unIO (handler e')
937                        Nothing -> raise# e
938
939 catchAny :: IO a -> (forall e . Exception e => e -> IO a) -> IO a
940 catchAny (IO io) handler = IO $ catch# io handler'
941     where handler' (SomeException e) = unIO (handler e)
942
943 -- | A variant of 'throw' that can be used within the 'IO' monad.
944 --
945 -- Although 'throwIO' has a type that is an instance of the type of 'throw', the
946 -- two functions are subtly different:
947 --
948 -- > throw e   `seq` x  ===> throw e
949 -- > throwIO e `seq` x  ===> x
950 --
951 -- The first example will cause the exception @e@ to be raised,
952 -- whereas the second one won\'t.  In fact, 'throwIO' will only cause
953 -- an exception to be raised when it is used within the 'IO' monad.
954 -- The 'throwIO' variant should be used in preference to 'throw' to
955 -- raise an exception within the 'IO' monad because it guarantees
956 -- ordering with respect to other 'IO' operations, whereas 'throw'
957 -- does not.
958 throwIO :: Exception e => e -> IO a
959 throwIO e = IO (raiseIO# (toException e))
960 \end{code}
961
962
963 %*********************************************************
964 %*                                                      *
965 \subsection{Controlling asynchronous exception delivery}
966 %*                                                      *
967 %*********************************************************
968
969 \begin{code}
970 -- | Applying 'block' to a computation will
971 -- execute that computation with asynchronous exceptions
972 -- /blocked/.  That is, any thread which
973 -- attempts to raise an exception in the current thread with 'Control.Exception.throwTo' will be
974 -- blocked until asynchronous exceptions are enabled again.  There\'s
975 -- no need to worry about re-enabling asynchronous exceptions; that is
976 -- done automatically on exiting the scope of
977 -- 'block'.
978 --
979 -- Threads created by 'Control.Concurrent.forkIO' inherit the blocked
980 -- state from the parent; that is, to start a thread in blocked mode,
981 -- use @block $ forkIO ...@.  This is particularly useful if you need to
982 -- establish an exception handler in the forked thread before any
983 -- asynchronous exceptions are received.
984 block :: IO a -> IO a
985
986 -- | To re-enable asynchronous exceptions inside the scope of
987 -- 'block', 'unblock' can be
988 -- used.  It scopes in exactly the same way, so on exit from
989 -- 'unblock' asynchronous exception delivery will
990 -- be disabled again.
991 unblock :: IO a -> IO a
992
993 block (IO io) = IO $ blockAsyncExceptions# io
994 unblock (IO io) = IO $ unblockAsyncExceptions# io
995
996 -- | returns True if asynchronous exceptions are blocked in the
997 -- current thread.
998 blocked :: IO Bool
999 blocked = IO $ \s -> case asyncExceptionsBlocked# s of
1000                         (# s', i #) -> (# s', i /=# 0# #)
1001 \end{code}
1002
1003 \begin{code}
1004 -- | Forces its argument to be evaluated when the resultant 'IO' action
1005 -- is executed.  It can be used to order evaluation with respect to
1006 -- other 'IO' operations; its semantics are given by
1007 --
1008 -- >   evaluate x `seq` y    ==>  y
1009 -- >   evaluate x `catch` f  ==>  (return $! x) `catch` f
1010 -- >   evaluate x >>= f      ==>  (return $! x) >>= f
1011 --
1012 -- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the
1013 -- same as @(return $! x)@.  A correct definition is
1014 --
1015 -- >   evaluate x = (return $! x) >>= return
1016 --
1017 evaluate :: a -> IO a
1018 evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #)
1019         -- NB. can't write
1020         --      a `seq` (# s, a #)
1021         -- because we can't have an unboxed tuple as a function argument
1022 \end{code}
1023
1024 \begin{code}
1025 assertError :: Addr# -> Bool -> a -> a
1026 assertError str predicate v
1027   | predicate = v
1028   | otherwise = throw (AssertionFailed (untangle str "Assertion failed"))
1029
1030 {-
1031 (untangle coded message) expects "coded" to be of the form
1032         "location|details"
1033 It prints
1034         location message details
1035 -}
1036 untangle :: Addr# -> String -> String
1037 untangle coded message
1038   =  location
1039   ++ ": "
1040   ++ message
1041   ++ details
1042   ++ "\n"
1043   where
1044     coded_str = unpackCStringUtf8# coded
1045
1046     (location, details)
1047       = case (span not_bar coded_str) of { (loc, rest) ->
1048         case rest of
1049           ('|':det) -> (loc, ' ' : det)
1050           _         -> (loc, "")
1051         }
1052     not_bar c = c /= '|'
1053 \end{code}
1054