-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Safe, consistent, and easy exception handling
--
-- Please see README.md
@package safe-exceptions
@version 0.1.2.0
-- | Please see the README.md file in the safe-exceptions repo for
-- information on how to use this module. Relevant links:
--
--
module Control.Exception.Safe
-- | Synchronously throw the given exception
throw :: (MonadThrow m, Exception e) => e -> m a
-- | Synonym for throw
throwIO :: (MonadThrow m, Exception e) => e -> m a
-- | Synonym for throw
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | Throw an asynchronous exception to another thread
--
-- It's usually a better idea to use the async package, see
-- https://github.com/fpco/safe-exceptions#quickstart
throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
-- | 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
impureThrow :: Exception e => e -> a
-- | Same as upstream catch, but will not catch asynchronous
-- exceptions
catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
-- | catch specialized to catch all synchronous exception
catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a
-- | Same as catch, but fully force evaluation of the result value
-- to find all impure exceptions.
catchDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
-- | catchDeep specialized to catch all synchronous exception
catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a
-- | catch without async exception safety
--
-- Generally it's better to avoid using this function since we do not
-- want to recover from async exceptions, see
-- https://github.com/fpco/safe-exceptions#quickstart
catchAsync :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
-- | Flipped version of catch
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
-- | Flipped version of catchAny
handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a
-- | Flipped version of catchDeep
handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a
-- | Flipped version of catchAnyDeep
handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a
-- | Flipped version of catchAsync
--
-- Generally it's better to avoid using this function since we do not
-- want to recover from async exceptions, see
-- https://github.com/fpco/safe-exceptions#quickstart
handleAsync :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
-- | Same as upstream try, but will not catch asynchronous
-- exceptions
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)
-- | try specialized to catch all synchronous exceptions
tryAny :: MonadCatch m => m a -> m (Either SomeException a)
-- | Same as try, but fully force evaluation of the result value to
-- find all impure exceptions.
tryDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> m (Either e a)
-- | tryDeep specialized to catch all synchronous exceptions
tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a)
-- | try without async exception safety
--
-- Generally it's better to avoid using this function since we do not
-- want to recover from async exceptions, see
-- https://github.com/fpco/safe-exceptions#quickstart
tryAsync :: (MonadCatch m, Exception e) => m a -> m (Either e a)
-- | You need this when using catches.
data Handler m a
Handler :: (e -> m a) -> Handler m a
-- | Same as upstream catches, but will not catch asynchronous
-- exceptions
catches :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a
-- | Same as catches, but fully force evaluation of the result value
-- to find all impure exceptions.
catchesDeep :: (MonadCatch m, MonadThrow m, MonadIO m, NFData a) => m a -> [Handler m a] -> m a
-- | catches without async exception safety
--
-- Generally it's better to avoid using this function since we do not
-- want to recover from async exceptions, see
-- https://github.com/fpco/safe-exceptions#quickstart
catchesAsync :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a
-- | Async safe version of onException
onException :: MonadMask m => m a -> m b -> m a
-- | Async safe version of bracket
bracket :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Async safe version of bracket_
bracket_ :: MonadMask m => m a -> m b -> m c -> m c
-- | Async safe version of finally
finally :: MonadMask m => m a -> m b -> m a
-- | Like onException, but provides the handler the thrown
-- exception.
withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a
-- | Async safe version of bracketOnError
bracketOnError :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Async safe version of bracketOnError_
bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c
-- | Wrap up an asynchronous exception to be treated as a synchronous
-- exception
--
-- This is intended to be created via toSyncException
data SyncExceptionWrapper
SyncExceptionWrapper :: e -> SyncExceptionWrapper
-- | 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
toSyncException :: Exception e => e -> SomeException
-- | Wrap up a synchronous exception to be treated as an asynchronous
-- exception
--
-- This is intended to be created via toAsyncException
data AsyncExceptionWrapper
AsyncExceptionWrapper :: e -> AsyncExceptionWrapper
-- | 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
toAsyncException :: Exception e => e -> SomeException
-- | Check if the given exception is synchronous
isSyncException :: Exception e => e -> Bool
-- | Check if the given exception is asynchronous
isAsyncException :: Exception e => e -> Bool
-- | 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.
class Monad m => MonadThrow (m :: * -> *)
-- | A class for monads which allow exceptions to be caught, in particular
-- exceptions which were thrown by throwM.
--
-- Instances should obey the following law:
--
--
-- catch (throwM e) f = f e
--
--
-- Note that the ability to catch an exception does not guarantee
-- that we can deal with all possible exit points from a computation.
-- Some monads, such as continuation-based stacks, allow for more than
-- just a success/failure strategy, and therefore catch
-- cannot be used by those monads to properly implement a function
-- such as finally. For more information, see MonadMask.
class MonadThrow m => MonadCatch (m :: * -> *)
-- | A class for monads which provide for the ability to account for all
-- possible exit points from a computation, and to mask asynchronous
-- exceptions. Continuation-based monads, and stacks such as ErrorT e
-- IO which provide for multiple failure modes, are invalid
-- instances of this class.
--
-- Note that this package does provide a MonadMask
-- instance for CatchT. This instance is only valid if
-- the base monad provides no ability to provide multiple exit. For
-- example, IO or Either would be invalid base monads,
-- but Reader or State would be acceptable.
--
-- Instances should ensure that, in the following code:
--
--
-- f `finally` g
--
--
-- The action g is called regardless of what occurs within
-- f, including async exceptions.
class MonadCatch m => MonadMask (m :: * -> *)
-- | Runs an action with asynchronous exceptions disabled. The action is
-- provided a method for restoring the async. environment to what it was
-- at the mask call. See Control.Exception's mask.
mask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b
-- | Like mask, but the masked computation is not interruptible (see
-- Control.Exception's uninterruptibleMask. WARNING: Only
-- use if you need to mask exceptions around an interruptible operation
-- AND you can guarantee the interruptible operation will only block for
-- a short period of time. Otherwise you render the program/thread
-- unresponsive and/or unkillable.
uninterruptibleMask :: MonadMask m => ((forall a. m a -> m a) -> m b) -> m b
-- | Like mask, but does not pass a restore action to the
-- argument.
mask_ :: MonadMask m => m a -> m a
-- | Like uninterruptibleMask, but does not pass a restore
-- action to the argument.
uninterruptibleMask_ :: MonadMask m => m a -> m a
-- | Catch all IOError (eqv. IOException) exceptions. Still
-- somewhat too general, but better than using catchAll. See
-- catchIf for an easy way of catching specific IOErrors
-- based on the predicates in System.IO.Error.
catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a
-- | Flipped catchIOError
handleIOError :: MonadCatch m => (IOError -> m a) -> m a -> m a
-- | 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 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
--
class (Typeable * e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
-- | Render this exception value in a human-friendly manner.
--
-- Default implementation: show.
displayException :: Exception e => e -> String
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable k (a :: k)
-- | 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 SomeException :: *
[SomeException] :: SomeException
-- | Superclass for asynchronous exceptions.
data SomeAsyncException :: *
[SomeAsyncException] :: SomeAsyncException
-- | 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.
data IOException :: *
instance GHC.Show.Show Control.Exception.Safe.SyncExceptionWrapper
instance GHC.Exception.Exception Control.Exception.Safe.SyncExceptionWrapper
instance GHC.Show.Show Control.Exception.Safe.AsyncExceptionWrapper
instance GHC.Exception.Exception Control.Exception.Safe.AsyncExceptionWrapper