Safe Haskell | None |
---|---|
Language | Haskell2010 |
UnliftIO.Exception
Description
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
- 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 a = forall e.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
- 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 = forall e.Exception e => SyncExceptionWrapper e
- toSyncException :: Exception e => e -> SomeException
- data AsyncExceptionWrapper = forall e.Exception e => AsyncExceptionWrapper e
- toAsyncException :: Exception e => e -> SomeException
- 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
Throwing
throwIO :: (MonadIO m, Exception e) => e -> m a Source #
Synchronously throw the given exception.
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
Constructors
StringException String CallStack |
Instances
Show StringException Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods showsPrec :: Int -> StringException -> ShowS show :: StringException -> String showList :: [StringException] -> ShowS | |
Exception StringException Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods toException :: StringException -> SomeException # fromException :: SomeException -> Maybe StringException # displayException :: StringException -> String # |
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
fromEither :: (Exception e, MonadIO m) => Either e a -> m a Source #
Unwrap an Either
value, throwing its Left
value as a runtime
exception via throwIO
if present.
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
Catching (with recovery)
catch :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a Source #
Unlifted catch
, but will not catch asynchronous exceptions.
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 exception.
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
try :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a) Source #
Unlifted try
, but will not catch asynchronous exceptions.
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
Generalized version of Handler
.
Since: 0.1.0.0
catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a Source #
Same as upstream catches
, but will not catch
asynchronous exceptions.
Since: 0.1.0.0
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
Cleanup (no recovery)
onException :: MonadUnliftIO m => m a -> m b -> m a Source #
Async safe version of onException
.
Since: 0.1.0.0
bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c Source #
Async safe version of bracket
.
Since: 0.1.0.0
bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c Source #
Async safe version of bracket_
.
Since: 0.1.0.0
finally :: MonadUnliftIO m => m a -> m b -> m a Source #
Async safe version of finally
.
Since: 0.1.0.0
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 #
Async safe version of bracketOnError
.
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
data SyncExceptionWrapper Source #
Wrap up an asynchronous exception to be treated as a synchronous exception.
This is intended to be created via toSyncException
.
Since: 0.1.0.0
Constructors
forall e.Exception e => SyncExceptionWrapper e |
Instances
Show SyncExceptionWrapper Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods showsPrec :: Int -> SyncExceptionWrapper -> ShowS show :: SyncExceptionWrapper -> String showList :: [SyncExceptionWrapper] -> ShowS | |
Exception SyncExceptionWrapper Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods toException :: SyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe SyncExceptionWrapper # displayException :: SyncExceptionWrapper -> String # |
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 Source #
Wrap up a synchronous exception to be treated as an asynchronous exception.
This is intended to be created via toAsyncException
.
Since: 0.1.0.0
Constructors
forall e.Exception e => AsyncExceptionWrapper e |
Instances
Show AsyncExceptionWrapper Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods showsPrec :: Int -> AsyncExceptionWrapper -> ShowS show :: AsyncExceptionWrapper -> String showList :: [AsyncExceptionWrapper] -> ShowS | |
Exception AsyncExceptionWrapper Source # | Since: 0.1.0.0 |
Defined in UnliftIO.Exception Methods toException :: AsyncExceptionWrapper -> SomeException # fromException :: SomeException -> Maybe AsyncExceptionWrapper # displayException :: AsyncExceptionWrapper -> String # |
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
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
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 #
Deeply evaluate a value using evaluate
and NFData
.
Since: 0.1.0.0
Reexports
class (Typeable e, Show e) => Exception e where #
Minimal complete definition
Nothing
Methods
toException :: e -> SomeException #
fromException :: SomeException -> Maybe e #
displayException :: e -> String #
Instances
data SomeException #
Constructors
Exception e => SomeException e |
Instances
Show SomeException | |
Defined in GHC.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS show :: SomeException -> String showList :: [SomeException] -> ShowS | |
Exception SomeException | |
Defined in GHC.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # |
data SomeAsyncException #
Constructors
Exception e => SomeAsyncException e |
Instances
Show SomeAsyncException | |
Defined in GHC.IO.Exception Methods showsPrec :: Int -> SomeAsyncException -> ShowS show :: SomeAsyncException -> String showList :: [SomeAsyncException] -> ShowS | |
Exception SomeAsyncException | |
Defined in GHC.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String # |
data IOException #
Instances
Eq IOException | |
Defined in GHC.IO.Exception | |
Show IOException | |
Defined in GHC.IO.Exception Methods showsPrec :: Int -> IOException -> ShowS show :: IOException -> String showList :: [IOException] -> ShowS | |
Exception IOException | |
Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # |