-- 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.4.0


-- | Please see the README.md file in the safe-exceptions repo for
--   information on how to use this module. Relevant links:
--   
--   <ul>
--   <li><a>https://github.com/fpco/safe-exceptions#readme</a></li>
--   <li><a>https://www.stackage.org/package/safe-exceptions</a></li>
--   </ul>
module Control.Exception.Safe

-- | Synchronously throw the given exception
throw :: (MonadThrow m, Exception e) => e -> m a

-- | Synonym for <a>throw</a>
throwIO :: (MonadThrow m, Exception e) => e -> m a

-- | Synonym for <a>throw</a>
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
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
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
--   <a>throw</a>, see
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
impureThrow :: Exception e => e -> a

-- | Same as upstream <a>catch</a>, but will not catch asynchronous
--   exceptions
catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a

-- | <a>catch</a> specialized to only catching <a>IOException</a>s
catchIO :: MonadCatch m => m a -> (IOException -> m a) -> m a

-- | <a>catch</a> specialized to catch all synchronous exception
catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a

-- | Same as <a>catch</a>, 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

-- | <a>catchDeep</a> specialized to catch all synchronous exception
catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a

-- | <a>catch</a> without async exception safety
--   
--   Generally it's better to avoid using this function since we do not
--   want to recover from async exceptions, see
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
catchAsync :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a

-- | <a>catchJust</a> is like <a>catch</a> but it takes an extra argument
--   which is an exception predicate, a function which selects which type
--   of exceptions we're interested in.
catchJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a

-- | Flipped version of <a>catch</a>
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a

-- | <a>handle</a> specialized to only catching <a>IOException</a>s
handleIO :: MonadCatch m => (IOException -> m a) -> m a -> m a

-- | Flipped version of <a>catchAny</a>
handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a

-- | Flipped version of <a>catchDeep</a>
handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a

-- | Flipped version of <a>catchAnyDeep</a>
handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a

-- | Flipped version of <a>catchAsync</a>
--   
--   Generally it's better to avoid using this function since we do not
--   want to recover from async exceptions, see
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
handleAsync :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a

-- | Flipped <a>catchJust</a>.
handleJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a

-- | Same as upstream <a>try</a>, but will not catch asynchronous
--   exceptions
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)

-- | <a>try</a> specialized to only catching <a>IOException</a>s
tryIO :: MonadCatch m => m a -> m (Either IOException a)

-- | <a>try</a> specialized to catch all synchronous exceptions
tryAny :: MonadCatch m => m a -> m (Either SomeException a)

-- | Same as <a>try</a>, 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)

-- | <a>tryDeep</a> specialized to catch all synchronous exceptions
tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a)

-- | <a>try</a> without async exception safety
--   
--   Generally it's better to avoid using this function since we do not
--   want to recover from async exceptions, see
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
tryAsync :: (MonadCatch m, Exception e) => m a -> m (Either e a)

-- | A variant of <a>try</a> that takes an exception predicate to select
--   which exceptions are caught.
tryJust :: (MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)

-- | You need this when using <a>catches</a>.
data Handler m a
Handler :: (e -> m a) -> Handler m a

-- | Same as upstream <a>catches</a>, but will not catch asynchronous
--   exceptions
catches :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a

-- | Same as <a>catches</a>, 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

-- | <a>catches</a> without async exception safety
--   
--   Generally it's better to avoid using this function since we do not
--   want to recover from async exceptions, see
--   <a>https://github.com/fpco/safe-exceptions#quickstart</a>
catchesAsync :: (MonadCatch m, MonadThrow m) => m a -> [Handler m a] -> m a

-- | Async safe version of <a>onException</a>
onException :: MonadMask m => m a -> m b -> m a

-- | Async safe version of <a>bracket</a>
bracket :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Async safe version of <a>bracket_</a>
bracket_ :: MonadMask m => m a -> m b -> m c -> m c

-- | Async safe version of <a>finally</a>
finally :: MonadMask m => m a -> m b -> m a

-- | Like <a>onException</a>, but provides the handler the thrown
--   exception.
withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a

-- | Async safe version of <a>bracketOnError</a>
bracketOnError :: forall m a b c. MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Async safe version of <a>bracketOnError_</a>
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 <a>toSyncException</a>
data SyncExceptionWrapper
SyncExceptionWrapper :: e -> SyncExceptionWrapper

-- | Convert an exception into a synchronous exception
--   
--   For synchronous exceptions, this is the same as <a>toException</a>.
--   For asynchronous exceptions, this will wrap up the exception with
--   <a>SyncExceptionWrapper</a>
toSyncException :: Exception e => e -> SomeException

-- | Wrap up a synchronous exception to be treated as an asynchronous
--   exception
--   
--   This is intended to be created via <a>toAsyncException</a>
data AsyncExceptionWrapper
AsyncExceptionWrapper :: e -> AsyncExceptionWrapper

-- | Convert an exception into an asynchronous exception
--   
--   For asynchronous exceptions, this is the same as <a>toException</a>.
--   For synchronous exceptions, this will wrap up the exception with
--   <a>AsyncExceptionWrapper</a>
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:
--   
--   <pre>
--   throwM e &gt;&gt; x = throwM e
--   </pre>
--   
--   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 <a>throwM</a>.
--   
--   Instances should obey the following law:
--   
--   <pre>
--   catch (throwM e) f = f e
--   </pre>
--   
--   Note that the ability to catch an exception does <i>not</i> 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 <tt>catch</tt>
--   <i>cannot</i> be used by those monads to properly implement a function
--   such as <tt>finally</tt>. For more information, see <a>MonadMask</a>.
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 <tt>ErrorT e
--   IO</tt> which provide for multiple failure modes, are invalid
--   instances of this class.
--   
--   Note that this package <i>does</i> provide a <tt>MonadMask</tt>
--   instance for <tt>CatchT</tt>. This instance is <i>only</i> valid if
--   the base monad provides no ability to provide multiple exit. For
--   example, <tt>IO</tt> or <tt>Either</tt> would be invalid base monads,
--   but <tt>Reader</tt> or <tt>State</tt> would be acceptable.
--   
--   Instances should ensure that, in the following code:
--   
--   <pre>
--   f `finally` g
--   </pre>
--   
--   The action <tt>g</tt> is called regardless of what occurs within
--   <tt>f</tt>, 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 <a>mask</a> call. See <a>Control.Exception</a>'s <a>mask</a>.
mask :: ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>mask</a>, but the masked computation is not interruptible (see
--   <a>Control.Exception</a>'s <a>uninterruptibleMask</a>. 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 :: ((forall a. m a -> m a) -> m b) -> m b

-- | Like <a>mask</a>, but does not pass a <tt>restore</tt> action to the
--   argument.
mask_ :: MonadMask m => m a -> m a

-- | Like <a>uninterruptibleMask</a>, but does not pass a <tt>restore</tt>
--   action to the argument.
uninterruptibleMask_ :: MonadMask m => m a -> m a

-- | Catch all <a>IOError</a> (eqv. <tt>IOException</tt>) exceptions. Still
--   somewhat too general, but better than using <a>catchAll</a>. See
--   <a>catchIf</a> for an easy way of catching specific <a>IOError</a>s
--   based on the predicates in <a>System.IO.Error</a>.
catchIOError :: MonadCatch m => m a -> (IOError -> m a) -> m a

-- | Flipped <a>catchIOError</a>
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 <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving (Show, Typeable)
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--       deriving Typeable
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--       deriving Typeable
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- 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
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses <tt>catch</tt> e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable * e, Show e) => Exception e
toException :: e -> SomeException
fromException :: SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: e -> String

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable k (a :: k)

-- | The <tt>SomeException</tt> type is the root of the exception type
--   hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
--   scenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException :: *
[SomeException] :: SomeException

-- | Superclass for asynchronous exceptions.
data SomeAsyncException :: *
[SomeAsyncException] :: SomeAsyncException

-- | Exceptions that occur in the <tt>IO</tt> monad. An
--   <tt>IOException</tt> 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