| Haskell Hierarchical Libraries (base package) | Contents | Index

GHC.Exception

Portability | non-portable (GHC extensions)
Stability | internal
Maintainer | cvs-ghc@haskell.org

Description
Exceptions and exception-handling functions.
Synopsis

catchException :: IO a -> (Exception -> IO a) -> IO a
catch :: IO a -> (IOError -> IO a) -> IO a
block :: IO a -> IO a
unblock :: IO a -> IO a

data Exception

= ArithException ArithException
| ArrayException ArrayException
| AssertionFailed String
| AsyncException AsyncException
| BlockedOnDeadMVar
| Deadlock
| DynException Dynamic
| ErrorCall String
| ExitException ExitCode
| IOException IOException
| NoMethodError String
| NonTermination
| PatternMatchFail String
| RecConError String
| RecSelError String
| RecUpdError String

data AsyncException

= StackOverflow
| HeapOverflow
| ThreadKilled

data IOException = IOError {

ioe_handle :: (Maybe Handle)
ioe_type :: IOErrorType
ioe_location :: String
ioe_description :: String
ioe_filename :: (Maybe FilePath)

}

data ArithException

= Overflow
| Underflow
| LossOfPrecision
| DivideByZero
| Denormal

data ArrayException

= IndexOutOfBounds String
| UndefinedElement String

throw :: Exception -> a
throwIO :: Exception -> IO a
ioError :: IOError -> IO a

Documentation
catchException :: IO a -> (Exception -> IO a) -> IO a
catch :: IO a -> (IOError -> IO a) -> IO a

The `catch` function establishes a handler that receives any `IOError` raised in the action protected by `catch`. An `IOError` is caught by the most recent handler established by `catch`. These handlers are not selective: all `IOError`s are caught. Exception propagation must be explicitly provided in a handler by re-raising any unwanted exceptions. For example, in

     f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)

the function `f` returns `[]` when an end-of-file exception (cf. `isEOFError`) occurs in `g`; otherwise, the exception is propagated to the next outer handler.

When an exception propagates outside the main program, the Haskell system prints the associated `IOError` value and exits the program.

Non-I/O exceptions are not caught by this variant; to catch all exceptions, use `catch` from Control.Exception.

block :: IO a -> IO a
Applying `block` to a computation will execute that computation with asynchronous exceptions blocked. That is, any thread which attempts to raise an exception in the current thread will be blocked until asynchronous exceptions are enabled again. There's no need to worry about re-enabling asynchronous exceptions; that is done automatically on exiting the scope of `block`.
unblock :: IO a -> IO a
To re-enable asynchronous exceptions inside the scope of `block`, `unblock` can be used. It scopes in exactly the same way, so on exit from `unblock` asynchronous exception delivery will be disabled again.
data Exception

The type of exceptions. Every kind of system-generated exception has a constructor in the `Exception` type, and values of other types may be injected into `Exception` by coercing them to `Dynamic` (see the section on Dynamic Exceptions: Control.Exception#DynamicExceptions).
Constructors

ArithException ArithException | Exceptions raised by arithmetic operations. (NOTE: GHC currently does not throw `ArithException`s except for `DivideByZero`).
ArrayException ArrayException | Exceptions raised by array-related operations. (NOTE: GHC currently does not throw `ArrayException`s).
AssertionFailed String | This exception is thrown by the `assert` operation when the condition fails. The `String` argument contains the location of the assertion in the source program.
AsyncException AsyncException | Asynchronous exceptions (see section on Asynchronous Exceptions: Control.Exception#AsynchronousExceptions).
BlockedOnDeadMVar | The current thread was executing a call to `takeMVar` that could never return, because there are no other references to this `MVar`.
Deadlock | There are no runnable threads, so the program is deadlocked. The `Deadlock` exception is raised in the main thread only (see also: Control.Concurrent).
DynException Dynamic | Dynamically typed exceptions (see section on Dynamic Exceptions: Control.Exception#DynamicExceptions).
ErrorCall String | The `ErrorCall` exception is thrown by `error`. The `String` argument of `ErrorCall` is the string passed to `error` when it was called.
ExitException ExitCode | The `ExitException` exception is thrown by `exitWith` (and `exitFailure`). The `ExitCode` argument is the value passed to `exitWith`. An unhandled `ExitException` exception in the main thread will cause the program to be terminated with the given exit code.
IOException IOException | These are the standard IO exceptions generated by Haskell's `IO` operations. See also System.IO.Error.
NoMethodError String | An attempt was made to invoke a class method which has no definition in this instance, and there was no default definition given in the class declaration. GHC issues a warning when you compile an instance which has missing methods.
NonTermination | The current thread is stuck in an infinite loop. This exception may or may not be thrown when the program is non-terminating.
PatternMatchFail String | A pattern matching failure. The `String` argument should contain a descriptive message including the function name, source file and line number.
RecConError String | An attempt was made to evaluate a field of a record for which no value was given at construction time. The `String` argument gives the location of the record construction in the source program.
RecSelError String | A field selection was attempted on a constructor that doesn't have the requested field. This can happen with multi-constructor records when one or more fields are missing from some of the constructors. The `String` argument gives the location of the record selection in the source program.
RecUpdError String | An attempt was made to update a field in a record, where the record doesn't have the requested field. This can only occur with multi-constructor records, when one or more fields are missing from some of the constructors. The `String` argument gives the location of the record update in the source program.

Instances

Typeable Exception
Show Exception
Eq Exception

data AsyncException

Asynchronous exceptions
Constructors

StackOverflow | The current thread's stack exceeded its limit. Since an exception has been raised, the thread's stack will certainly be below its limit again, but the programmer should take remedial action immediately.

HeapOverflow

The program's heap is reaching its limit, and the program should take action to reduce the amount of live data it has. Notes:

- It is undefined which thread receives this exception.
- GHC currently does not throw `HeapOverflow` exceptions.

ThreadKilled | This exception is raised by another thread calling `killThread`, or by the system if it needs to terminate the thread for some reason.

Instances

Typeable AsyncException
Show AsyncException
Eq AsyncException
Ord AsyncException

data IOException

Exceptions that occur in the `IO` monad. An `IOException` records a more specific error type, a descriptive string and maybe the handle that was used when the error was flagged.
Constructors

IOError |

ioe_handle :: (Maybe Handle) |
ioe_type :: IOErrorType |
ioe_location :: String |
ioe_description :: String |
ioe_filename :: (Maybe FilePath) |

Instances

Typeable IOException
Eq IOException
Show IOException

data ArithException

The type of arithmetic exceptions
Constructors

Overflow |
Underflow |
LossOfPrecision |
DivideByZero |
Denormal |

Instances

Typeable ArithException
Show ArithException
Eq ArithException
Ord ArithException

data ArrayException

Exceptions generated by array operations
Constructors

IndexOutOfBounds String | An attempt was made to index an array outside its declared bounds.
UndefinedElement String | An attempt was made to evaluate an element of an array that had not been initialized.

Instances

Typeable ArrayException
Show ArrayException
Eq ArrayException
Ord ArrayException

throw :: Exception -> a
Throw an exception. Exceptions may be thrown from purely functional code, but may only be caught within the `IO` monad.
throwIO :: Exception -> IO a

A variant of `throw` that can be used within the `IO` monad.

Although `throwIO` has a type that is an instance of the type of `throw`, the two functions are subtly different:

     throw e   `seq` return ()  ===> throw e
     throwIO e `seq` return ()  ===> return ()

The first example will cause the exception `e` to be raised, whereas the second one won't. In fact, `throwIO` will only cause an exception to be raised when it is used within the `IO` monad. The `throwIO` variant should be used in preference to `throw` to raise an exception within the `IO` monad because it guarantees ordering with respect to other `IO` operations, whereas `throw` does not.

ioError :: IOError -> IO a
Raise an `IOError` in the `IO` monad.
Produced by Haddock version 0.6