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

-- | 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 <a>StringException</a>. When GHC
--   supports it (base 4.9 and GHC 8.0 and onward), it includes a call
--   stack.
throwString :: (MonadThrow m, HasCallStack) => String -> m a

-- | Exception type thrown by <a>throwString</a>.
--   
--   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).
data StringException
StringException :: String -> CallStack -> StringException

-- | Throw an asynchronous exception to another thread.
--   
--   Synchronously typed exceptions will be wrapped into an
--   <a>AsyncExceptionWrapper</a>, see
--   <a>https://github.com/fpco/safe-exceptions#determining-sync-vs-async</a>
--   
--   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)

-- | Generalized version of <a>Handler</a>
data Handler (m :: Type -> Type) a
Handler :: (e -> m a) -> Handler (m :: Type -> Type) 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

-- | A variant of <a>bracketOnError</a> where the return value from the
--   first computation is not required.
bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c

-- | Async safe version of <a>bracket</a> with access to the exception in
--   the cleanup action.
bracketWithError :: forall m a b c. MonadMask m => m a -> (Maybe SomeException -> a -> m b) -> (a -> 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 :: Type -> Type)

-- | 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 :: Type -> Type)

-- | 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 are invalid instances of this
--   class.
--   
--   Instances should ensure that, in the following code:
--   
--   <pre>
--   fg = f `finally` g
--   </pre>
--   
--   The action <tt>g</tt> is called regardless of what occurs within
--   <tt>f</tt>, including async exceptions. Some monads allow <tt>f</tt>
--   to abort the computation via other effects than throwing an exception.
--   For simplicity, we will consider aborting and throwing an exception to
--   be two forms of "throwing an error".
--   
--   If <tt>f</tt> and <tt>g</tt> both throw an error, the error thrown by
--   <tt>fg</tt> depends on which errors we're talking about. In a monad
--   transformer stack, the deeper layers override the effects of the inner
--   layers; for example, <tt>ExceptT e1 (Except e2) a</tt> represents a
--   value of type <tt>Either e2 (Either e1 a)</tt>, so throwing both an
--   <tt>e1</tt> and an <tt>e2</tt> will result in <tt>Left e2</tt>. If
--   <tt>f</tt> and <tt>g</tt> both throw an error from the same layer,
--   instances should ensure that the error from <tt>g</tt> wins.
--   
--   Effects other than throwing an error are also overriden by the deeper
--   layers. For example, <tt>StateT s Maybe a</tt> represents a value of
--   type <tt>s -&gt; Maybe (a, s)</tt>, so if an error thrown from
--   <tt>f</tt> causes this function to return <tt>Nothing</tt>, any
--   changes to the state which <tt>f</tt> also performed will be erased.
--   As a result, <tt>g</tt> will see the state as it was before
--   <tt>f</tt>. Once <tt>g</tt> completes, <tt>f</tt>'s error will be
--   rethrown, so <tt>g</tt>' state changes will be erased as well. This is
--   the normal interaction between effects in a monad transformer stack.
--   
--   By contrast, <a>lifted-base</a>'s version of <a>finally</a> always
--   discards all of <tt>g</tt>'s non-IO effects, and <tt>g</tt> never sees
--   any of <tt>f</tt>'s non-IO effects, regardless of the layer ordering
--   and regardless of whether <tt>f</tt> throws an error. This is not the
--   result of interacting effects, but a consequence of
--   <tt>MonadBaseControl</tt>'s approach.
class MonadCatch m => MonadMask (m :: Type -> Type)

-- | 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 :: MonadMask m => ((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 :: MonadMask m => ((forall a. () => m a -> m a) -> m b) -> m b

-- | A generalized version of <a>bracket</a> which uses <a>ExitCase</a> to
--   distinguish the different exit cases, and returns the values of both
--   the <tt>use</tt> and <tt>release</tt> actions. In practice, this extra
--   information is rarely needed, so it is often more convenient to use
--   one of the simpler functions which are defined in terms of this one,
--   such as <a>bracket</a>, <a>finally</a>, <a>onError</a>, and
--   <a>bracketOnError</a>.
--   
--   This function exists because in order to thread their effects through
--   the execution of <a>bracket</a>, monad transformers need values to be
--   threaded from <tt>use</tt> to <tt>release</tt> and from
--   <tt>release</tt> to the output value.
--   
--   <i>NOTE</i> This method was added in version 0.9.0 of this library.
--   Previously, implementation of functions like <a>bracket</a> and
--   <a>finally</a> in this module were based on the <a>mask</a> and
--   <a>uninterruptibleMask</a> functions only, disallowing some classes of
--   tranformers from having <tt>MonadMask</tt> instances (notably
--   multi-exit-point transformers like <a>ExceptT</a>). If you are a
--   library author, you'll now need to provide an implementation for this
--   method. The <tt>StateT</tt> implementation demonstrates most of the
--   subtleties:
--   
--   <pre>
--   generalBracket acquire release use = StateT $ s0 -&gt; do
--     ((b, _s2), (c, s3)) &lt;- generalBracket
--       (runStateT acquire s0)
--       ((resource, s1) exitCase -&gt; case exitCase of
--         ExitCaseSuccess (b, s2) -&gt; runStateT (release resource (ExitCaseSuccess b)) s2
--   
--         -- In the two other cases, the base monad overrides <tt>use</tt>'s state
--         -- changes and the state reverts to <tt>s1</tt>.
--         ExitCaseException e     -&gt; runStateT (release resource (ExitCaseException e)) s1
--         ExitCaseAbort           -&gt; runStateT (release resource ExitCaseAbort) s1
--       )
--       ((resource, s1) -&gt; runStateT (use resource) s1)
--     return ((b, c), s3)
--   </pre>
--   
--   The <tt>StateT s m</tt> implementation of <tt>generalBracket</tt>
--   delegates to the <tt>m</tt> implementation of <tt>generalBracket</tt>.
--   The <tt>acquire</tt>, <tt>use</tt>, and <tt>release</tt> arguments
--   given to <tt>StateT</tt>'s implementation produce actions of type
--   <tt>StateT s m a</tt>, <tt>StateT s m b</tt>, and <tt>StateT s m
--   c</tt>. In order to run those actions in the base monad, we need to
--   call <tt>runStateT</tt>, from which we obtain actions of type <tt>m
--   (a, s)</tt>, <tt>m (b, s)</tt>, and <tt>m (c, s)</tt>. Since each
--   action produces the next state, it is important to feed the state
--   produced by the previous action to the next action.
--   
--   In the <a>ExitCaseSuccess</a> case, the state starts at <tt>s0</tt>,
--   flows through <tt>acquire</tt> to become <tt>s1</tt>, flows through
--   <tt>use</tt> to become <tt>s2</tt>, and finally flows through
--   <tt>release</tt> to become <tt>s3</tt>. In the other two cases,
--   <tt>release</tt> does not receive the value <tt>s2</tt>, so its action
--   cannot see the state changes performed by <tt>use</tt>. This is fine,
--   because in those two cases, an error was thrown in the base monad, so
--   as per the usual interaction between effects in a monad transformer
--   stack, those state changes get reverted. So we start from <tt>s1</tt>
--   instead.
--   
--   Finally, the <tt>m</tt> implementation of <tt>generalBracket</tt>
--   returns the pairs <tt>(b, s)</tt> and <tt>(c, s)</tt>. For monad
--   transformers other than <tt>StateT</tt>, this will be some other type
--   representing the effects and values performed and returned by the
--   <tt>use</tt> and <tt>release</tt> actions. The effect part of the
--   <tt>use</tt> result, in this case <tt>_s2</tt>, usually needs to be
--   discarded, since those effects have already been incorporated in the
--   <tt>release</tt> action.
--   
--   The only effect which is intentionally not incorporated in the
--   <tt>release</tt> action is the effect of throwing an error. In that
--   case, the error must be re-thrown. One subtlety which is easy to miss
--   is that in the case in which <tt>use</tt> and <tt>release</tt> both
--   throw an error, the error from <tt>release</tt> should take priority.
--   Here is an implementation for <tt>ExceptT</tt> which demonstrates how
--   to do this.
--   
--   <pre>
--   generalBracket acquire release use = ExceptT $ do
--     (eb, ec) &lt;- generalBracket
--       (runExceptT acquire)
--       (eresource exitCase -&gt; case eresource of
--         Left e -&gt; return (Left e) -- nothing to release, acquire didn't succeed
--         Right resource -&gt; case exitCase of
--           ExitCaseSuccess (Right b) -&gt; runExceptT (release resource (ExitCaseSuccess b))
--           ExitCaseException e       -&gt; runExceptT (release resource (ExitCaseException e))
--           _                         -&gt; runExceptT (release resource ExitCaseAbort))
--       (either (return . Left) (runExceptT . use))
--     return $ do
--       -- The order in which we perform those two <a>Either</a> effects determines
--       -- which error will win if they are both <a>Left</a>s. We want the error from
--       -- <tt>release</tt> to win.
--       c &lt;- ec
--       b &lt;- eb
--       return (b, c)
--   </pre>
generalBracket :: MonadMask m => m a -> (a -> ExitCase b -> m c) -> (a -> m b) -> m (b, c)

-- | 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
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
displayException :: Exception e => e -> String
class Typeable (a :: k)
data SomeException
SomeException :: e -> SomeException
data SomeAsyncException
SomeAsyncException :: e -> SomeAsyncException
data IOException
assert :: Bool -> a -> a
instance GHC.Show.Show Control.Exception.Safe.AsyncExceptionWrapper
instance GHC.Exception.Type.Exception Control.Exception.Safe.AsyncExceptionWrapper
instance GHC.Show.Show Control.Exception.Safe.SyncExceptionWrapper
instance GHC.Exception.Type.Exception Control.Exception.Safe.SyncExceptionWrapper
instance GHC.Show.Show Control.Exception.Safe.StringException
instance GHC.Exception.Type.Exception Control.Exception.Safe.StringException
