Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Unlifted Control.Exception, with extra async exception safety and more helper functions.
This module works best when your cleanup functions adhere to certain expectations around exception safety and interruptible actions. For more details, see this exception safety tutorial.
Synopsis
- throwIO :: (MonadIO m, Exception e) => e -> m a
- throwString :: (MonadIO m, HasCallStack) => String -> m a
- data StringException = StringException String CallStack
- stringException :: HasCallStack => String -> StringException
- throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
- impureThrow :: Exception e => e -> a
- fromEither :: (Exception e, MonadIO m) => Either e a -> m a
- fromEitherIO :: (Exception e, MonadIO m) => IO (Either e a) -> m a
- fromEitherM :: (Exception e, MonadIO m) => m (Either e a) -> m a
- mapExceptionM :: (Exception e1, Exception e2, MonadUnliftIO m) => (e1 -> e2) -> m a -> m a
- catch :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
- catchIO :: MonadUnliftIO m => m a -> (IOException -> m a) -> m a
- catchAny :: MonadUnliftIO m => m a -> (SomeException -> m a) -> m a
- catchDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
- catchAnyDeep :: (NFData a, MonadUnliftIO m) => m a -> (SomeException -> m a) -> m a
- catchJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- handle :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a
- handleIO :: MonadUnliftIO m => (IOException -> m a) -> m a -> m a
- handleAny :: MonadUnliftIO m => (SomeException -> m a) -> m a -> m a
- handleDeep :: (MonadUnliftIO m, Exception e, NFData a) => (e -> m a) -> m a -> m a
- handleAnyDeep :: (MonadUnliftIO m, NFData a) => (SomeException -> m a) -> m a -> m a
- handleJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- try :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
- tryIO :: MonadUnliftIO m => m a -> m (Either IOException a)
- tryAny :: MonadUnliftIO m => m a -> m (Either SomeException a)
- tryDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> m (Either e a)
- tryAnyDeep :: (MonadUnliftIO m, NFData a) => m a -> m (Either SomeException a)
- tryJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- pureTry :: a -> Either SomeException a
- pureTryDeep :: NFData a => a -> Either SomeException a
- data Handler (m :: Type -> Type) a = Exception e => Handler (e -> m a)
- catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a
- catchesDeep :: (MonadUnliftIO m, NFData a) => m a -> [Handler m a] -> m a
- catchSyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
- handleSyncOrAsync :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a
- trySyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
- onException :: MonadUnliftIO m => m a -> m b -> m a
- bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
- finally :: MonadUnliftIO m => m a -> m b -> m a
- withException :: (MonadUnliftIO m, Exception e) => m a -> (e -> m b) -> m a
- bracketOnError :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracketOnError_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
- data SyncExceptionWrapper = Exception e => SyncExceptionWrapper e
- toSyncException :: Exception e => e -> SomeException
- data AsyncExceptionWrapper = Exception e => AsyncExceptionWrapper e
- toAsyncException :: Exception e => e -> SomeException
- fromExceptionUnwrap :: Exception e => SomeException -> Maybe e
- isSyncException :: Exception e => e -> Bool
- isAsyncException :: Exception e => e -> Bool
- mask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b
- uninterruptibleMask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b
- mask_ :: MonadUnliftIO m => m a -> m a
- uninterruptibleMask_ :: MonadUnliftIO m => m a -> m a
- evaluate :: MonadIO m => a -> m a
- evaluateDeep :: (MonadIO m, NFData a) => a -> m a
- class (Typeable e, Show e) => Exception e where
- toException :: e -> SomeException
- fromException :: SomeException -> Maybe e
- displayException :: e -> String
- class Typeable (a :: k)
- data SomeException = Exception e => SomeException e
- data SomeAsyncException = Exception e => SomeAsyncException e
- data IOException
- assert :: Bool -> a -> a
- asyncExceptionToException :: Exception e => e -> SomeException
- asyncExceptionFromException :: Exception e => SomeException -> Maybe e
Throwing
throwIO :: (MonadIO m, Exception e) => e -> m a Source #
Synchronously throw the given exception.
Note that, if you provide an exception value which is of an asynchronous
type, it will be wrapped up in SyncExceptionWrapper
. See toSyncException
.
Since: 0.1.0.0
throwString :: (MonadIO m, HasCallStack) => String -> m a Source #
A convenience function for throwing a user error. This is useful for cases where it would be too high a burden to define your own exception type.
This throws an exception of type StringException
. When GHC
supports it (base 4.9 and GHC 8.0 and onward), it includes a call
stack.
Since: 0.1.0.0
data StringException Source #
Exception type thrown by throwString
.
Note that the second field of the data constructor depends on GHC/base version. For base 4.9 and GHC 8.0 and later, the second field is a call stack. Previous versions of GHC and base do not support call stacks, and the field is simply unit (provided to make pattern matching across GHC versions easier).
Since: 0.1.0.0
Instances
Exception StringException Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception | |
Show StringException Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception showsPrec :: Int -> StringException -> ShowS # show :: StringException -> String # showList :: [StringException] -> ShowS # | |
Eq StringException Source # | Since: 0.2.19 |
Defined in UnliftIO.Exception (==) :: StringException -> StringException -> Bool # (/=) :: StringException -> StringException -> Bool # |
stringException :: HasCallStack => String -> StringException Source #
Smart constructor for a StringException
that deals with the
call stack.
Since: 0.1.0.0
throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m () Source #
Throw an asynchronous exception to another thread.
Synchronously typed exceptions will be wrapped into an
AsyncExceptionWrapper
, see
https://github.com/fpco/safe-exceptions#determining-sync-vs-async.
It's usually a better idea to use the UnliftIO.Async module, see https://github.com/fpco/safe-exceptions#quickstart.
Since: 0.1.0.0
impureThrow :: Exception e => e -> a Source #
Generate a pure value which, when forced, will synchronously throw the given exception.
Generally it's better to avoid using this function and instead use throwIO
,
see https://github.com/fpco/safe-exceptions#quickstart.
Since: 0.1.0.0
fromEitherIO :: (Exception e, MonadIO m) => IO (Either e a) -> m a Source #
Same as fromEither
, but works on an IO
-wrapped Either
.
Since: 0.1.0.0
fromEitherM :: (Exception e, MonadIO m) => m (Either e a) -> m a Source #
Same as fromEither
, but works on an m
-wrapped Either
.
Since: 0.1.0.0
mapExceptionM :: (Exception e1, Exception e2, MonadUnliftIO m) => (e1 -> e2) -> m a -> m a Source #
Same as mapException
, except works in
a monadic context.
Since: 0.2.15
Catching (with recovery)
:: (MonadUnliftIO m, Exception e) | |
=> m a | action |
-> (e -> m a) | handler |
-> m a |
Catch a synchronous (but not asynchronous) exception and recover from it.
This is parameterized on the exception type. To catch all synchronous exceptions,
use catchAny
.
Since: 0.1.0.0
catchIO :: MonadUnliftIO m => m a -> (IOException -> m a) -> m a Source #
catch
specialized to only catching IOException
s.
Since: 0.1.0.0
catchAny :: MonadUnliftIO m => m a -> (SomeException -> m a) -> m a Source #
catch
specialized to catch all synchronous exceptions.
Since: 0.1.0.0
catchDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a Source #
Same as catch
, but fully force evaluation of the result value
to find all impure exceptions.
Since: 0.1.0.0
catchAnyDeep :: (NFData a, MonadUnliftIO m) => m a -> (SomeException -> m a) -> m a Source #
catchDeep
specialized to catch all synchronous exception.
Since: 0.1.0.0
handle :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a Source #
Flipped version of catch
.
Since: 0.1.0.0
handleIO :: MonadUnliftIO m => (IOException -> m a) -> m a -> m a Source #
handle
specialized to only catching IOException
s.
Since: 0.1.0.0
handleAny :: MonadUnliftIO m => (SomeException -> m a) -> m a -> m a Source #
Flipped version of catchAny
.
Since: 0.1.0.0
handleDeep :: (MonadUnliftIO m, Exception e, NFData a) => (e -> m a) -> m a -> m a Source #
Flipped version of catchDeep
.
Since: 0.1.0.0
handleAnyDeep :: (MonadUnliftIO m, NFData a) => (SomeException -> m a) -> m a -> m a Source #
Flipped version of catchAnyDeep
.
Since: 0.1.0.0
handleJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a Source #
Flipped catchJust
.
Since: 0.1.0.0
tryIO :: MonadUnliftIO m => m a -> m (Either IOException a) Source #
try
specialized to only catching IOException
s.
Since: 0.1.0.0
tryAny :: MonadUnliftIO m => m a -> m (Either SomeException a) Source #
try
specialized to catch all synchronous exceptions.
Since: 0.1.0.0
tryDeep :: (MonadUnliftIO m, Exception e, NFData a) => m a -> m (Either e a) Source #
Same as try
, but fully force evaluation of the result value
to find all impure exceptions.
Since: 0.1.0.0
tryAnyDeep :: (MonadUnliftIO m, NFData a) => m a -> m (Either SomeException a) Source #
tryDeep
specialized to catch all synchronous exceptions.
Since: 0.1.0.0
tryJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a) Source #
A variant of try
that takes an exception predicate to select
which exceptions are caught.
Since: 0.1.0.0
pureTry :: a -> Either SomeException a Source #
Evaluate the value to WHNF and catch any synchronous exceptions.
The expression may still have bottom values within it; you may
instead want to use pureTryDeep
.
Since: 0.2.2.0
pureTryDeep :: NFData a => a -> Either SomeException a Source #
Evaluate the value to NF and catch any synchronous exceptions.
Since: 0.2.2.0
catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a Source #
catchesDeep :: (MonadUnliftIO m, NFData a) => m a -> [Handler m a] -> m a Source #
Same as catches
, but fully force evaluation of the result value
to find all impure exceptions.
Since: 0.1.0.0
Catching async exceptions (with recovery)
catchSyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a Source #
A variant of catch
that catches both synchronous and asynchronous exceptions.
WARNING: This function (and other *SyncOrAsync
functions) is for advanced users. Most of the
time, you probably want to use the non-SyncOrAsync
versions.
Before attempting to use this function, be familiar with the "Rules for async safe handling" section in this blog post.
Since: 0.2.17
handleSyncOrAsync :: (MonadUnliftIO m, Exception e) => (e -> m a) -> m a -> m a Source #
A variant of handle
that catches both synchronous and asynchronous exceptions.
See catchSyncOrAsync
.
Since: 0.2.17
trySyncOrAsync :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a) Source #
A variant of try
that catches both synchronous and asynchronous exceptions.
See catchSyncOrAsync
.
Since: 0.2.17
Cleanup (no recovery)
onException :: MonadUnliftIO m => m a -> m b -> m a Source #
Like finally
, but only call after
if an exception occurs.
Since: 0.1.0.0
bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c Source #
Allocate and clean up a resource safely.
For more information on motivation and usage of this function, see base
's
bracket
. This function has two differences from the one in base
.
The first, and more obvious, is that it works on any MonadUnliftIO
instance, not just IO
.
The more subtle difference is that this function will use uninterruptible masking for its cleanup handler. This is a subtle distinction, but at a high level, means that resource cleanup has more guarantees to complete. This comes at the cost that an incorrectly written cleanup function cannot be interrupted.
For more information, please see https://github.com/fpco/safe-exceptions/issues/3.
Since: 0.1.0.0
bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c Source #
:: MonadUnliftIO m | |
=> m a | thing |
-> m b | after |
-> m a |
withException :: (MonadUnliftIO m, Exception e) => m a -> (e -> m b) -> m a Source #
Like onException
, but provides the handler the thrown
exception.
Since: 0.1.0.0
bracketOnError :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c Source #
Same as bracket
, but only perform the cleanup if an exception is thrown.
Since: 0.1.0.0
bracketOnError_ :: MonadUnliftIO m => m a -> m b -> m c -> m c Source #
A variant of bracketOnError
where the return value from the first
computation is not required.
Since: 0.1.0.0
Coercion to sync and async
In version 0.2.23.0, these were changed with aliases to the values
from Control.Exception.Safe in the safe-exceptions
package.
data SyncExceptionWrapper #
Wrap up an asynchronous exception to be treated as a synchronous exception
This is intended to be created via toSyncException
Since: safe-exceptions-0.1.0.0
Exception e => SyncExceptionWrapper e |
Instances
Exception SyncExceptionWrapper | |
Show SyncExceptionWrapper | |
Defined in Control.Exception.Safe showsPrec :: Int -> SyncExceptionWrapper -> ShowS # show :: SyncExceptionWrapper -> String # showList :: [SyncExceptionWrapper] -> ShowS # |
toSyncException :: Exception e => e -> SomeException Source #
Convert an exception into a synchronous exception.
For synchronous exceptions, this is the same as toException
.
For asynchronous exceptions, this will wrap up the exception with
SyncExceptionWrapper
.
Since: 0.1.0.0
data AsyncExceptionWrapper #
Wrap up a synchronous exception to be treated as an asynchronous exception
This is intended to be created via toAsyncException
Since: safe-exceptions-0.1.0.0
Exception e => AsyncExceptionWrapper e |
Instances
Exception AsyncExceptionWrapper | |
Show AsyncExceptionWrapper | |
Defined in Control.Exception.Safe showsPrec :: Int -> AsyncExceptionWrapper -> ShowS # show :: AsyncExceptionWrapper -> String # showList :: [AsyncExceptionWrapper] -> ShowS # |
toAsyncException :: Exception e => e -> SomeException Source #
Convert an exception into an asynchronous exception.
For asynchronous exceptions, this is the same as toException
.
For synchronous exceptions, this will wrap up the exception with
AsyncExceptionWrapper
.
Since: 0.1.0.0
fromExceptionUnwrap :: Exception e => SomeException -> Maybe e Source #
Convert from a possibly wrapped exception.
The inverse of toAsyncException
and toSyncException
. When using those
functions (or functions that use them, like throwTo
or throwIO
),
fromException
might not be sufficient because the exception might be
wrapped within SyncExceptionWrapper
or AsyncExceptionWrapper
.
Since: 0.2.17
Check exception type
isSyncException :: Exception e => e -> Bool Source #
Check if the given exception is synchronous.
Since: 0.1.0.0
isAsyncException :: Exception e => e -> Bool Source #
Check if the given exception is asynchronous.
Since: 0.1.0.0
Masking
mask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b Source #
Unlifted version of mask
.
Since: 0.1.0.0
uninterruptibleMask :: MonadUnliftIO m => ((forall a. m a -> m a) -> m b) -> m b Source #
Unlifted version of uninterruptibleMask
.
Since: 0.1.0.0
mask_ :: MonadUnliftIO m => m a -> m a Source #
Unlifted version of mask_
.
Since: 0.1.0.0
uninterruptibleMask_ :: MonadUnliftIO m => m a -> m a Source #
Unlifted version of uninterruptibleMask_
.
Since: 0.1.0.0
Evaluation
evaluateDeep :: (MonadIO m, NFData a) => a -> m a Source #
Reexports
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
Nothing
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
The class Typeable
allows a concrete representation of a type to
be calculated.
typeRep#
data SomeException #
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
.
Exception e => SomeException e |
Instances
Exception SomeException | Since: base-3.0 |
Defined in GHC.Exception.Type | |
Show SomeException | Since: base-3.0 |
Defined in GHC.Exception.Type showsPrec :: Int -> SomeException -> ShowS # show :: SomeException -> String # showList :: [SomeException] -> ShowS # |
data SomeAsyncException #
Superclass for asynchronous exceptions.
Since: base-4.7.0.0
Exception e => SomeAsyncException e |
Instances
Exception SomeAsyncException | Since: base-4.7.0.0 |
Defined in GHC.IO.Exception | |
Show SomeAsyncException | Since: base-4.7.0.0 |
Defined in GHC.IO.Exception showsPrec :: Int -> SomeAsyncException -> ShowS # show :: SomeAsyncException -> String # showList :: [SomeAsyncException] -> ShowS # |
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
Exception IOException | Since: base-4.1.0.0 |
Defined in GHC.IO.Exception | |
Show IOException | Since: base-4.1.0.0 |
Defined in GHC.IO.Exception showsPrec :: Int -> IOException -> ShowS # show :: IOException -> String # showList :: [IOException] -> ShowS # | |
Eq IOException | Since: base-4.1.0.0 |
Defined in GHC.IO.Exception (==) :: IOException -> IOException -> Bool # (/=) :: IOException -> IOException -> Bool # | |
Error IOException | |
Defined in Control.Monad.Trans.Error noMsg :: IOException # strMsg :: String -> IOException # |
If the first argument evaluates to True
, then the result is the
second argument. Otherwise an AssertionFailed
exception
is raised, containing a String
with the source file and line number of the
call to assert
.
Assertions can normally be turned on or off with a compiler flag
(for GHC, assertions are normally on unless optimisation is turned on
with -O
or the -fignore-asserts
option is given). When assertions are turned off, the first
argument to assert
is ignored, and the second argument is
returned as the result.
asyncExceptionToException :: Exception e => e -> SomeException #
Since: base-4.7.0.0
asyncExceptionFromException :: Exception e => SomeException -> Maybe e #
Since: base-4.7.0.0