base-3.0.2.0: Basic librariesContentsIndex
GHC.Exception
Portabilitynon-portable (GHC extensions)
Stabilityinternal
Maintainercvs-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
evaluate :: a -> IO a
data Exception
= ArithException ArithException
| ArrayException ArrayException
| AssertionFailed String
| AsyncException AsyncException
| BlockedOnDeadMVar
| BlockedIndefinitely
| NestedAtomically
| 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 IOErrors 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. System.IO.Error.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 Control.Exception.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 with Control.Exception.throwTo 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.

Threads created by Control.Concurrent.forkIO inherit the blocked state from the parent; that is, to start a thread in blocked mode, use block $ forkIO .... This is particularly useful if you need to establish an exception handler in the forked thread before any asynchronous exceptions are received.

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.
evaluate :: a -> IO a

Forces its argument to be evaluated when the resultant IO action is executed. It can be used to order evaluation with respect to other IO operations; its semantics are given by

   evaluate x `seq` y    ==>  y
   evaluate x `catch` f  ==>  (return $! x) `catch` f
   evaluate x >>= f      ==>  (return $! x) >>= f

Note: the first equation implies that (evaluate x) is not the same as (return $! x). A correct definition is

   evaluate x = (return $! x) >>= return
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 ArithExceptionExceptions raised by arithmetic operations. (NOTE: GHC currently does not throw ArithExceptions except for DivideByZero).
ArrayException ArrayExceptionExceptions raised by array-related operations. (NOTE: GHC currently does not throw ArrayExceptions).
AssertionFailed StringThis 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 AsyncExceptionAsynchronous exceptions (see section on Asynchronous Exceptions: Control.Exception#AsynchronousExceptions).
BlockedOnDeadMVarThe current thread was executing a call to Control.Concurrent.MVar.takeMVar that could never return, because there are no other references to this MVar.
BlockedIndefinitelyThe current thread was waiting to retry an atomic memory transaction that could never become possible to complete because there are no other threads referring to any of the TVars involved.
NestedAtomicallyThe runtime detected an attempt to nest one STM transaction inside another one, presumably due to the use of unsafePeformIO with atomically.
DeadlockThere are no runnable threads, so the program is deadlocked. The Deadlock exception is raised in the main thread only (see also: Control.Concurrent).
DynException DynamicDynamically typed exceptions (see section on Dynamic Exceptions: Control.Exception#DynamicExceptions).
ErrorCall StringThe ErrorCall exception is thrown by error. The String argument of ErrorCall is the string passed to error when it was called.
ExitException ExitCodeThe ExitException exception is thrown by System.Exit.exitWith (and System.Exit.exitFailure). The ExitCode argument is the value passed to System.Exit.exitWith. An unhandled ExitException exception in the main thread will cause the program to be terminated with the given exit code.
IOException IOExceptionThese are the standard IO exceptions generated by Haskell's IO operations. See also System.IO.Error.
NoMethodError StringAn 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.
NonTerminationThe current thread is stuck in an infinite loop. This exception may or may not be thrown when the program is non-terminating.
PatternMatchFail StringA pattern matching failure. The String argument should contain a descriptive message including the function name, source file and line number.
RecConError StringAn 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 StringA 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 StringAn 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.
show/hide Instances
data AsyncException
Asynchronous exceptions
Constructors
StackOverflowThe 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.
ThreadKilledThis exception is raised by another thread calling Control.Concurrent.killThread, or by the system if it needs to terminate the thread for some reason.
show/hide Instances
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
show/hide Instances
data ArithException
The type of arithmetic exceptions
Constructors
Overflow
Underflow
LossOfPrecision
DivideByZero
Denormal
show/hide Instances
data ArrayException
Exceptions generated by array operations
Constructors
IndexOutOfBounds StringAn attempt was made to index an array outside its declared bounds.
UndefinedElement StringAn attempt was made to evaluate an element of an array that had not been initialized.
show/hide Instances
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` x  ===> throw e
 throwIO e `seq` x  ===> x

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 2.2.2