planet-mitchell-0.1.0: Planet Mitchell

Safe HaskellNone
LanguageHaskell2010

Exception

Contents

Synopsis

Throwing exceptions

throwIO :: (MonadIO m, Exception e) => e -> m a #

Synchronously throw the given exception.

Since: unliftio-0.1.0.0

class Monad m => MonadThrow (m :: * -> *) where #

A class for monads in which exceptions may be thrown.

Instances should obey the following law:

throwM e >> x = throwM e

In other words, throwing an exception short-circuits the rest of the monadic computation.

Minimal complete definition

throwM

Methods

throwM :: Exception e => e -> m a #

Throw an exception. Note that this throws when this action is run in the monad m, not when it is applied. It is a generalization of Control.Exception's throwIO.

Should satisfy the law:

throwM e >> f = throwM e
Instances
MonadThrow [] 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> [a] #

MonadThrow Maybe 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> Maybe a #

MonadThrow IO 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> IO a #

MonadThrow Q 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> Q a #

MonadThrow STM 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> STM a #

e ~ SomeException => MonadThrow (Either e) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e0 => e0 -> Either e a #

MonadThrow m => MonadThrow (MaybeT m)

Throws exceptions into the base monad.

Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> MaybeT m a #

MonadThrow m => MonadThrow (ListT m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> ListT m a #

MonadThrow m => MonadThrow (IdentityT m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> IdentityT m a #

MonadThrow m => MonadThrow (ExceptT e m)

Throws exceptions into the base monad.

Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e0 => e0 -> ExceptT e m a #

(Functor f, MonadThrow m) => MonadThrow (FreeT f m) 
Instance details

Defined in Control.Monad.Trans.Free

Methods

throwM :: Exception e => e -> FreeT f m a #

(Error e, MonadThrow m) => MonadThrow (ErrorT e m)

Throws exceptions into the base monad.

Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e0 => e0 -> ErrorT e m a #

(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> WriterT w m a #

MonadThrow m => MonadThrow (StateT s m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> StateT s m a #

SomeException ~ err => MonadThrow (STE err s) 
Instance details

Defined in Control.Monad.STE.Internal

Methods

throwM :: Exception e => e -> STE err s a #

MonadThrow m => MonadThrow (StateT s m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> StateT s m a #

(MonadThrow m, Monoid w) => MonadThrow (WriterT w m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> WriterT w m a #

MonadThrow m => MonadThrow (ReaderT r m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> ReaderT r m a #

MonadThrow m => MonadThrow (ContT r m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> ContT r m a #

(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> RWST r w s m a #

(MonadThrow m, Monoid w) => MonadThrow (RWST r w s m) 
Instance details

Defined in Control.Monad.Catch

Methods

throwM :: Exception e => e -> RWST r w s m a #

Throwing specific exceptions

ioError :: IOError -> IO a #

Raise an IOError in the IO monad.

userError :: String -> IOError #

Construct an IOError value with a string describing the error. The fail method of the IO instance of the Monad class raises a userError, thus:

instance Monad IO where
  ...
  fail s = ioError (userError s)

exitWith :: ExitCode -> IO a #

Computation exitWith code throws ExitCode code. Normally this terminates the program, returning code to the program's caller.

On program termination, the standard Handles stdout and stderr are flushed automatically; any other buffered Handles need to be flushed manually, otherwise the buffered data will be discarded.

A program that fails in any other way is treated as if it had called exitFailure. A program that terminates successfully without calling exitWith explicitly is treated as if it had called exitWith ExitSuccess.

As an ExitCode is not an IOError, exitWith bypasses the error handling in the IO monad and cannot be intercepted by catch from the Prelude. However it is a SomeException, and can be caught using the functions of Control.Exception. This means that cleanup computations added with bracket (from Control.Exception) are also executed properly on exitWith.

Note: in GHC, exitWith should be called from the main program thread in order to exit the process. When called from another thread, exitWith will throw an ExitException as normal, but the exception will not cause the process itself to exit.

exitFailure :: IO a #

The computation exitFailure is equivalent to exitWith (ExitFailure exitfail), where exitfail is implementation-dependent.

exitSuccess :: IO a #

The computation exitSuccess is equivalent to exitWith ExitSuccess, It terminates the program successfully.

die :: String -> IO a #

Write given error message to stderr and terminate with exitFailure.

Since: base-4.8.0.0

Catching exceptions

catch :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a #

Unlifted catch, but will not catch asynchronous exceptions.

Since: unliftio-0.1.0.0

catchAny :: MonadUnliftIO m => m a -> (SomeException -> m a) -> m a #

catch specialized to catch all synchronous exception.

Since: unliftio-0.1.0.0

catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a #

Same as upstream catches, but will not catch asynchronous exceptions.

Since: unliftio-0.1.0.0

data Handler (m :: * -> *) a where #

Generalized version of Handler.

Since: unliftio-0.1.0.0

Constructors

Handler :: Handler m a 

catchJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a #

catchJust is like catch but it takes an extra argument which is an exception predicate, a function which selects which type of exceptions we're interested in.

Since: unliftio-0.1.0.0

handle :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a #

Flipped version of catch.

Since: unliftio-0.1.0.0

handleJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a #

Flipped catchJust.

Since: unliftio-0.1.0.0

try :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a) #

Unlifted try, but will not catch asynchronous exceptions.

Since: unliftio-0.1.0.0

tryAny :: MonadUnliftIO m => m a -> m (Either SomeException a) #

try specialized to catch all synchronous exceptions.

Since: unliftio-0.1.0.0

tryJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a) #

A variant of try that takes an exception predicate to select which exceptions are caught.

Since: unliftio-0.1.0.0

tryIO :: MonadUnliftIO m => m a -> m (Either IOException a) #

try specialized to only catching IOExceptions.

Since: unliftio-0.1.0.0

Cleanup

bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c #

Async safe version of bracket.

Since: unliftio-0.1.0.0

bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c #

Async safe version of bracket_.

Since: unliftio-0.1.0.0

bracketOnError :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c #

Async safe version of bracketOnError.

Since: unliftio-0.1.0.0

finally :: MonadUnliftIO m => m a -> m b -> m a #

Async safe version of finally.

Since: unliftio-0.1.0.0

onException :: MonadUnliftIO m => m a -> m b -> m a #

Async safe version of onException.

Since: unliftio-0.1.0.0

Masking exceptions

data MaskingState #

Describes the behaviour of a thread when an asynchronous exception is received.

Constructors

Unmasked

asynchronous exceptions are unmasked (the normal state)

MaskedInterruptible

the state during mask: asynchronous exceptions are masked, but blocking operations may still be interrupted

MaskedUninterruptible

the state during uninterruptibleMask: asynchronous exceptions are masked, and blocking operations may not be interrupted

Instances
Eq MaskingState 
Instance details

Defined in GHC.IO

Show MaskingState 
Instance details

Defined in GHC.IO

mask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b #

Unlifted version of mask.

Since: unliftio-0.1.0.0

mask_ :: MonadUnliftIO m => m a -> m a #

Unlifted version of mask_.

Since: unliftio-0.1.0.0

uninterruptibleMask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b #

Unlifted version of uninterruptibleMask.

Since: unliftio-0.1.0.0

uninterruptibleMask_ :: MonadUnliftIO m => m a -> m a #

Unlifted version of uninterruptibleMask_.

Since: unliftio-0.1.0.0

getMaskingState :: IO MaskingState #

Returns the MaskingState for the current thread.

interruptible :: IO a -> IO a #

Allow asynchronous exceptions to be raised even inside mask, making the operation interruptible (see the discussion of "Interruptible operations" in Exception).

When called outside mask, or inside uninterruptibleMask, this function has no effect.

Since: base-4.9.0.0

allowInterrupt :: IO () #

When invoked inside mask, this function allows a masked asynchronous exception to be raised, if one exists. It is equivalent to performing an interruptible operation (see #interruptible), but does not involve any actual blocking.

When called outside mask, or inside uninterruptibleMask, this function has no effect.

Since: base-4.4.0.0

Exception types

data SomeException where #

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

Constructors

SomeException :: SomeException 

class (Typeable e, Show e) => Exception e where #

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

Methods

toException :: e -> SomeException #

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

Render this exception value in a human-friendly manner.

Default implementation: show.

Since: base-4.8.0.0

Instances
Exception AsyncCancelled 
Instance details

Defined in Control.Concurrent.Async

Exception ExceptionInLinkedThread 
Instance details

Defined in Control.Concurrent.Async

Exception Void

Since: base-4.8.0.0

Instance details

Defined in Data.Void

Exception PatternMatchFail

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception RecSelError

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception RecConError

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception RecUpdError

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception NoMethodError

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception TypeError

Since: base-4.9.0.0

Instance details

Defined in Control.Exception.Base

Exception NonTermination

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception NestedAtomically

Since: base-4.0

Instance details

Defined in Control.Exception.Base

Exception Dynamic

Since: base-4.0.0.0

Instance details

Defined in Data.Dynamic

Exception BlockedIndefinitelyOnMVar

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception BlockedIndefinitelyOnSTM

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception Deadlock

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception AllocationLimitExceeded

Since: base-4.8.0.0

Instance details

Defined in GHC.IO.Exception

Exception CompactionFailed

Since: base-4.10.0.0

Instance details

Defined in GHC.IO.Exception

Exception AssertionFailed

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception SomeAsyncException

Since: base-4.7.0.0

Instance details

Defined in GHC.IO.Exception

Exception AsyncException

Since: base-4.7.0.0

Instance details

Defined in GHC.IO.Exception

Exception ArrayException

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception FixIOException

Since: base-4.11.0.0

Instance details

Defined in GHC.IO.Exception

Exception ExitCode

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception IOException

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception ErrorCall

Since: base-4.0.0.0

Instance details

Defined in GHC.Exception

Exception ArithException

Since: base-4.0.0.0

Instance details

Defined in GHC.Exception

Exception SomeException

Since: base-3.0

Instance details

Defined in GHC.Exception

Exception DeserialiseFailure 
Instance details

Defined in Codec.CBOR.Read

Exception InvalidPosException 
Instance details

Defined in Text.Megaparsec.Pos

Exception STException 
Instance details

Defined in Control.Monad.STE.Internal

Methods

toException :: STException -> SomeException #

fromException :: SomeException -> Maybe STException #

displayException :: STException -> String #

Exception UnicodeException 
Instance details

Defined in Data.Text.Encoding.Error

Exception ExitCodeException 
Instance details

Defined in System.Process.Typed

Exception ByteStringOutputException 
Instance details

Defined in System.Process.Typed

Exception SyncExceptionWrapper

Since: unliftio-0.1.0.0

Instance details

Defined in UnliftIO.Exception

Exception AsyncExceptionWrapper

Since: unliftio-0.1.0.0

Instance details

Defined in UnliftIO.Exception

Exception StringException

Since: unliftio-0.1.0.0

Instance details

Defined in UnliftIO.Exception

Typeable a => Exception (FieldException a) 
Instance details

Defined in Data.Data.Lens

Methods

toException :: FieldException a -> SomeException #

fromException :: SomeException -> Maybe (FieldException a) #

displayException :: FieldException a -> String #

(Show t, Ord t, ShowToken t, Typeable t, Show e, ShowErrorComponent e, Typeable e) => Exception (ParseError t e) 
Instance details

Defined in Text.Megaparsec.Error

mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a #

This function maps one exception into another as proposed in the paper "A semantics for imprecise exceptions".

data ExitCode #

Defines the exit codes that a program can return.

Constructors

ExitSuccess

indicates successful termination;

ExitFailure Int

indicates program failure with an exit code. The exact interpretation of the code is operating-system dependent. In particular, some values may be prohibited (e.g. 0 on a POSIX-compliant system).

Instances
Eq ExitCode 
Instance details

Defined in GHC.IO.Exception

Ord ExitCode 
Instance details

Defined in GHC.IO.Exception

Read ExitCode 
Instance details

Defined in GHC.IO.Exception

Show ExitCode 
Instance details

Defined in GHC.IO.Exception

Generic ExitCode 
Instance details

Defined in GHC.IO.Exception

Associated Types

type Rep ExitCode :: * -> * #

Methods

from :: ExitCode -> Rep ExitCode x #

to :: Rep ExitCode x -> ExitCode #

Exception ExitCode

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

NFData ExitCode

Since: deepseq-1.4.2.0

Instance details

Defined in Control.DeepSeq

Methods

rnf :: ExitCode -> () #

Serialise ExitCode

Since: serialise-0.2.0.0

Instance details

Defined in Codec.Serialise.Class

type Rep ExitCode 
Instance details

Defined in GHC.IO.Exception

type Rep ExitCode = D1 (MetaData "ExitCode" "GHC.IO.Exception" "base" False) (C1 (MetaCons "ExitSuccess" PrefixI False) (U1 :: * -> *) :+: C1 (MetaCons "ExitFailure" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int)))

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.

Instances
Eq IOException

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Show IOException

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Exception IOException

Since: base-4.1.0.0

Instance details

Defined in GHC.IO.Exception

Error IOException 
Instance details

Defined in Control.Monad.Trans.Error

MonadError IOException IO 
Instance details

Defined in Control.Monad.Error.Class

Methods

throwError :: IOException -> IO a #

catchError :: IO a -> (IOException -> IO a) -> IO a #

Asynchronous exceptions

data SomeAsyncException where #

Superclass for asynchronous exceptions.

Since: base-4.7.0.0

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 throws this to the same thread that receives UserInterrupt, but this may change in the future.
  • The GHC RTS currently can only recover from heap overflow if it detects that an explicit memory limit (set via RTS flags). has been exceeded. Currently, failure to allocate memory from the operating system results in immediate termination of the program.
ThreadKilled

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

UserInterrupt

This exception is raised by default in the main thread of the program when the user requests to terminate the program via the usual mechanism(s) (e.g. Control-C in the console).

asyncExceptionToException :: Exception e => e -> SomeException #

Since: base-4.7.0.0