Safe Haskell | Safe |
---|---|
Language | Haskell2010 |
Unlifted Control.Exception, with extra async exception safety and more helper functions.
- 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)
- data Handler m 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
- 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
- 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
- class Typeable k a
- data SomeException :: * where
- data SomeAsyncException :: * where
- 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.5.0
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 async package, 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 throw
,
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
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.1.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.1.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.1.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
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
Exception e => SyncExceptionWrapper e |
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
Exception e => AsyncExceptionWrapper e |
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
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, Typeable) 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 deriving Typeable 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 deriving Typeable 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 (Typeable, 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 MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException)) Caught MismatchedParentheses *Main> throw MismatchedParenthesescatch
e -> putStrLn ("Caught " ++ show (e :: IOException)) *** Exception: MismatchedParentheses
toException :: e -> SomeException #
fromException :: SomeException -> Maybe e #
displayException :: e -> String #
The class Typeable
allows a concrete representation of a type to
be calculated.
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
.
data SomeAsyncException :: * where #
Superclass for asynchronous exceptions.
Since: 4.7.0.0
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.
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.