-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Lift control operations like exception catching through monad transformers
--   
--   This package defines <tt>MonadPeelIO</tt>, a subset of
--   <tt>MonadIO</tt> into which generic control operations such as
--   <tt>catch</tt> can be lifted from <tt>IO</tt>. Instances are based on
--   monad transformers in <tt>MonadTransPeel</tt>, which includes all
--   standard monad transformers in the <tt>transformers</tt> library
--   except <tt>ContT</tt>. For convenience, it provides a wrapped version
--   of Control.Exception with types generalized from <tt>IO</tt> to all
--   monads in <tt>MonadPeelIO</tt>.
@package monad-peel
@version 0.2.1.2


-- | This module defines the class <a>MonadTransPeel</a> of monad
--   transformers through which control operations can be lifted. Instances
--   are included for all the standard monad transformers from the
--   <tt>transformers</tt> library except <tt>ContT</tt>.
--   
--   <a>idPeel</a> and <a>liftPeel</a> are provided to assist creation of
--   <tt>MonadPeelIO</tt>-like classes (see <a>Control.Monad.IO.Peel</a>)
--   based on core monads other than <a>IO</a>.
--   
--   <a>liftOp</a> and <a>liftOp_</a> enable convenient lifting of two
--   common special cases of control operation types.
module Control.Monad.Trans.Peel

-- | <tt>MonadTransPeel</tt> is the class of monad transformers supporting
--   an extra operation <a>peel</a>, enabling control operations (functions
--   that use monadic actions as input instead of just output) to be lifted
--   through the transformer.
class MonadTrans t => MonadTransPeel t

-- | <tt>peel</tt> is used to peel off the outer layer of a transformed
--   monadic action, allowing an transformed action <tt>t m a</tt> to be
--   treated as a base action <tt>m b</tt>.
--   
--   More precisely, <tt>peel</tt> captures the monadic state of <tt>t</tt>
--   at the point where it is bound (in <tt>t n</tt>), yielding a function
--   <tt>t m a -&gt; m (t o a)</tt>; this function runs a transformed
--   monadic action <tt>t m a</tt> in the base monad <tt>m</tt> using the
--   captured state, and leaves the result <tt>t o a</tt> in the monad
--   <tt>m</tt> after all side effects in <tt>m</tt> have occurred.
--   
--   This can be used together with <a>lift</a> to lift control operations
--   with types such as <tt>M a -&gt; M a</tt> into the transformed monad
--   <tt>t M</tt>:
--   
--   <pre>
--   instance Monad M
--   foo :: M a -&gt; M a
--   foo' :: (<a>MonadTransPeel</a> t, <a>Monad</a> (t M)) =&gt; t M a -&gt; t M a
--   foo' a = do
--     k &lt;- <a>peel</a>  -- k :: t M a -&gt; M (t M a)
--     <a>join</a> $ <a>lift</a> $ foo (k a)  -- uses foo :: M (t M a) -&gt; M (t M a)
--   </pre>
--   
--   <tt>peel</tt> is typically used with <tt>m == n == o</tt>, but is
--   required to be polymorphic for greater type safety: for example, this
--   type ensures that the result of running the action in <tt>m</tt> has
--   no remaining side effects in <tt>m</tt>.
peel :: (MonadTransPeel t, Monad m, Monad n, Monad o) => t n (t m a -> m (t o a))

-- | <tt>idPeel</tt> acts as the "identity" <a>peel</a> operation from a
--   monad <tt>m</tt> to itself.
--   
--   <pre>
--   <a>idPeel</a> = <a>return</a> $ <a>liftM</a> <a>return</a>
--   </pre>
--   
--   It serves as the base case for a class like <tt>MonadPeelIO</tt>,
--   which allows control operations in some base monad (here <tt>IO</tt>)
--   to be lifted through arbitrary stacks of zero or more monad
--   transformers in one call. For example, <a>Control.Monad.IO.Peel</a>
--   defines
--   
--   <pre>
--   class <tt>MonadIO</tt> m =&gt; MonadPeelIO m where
--     peelIO :: m (m a -&gt; <a>IO</a> (m a))
--   instance MonadPeelIO <a>IO</a> where
--     peelIO = <a>idPeel</a>
--   </pre>
idPeel :: (Monad m, Monad n, Monad o) => n (m a -> m (o a))

-- | <tt>liftPeel</tt> is used to compose two <a>peel</a> operations: the
--   outer provided by a <a>MonadTransPeel</a> instance, and the inner
--   provided as the argument.
--   
--   It satisfies <tt><a>liftPeel</a> <a>idPeel</a> == <a>peel</a></tt>.
--   
--   It serves as the induction step of a <tt>MonadPeelIO</tt>-like class.
--   For example, <a>Control.Monad.IO.Peel</a> defines
--   
--   <pre>
--   instance MonadPeelIO m =&gt; MonadPeelIO (<a>StateT</a> s m) where
--     peelIO = <a>liftPeel</a> peelIO
--   </pre>
--   
--   using the <a>MonadTransPeel</a> instance of <tt><a>StateT</a> s</tt>.
liftPeel :: (MonadTransPeel t, Monad m, Monad m', Monad n', Monad (t n'), Monad o', Monad (t o')) => n' (m' (t o' a) -> m (o' (t o' a))) -> t n' (t m' a -> m (t o' a))

-- | <tt>liftOp</tt> is a particular application of <a>peel</a> that allows
--   lifting control operations of type <tt>(a -&gt; m b) -&gt; m b</tt> to
--   <tt><a>MonadTransPeel</a> t =&gt; (a -&gt; t m b) -&gt; t m b</tt>.
--   
--   <pre>
--   <a>liftOp</a> f g = do
--     k &lt;- <a>peel</a>
--     <a>join</a> $ <a>lift</a> $ f (k . g)
--   </pre>
liftOp :: (MonadTransPeel t, Monad m, Monad n, Monad o, Monad (t n)) => ((a -> m (t o b)) -> n (t n c)) -> (a -> t m b) -> t n c

-- | <tt>liftOp_</tt> is a particular application of <a>peel</a> that
--   allows lifting control operations of type <tt>m a -&gt; m a</tt> to
--   <tt><a>MonadTransPeel</a> m =&gt; t m a -&gt; t m a</tt>.
--   
--   It can be thought of as a generalization of <tt>mapReaderT</tt>,
--   <tt>mapStateT</tt>, etc.
--   
--   <pre>
--   <a>liftOp_</a> f m = do
--     k &lt;- <a>peel</a>
--     <a>join</a> $ <a>lift</a> $ f (k m)
--   </pre>
liftOp_ :: (MonadTransPeel t, Monad m, Monad n, Monad o, Monad (t n)) => (m (t o a) -> n (t n b)) -> t m a -> t n b
instance Control.Monad.Trans.Peel.MonadTransPeel Control.Monad.Trans.Identity.IdentityT
instance Control.Monad.Trans.Peel.MonadTransPeel Control.Monad.Trans.List.ListT
instance Control.Monad.Trans.Peel.MonadTransPeel Control.Monad.Trans.Maybe.MaybeT
instance Control.Monad.Trans.Error.Error e => Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.Error.ErrorT e)
instance Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.Except.ExceptT e)
instance Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.Reader.ReaderT r)
instance Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.State.Lazy.StateT s)
instance Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.State.Strict.StateT s)
instance GHC.Base.Monoid w => Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.Writer.Lazy.WriterT w)
instance GHC.Base.Monoid w => Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.Writer.Strict.WriterT w)
instance GHC.Base.Monoid w => Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.RWS.Lazy.RWST r w s)
instance GHC.Base.Monoid w => Control.Monad.Trans.Peel.MonadTransPeel (Control.Monad.Trans.RWS.Strict.RWST r w s)


-- | This module defines the class <a>MonadPeelIO</a> of <a>IO</a>-based
--   monads into which control operations on <a>IO</a> (such as exception
--   catching; see <a>Control.Exception.Peel</a>) can be lifted.
--   
--   <a>liftIOOp</a> and <a>liftIOOp_</a> enable convenient lifting of two
--   common special cases of control operation types.
module Control.Monad.IO.Peel

-- | <tt>MonadPeelIO</tt> is the class of <a>IO</a>-based monads supporting
--   an extra operation <a>peelIO</a>, enabling control operations on
--   <a>IO</a> to be lifted into the monad.
class MonadIO m => MonadPeelIO m

-- | <tt>peelIO</tt> is a version of <a>peel</a> that operates through an
--   arbitrary stack of monad transformers directly to an inner <a>IO</a>
--   (analagously to how <a>liftIO</a> is a version of <tt>lift</tt>). So
--   it can be used with <a>liftIO</a> to lift control operations on
--   <a>IO</a> into any monad in <a>MonadPeelIO</a>. For example:
--   
--   <pre>
--   foo :: <a>IO</a> a -&gt; <a>IO</a> a
--   foo' :: <a>MonadPeelIO</a> m =&gt; m a -&gt; m a
--   foo' a = do
--     k &lt;- <a>peelIO</a>  -- k :: m a -&gt; IO (m a)
--     <a>join</a> $ <a>liftIO</a> $ foo (k a)  -- uses foo :: <a>IO</a> (m a) -&gt; <a>IO</a> (m a)
--   </pre>
--   
--   Note that the "obvious" term of this type (<tt>peelIO = <a>return</a>
--   <a>return</a></tt>) <i>does not</i> work correctly. Instances of
--   <a>MonadPeelIO</a> should be constructed via <a>MonadTransPeel</a>,
--   using <tt>peelIO = <a>liftPeel</a> peelIO</tt>.
peelIO :: MonadPeelIO m => m (m a -> IO (m a))

-- | <tt>liftIOOp</tt> is a particular application of <a>peelIO</a> that
--   allows lifting control operations of type <tt>(a -&gt; <a>IO</a> b)
--   -&gt; <a>IO</a> b</tt> (e.g. <tt>alloca</tt>, <tt>withMVar v</tt>) to
--   <tt><a>MonadPeelIO</a> m =&gt; (a -&gt; m b) -&gt; m b</tt>.
--   
--   <pre>
--   <a>liftIOOp</a> f g = do
--     k &lt;- <a>peelIO</a>
--     <a>join</a> $ <a>liftIO</a> $ f (k . g)
--   </pre>
liftIOOp :: MonadPeelIO m => ((a -> IO (m b)) -> IO (m c)) -> (a -> m b) -> m c

-- | <tt>liftIOOp_</tt> is a particular application of <a>peelIO</a> that
--   allows lifting control operations of type <tt><a>IO</a> a -&gt;
--   <a>IO</a> a</tt> (e.g. <tt>block</tt>) to <tt><a>MonadPeelIO</a> m
--   =&gt; m a -&gt; m a</tt>.
--   
--   <pre>
--   <a>liftIOOp_</a> f m = do
--     k &lt;- <a>peelIO</a>
--     <a>join</a> $ <a>liftIO</a> $ f (k m)
--   </pre>
liftIOOp_ :: MonadPeelIO m => (IO (m a) -> IO (m b)) -> m a -> m b
instance Control.Monad.IO.Peel.MonadPeelIO GHC.Types.IO
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.List.ListT m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Maybe.MaybeT m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.IO.Peel.MonadPeelIO m) => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.IO.Peel.MonadPeelIO m => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.IO.Peel.MonadPeelIO m) => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.IO.Peel.MonadPeelIO m) => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.IO.Peel.MonadPeelIO m) => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.IO.Peel.MonadPeelIO m) => Control.Monad.IO.Peel.MonadPeelIO (Control.Monad.Trans.RWS.Strict.RWST r w s m)


-- | This is a wrapped version of Control.Exception with types generalized
--   from <a>IO</a> to all monads in <a>MonadPeelIO</a>.
module Control.Exception.Peel

-- | If the first argument evaluates to <a>True</a>, then the result is the
--   second argument. Otherwise an <tt>AssertionFailed</tt> exception is
--   raised, containing a <a>String</a> with the source file and line
--   number of the call to <a>assert</a>.
--   
--   Assertions can normally be turned on or off with a compiler flag (for
--   GHC, assertions are normally on unless optimisation is turned on with
--   <tt>-O</tt> or the <tt>-fignore-asserts</tt> option is given). When
--   assertions are turned off, the first argument to <a>assert</a> is
--   ignored, and the second argument is returned as the result.
assert :: () => Bool -> a -> a

-- | When invoked inside <a>mask</a>, this function allows a masked
--   asynchronous exception to be raised, if one exists. It is equivalent
--   to performing an interruptible operation (see #interruptible), but
--   does not involve any actual blocking.
--   
--   When called outside <a>mask</a>, or inside <a>uninterruptibleMask</a>,
--   this function has no effect.
allowInterrupt :: IO ()

-- | This function maps one exception into another as proposed in the paper
--   "A semantics for imprecise exceptions".
mapException :: (Exception e1, Exception e2) => e1 -> e2 -> a -> a

-- | A pattern match failed. The <tt>String</tt> gives information about
--   the source location of the pattern.
newtype PatternMatchFail
PatternMatchFail :: String -> PatternMatchFail

-- | A record selector was applied to a constructor without the appropriate
--   field. This can only happen with a datatype with multiple
--   constructors, where some fields are in one constructor but not
--   another. The <tt>String</tt> gives information about the source
--   location of the record selector.
newtype RecSelError
RecSelError :: String -> RecSelError

-- | An uninitialised record field was used. The <tt>String</tt> gives
--   information about the source location where the record was
--   constructed.
newtype RecConError
RecConError :: String -> RecConError

-- | A record update was performed on a constructor without the appropriate
--   field. This can only happen with a datatype with multiple
--   constructors, where some fields are in one constructor but not
--   another. The <tt>String</tt> gives information about the source
--   location of the record update.
newtype RecUpdError
RecUpdError :: String -> RecUpdError

-- | A class method without a definition (neither a default definition, nor
--   a definition in the appropriate instance) was called. The
--   <tt>String</tt> gives information about which method it was.
newtype NoMethodError
NoMethodError :: String -> NoMethodError

-- | An expression that didn't typecheck during compile time was called.
--   This is only possible with -fdefer-type-errors. The <tt>String</tt>
--   gives details about the failed type check.
newtype TypeError
TypeError :: String -> TypeError

-- | Thrown when the runtime system detects that the computation is
--   guaranteed not to terminate. Note that there is no guarantee that the
--   runtime system will notice whether any given computation is guaranteed
--   to terminate or not.
data NonTermination
NonTermination :: NonTermination

-- | Thrown when the program attempts to call <tt>atomically</tt>, from the
--   <tt>stm</tt> package, inside another call to <tt>atomically</tt>.
data NestedAtomically
NestedAtomically :: NestedAtomically

-- | <a>throwTo</a> raises an arbitrary exception in the target thread (GHC
--   only).
--   
--   Exception delivery synchronizes between the source and target thread:
--   <a>throwTo</a> does not return until the exception has been raised in
--   the target thread. The calling thread can thus be certain that the
--   target thread has received the exception. Exception delivery is also
--   atomic with respect to other exceptions. Atomicity is a useful
--   property to have when dealing with race conditions: e.g. if there are
--   two threads that can kill each other, it is guaranteed that only one
--   of the threads will get to kill the other.
--   
--   Whatever work the target thread was doing when the exception was
--   raised is not lost: the computation is suspended until required by
--   another thread.
--   
--   If the target thread is currently making a foreign call, then the
--   exception will not be raised (and hence <a>throwTo</a> will not
--   return) until the call has completed. This is the case regardless of
--   whether the call is inside a <a>mask</a> or not. However, in GHC a
--   foreign call can be annotated as <tt>interruptible</tt>, in which case
--   a <a>throwTo</a> will cause the RTS to attempt to cause the call to
--   return; see the GHC documentation for more details.
--   
--   Important note: the behaviour of <a>throwTo</a> differs from that
--   described in the paper "Asynchronous exceptions in Haskell"
--   (<a>http://research.microsoft.com/~simonpj/Papers/asynch-exns.htm</a>).
--   In the paper, <a>throwTo</a> is non-blocking; but the library
--   implementation adopts a more synchronous design in which
--   <a>throwTo</a> does not return until the exception is received by the
--   target thread. The trade-off is discussed in Section 9 of the paper.
--   Like any blocking operation, <a>throwTo</a> is therefore interruptible
--   (see Section 5.3 of the paper). Unlike other interruptible operations,
--   however, <a>throwTo</a> is <i>always</i> interruptible, even if it
--   does not actually block.
--   
--   There is no guarantee that the exception will be delivered promptly,
--   although the runtime will endeavour to ensure that arbitrary delays
--   don't occur. In GHC, an exception can only be raised when a thread
--   reaches a <i>safe point</i>, where a safe point is where memory
--   allocation occurs. Some loops do not perform any memory allocation
--   inside the loop and therefore cannot be interrupted by a
--   <a>throwTo</a>.
--   
--   If the target of <a>throwTo</a> is the calling thread, then the
--   behaviour is the same as <a>throwIO</a>, except that the exception is
--   thrown as an asynchronous exception. This means that if there is an
--   enclosing pure computation, which would be the case if the current IO
--   operation is inside <a>unsafePerformIO</a> or
--   <a>unsafeInterleaveIO</a>, that computation is not permanently
--   replaced by the exception, but is suspended as if it had received an
--   asynchronous exception.
--   
--   Note that if <a>throwTo</a> is called with the current thread as the
--   target, the exception will be thrown even if the thread is currently
--   inside <a>mask</a> or <a>uninterruptibleMask</a>.
throwTo :: Exception e => ThreadId -> e -> IO ()

asyncExceptionFromException :: Exception e => SomeException -> Maybe e

asyncExceptionToException :: Exception e => e -> SomeException

-- | The thread is blocked on an <tt>MVar</tt>, but there are no other
--   references to the <tt>MVar</tt> so it can't ever continue.
data BlockedIndefinitelyOnMVar
BlockedIndefinitelyOnMVar :: BlockedIndefinitelyOnMVar

-- | The thread is waiting to retry an STM transaction, but there are no
--   other references to any <tt>TVar</tt>s involved, so it can't ever
--   continue.
data BlockedIndefinitelyOnSTM
BlockedIndefinitelyOnSTM :: BlockedIndefinitelyOnSTM

-- | There are no runnable threads, so the program is deadlocked. The
--   <tt>Deadlock</tt> exception is raised in the main thread only.
data Deadlock
Deadlock :: Deadlock

-- | This thread has exceeded its allocation limit. See
--   <a>setAllocationCounter</a> and <a>enableAllocationLimit</a>.
data AllocationLimitExceeded
AllocationLimitExceeded :: AllocationLimitExceeded

-- | Compaction found an object that cannot be compacted. Functions cannot
--   be compacted, nor can mutable objects or pinned objects. See
--   <a>compact</a>.
newtype CompactionFailed
CompactionFailed :: String -> CompactionFailed

-- | <a>assert</a> was applied to <a>False</a>.
newtype AssertionFailed
AssertionFailed :: String -> AssertionFailed

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

-- | Asynchronous exceptions.
data AsyncException

-- | The current thread's stack exceeded its limit. Since an exception has
--   been raised, the thread's stack will certainly be below its limit
--   again, but the programmer should take remedial action immediately.
StackOverflow :: AsyncException

-- | The program's heap is reaching its limit, and the program should take
--   action to reduce the amount of live data it has. Notes:
--   
--   <ul>
--   <li>It is undefined which thread receives this exception. GHC
--   currently throws this to the same thread that receives
--   <a>UserInterrupt</a>, but this may change in the future.</li>
--   <li>The GHC RTS currently can only recover from heap overflow if it
--   detects that an explicit memory limit (set via RTS flags). has been
--   exceeded. Currently, failure to allocate memory from the operating
--   system results in immediate termination of the program.</li>
--   </ul>
HeapOverflow :: AsyncException

-- | This exception is raised by another thread calling <a>killThread</a>,
--   or by the system if it needs to terminate the thread for some reason.
ThreadKilled :: AsyncException

-- | This exception is raised by default in the main thread of the program
--   when the user requests to terminate the program via the usual
--   mechanism(s) (e.g. Control-C in the console).
UserInterrupt :: AsyncException

-- | Exceptions generated by array operations
data ArrayException

-- | An attempt was made to index an array outside its declared bounds.
IndexOutOfBounds :: String -> ArrayException

-- | An attempt was made to evaluate an element of an array that had not
--   been initialized.
UndefinedElement :: String -> ArrayException

-- | Like <a>mask</a>, but the masked computation is not interruptible (see
--   <a>Control.Exception#interruptible</a>). THIS SHOULD BE USED WITH
--   GREAT CARE, because if a thread executing in
--   <a>uninterruptibleMask</a> blocks for any reason, then the thread (and
--   possibly the program, if this is the main thread) will be unresponsive
--   and unkillable. This function should only be necessary if you need to
--   mask exceptions around an interruptible operation, and you can
--   guarantee that the interruptible operation will only block for a short
--   period of time.
uninterruptibleMask :: () => forall a. () => IO a -> IO a -> IO b -> IO b

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

-- | Executes an IO computation with asynchronous exceptions <i>masked</i>.
--   That is, any thread which attempts to raise an exception in the
--   current thread with <a>throwTo</a> will be blocked until asynchronous
--   exceptions are unmasked again.
--   
--   The argument passed to <a>mask</a> is a function that takes as its
--   argument another function, which can be used to restore the prevailing
--   masking state within the context of the masked computation. For
--   example, a common way to use <a>mask</a> is to protect the acquisition
--   of a resource:
--   
--   <pre>
--   mask $ \restore -&gt; do
--       x &lt;- acquire
--       restore (do_something_with x) `onException` release
--       release
--   </pre>
--   
--   This code guarantees that <tt>acquire</tt> is paired with
--   <tt>release</tt>, by masking asynchronous exceptions for the critical
--   parts. (Rather than write this code yourself, it would be better to
--   use <a>bracket</a> which abstracts the general pattern).
--   
--   Note that the <tt>restore</tt> action passed to the argument to
--   <a>mask</a> does not necessarily unmask asynchronous exceptions, it
--   just restores the masking state to that of the enclosing context. Thus
--   if asynchronous exceptions are already masked, <a>mask</a> cannot be
--   used to unmask exceptions again. This is so that if you call a library
--   function with exceptions masked, you can be sure that the library call
--   will not be able to unmask exceptions again. If you are writing
--   library code and need to use asynchronous exceptions, the only way is
--   to create a new thread; see <a>forkIOWithUnmask</a>.
--   
--   Asynchronous exceptions may still be received while in the masked
--   state if the masked thread <i>blocks</i> in certain ways; see
--   <a>Control.Exception#interruptible</a>.
--   
--   Threads created by <a>forkIO</a> inherit the <a>MaskingState</a> from
--   the parent; that is, to start a thread in the
--   <a>MaskedInterruptible</a> state, use <tt>mask_ $ forkIO ...</tt>.
--   This is particularly useful if you need to establish an exception
--   handler in the forked thread before any asynchronous exceptions are
--   received. To create a a new thread in an unmasked state use
--   <a>forkIOWithUnmask</a>.
mask :: () => forall a. () => IO a -> IO a -> IO b -> IO b

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

-- | Returns the <a>MaskingState</a> for the current thread.
getMaskingState :: IO MaskingState

-- | Allow asynchronous exceptions to be raised even inside <a>mask</a>,
--   making the operation interruptible (see the discussion of
--   "Interruptible operations" in <a>Exception</a>).
--   
--   When called outside <a>mask</a>, or inside <a>uninterruptibleMask</a>,
--   this function has no effect.
interruptible :: () => IO a -> IO a

-- | Describes the behaviour of a thread when an asynchronous exception is
--   received.
data MaskingState

-- | asynchronous exceptions are unmasked (the normal state)
Unmasked :: MaskingState

-- | the state during <a>mask</a>: asynchronous exceptions are masked, but
--   blocking operations may still be interrupted
MaskedInterruptible :: MaskingState

-- | the state during <a>uninterruptibleMask</a>: asynchronous exceptions
--   are masked, and blocking operations may not be interrupted
MaskedUninterruptible :: MaskingState

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

-- | Throw an exception. Exceptions may be thrown from purely functional
--   code, but may only be caught within the <a>IO</a> monad.
throw :: Exception e => e -> 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
--   
--   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
--   
--   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
--   
--   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 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 `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
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: <tt><a>show</a></tt>.
displayException :: Exception e => e -> String

-- | This is thrown when the user calls <a>error</a>. The first
--   <tt>String</tt> is the argument given to <a>error</a>, second
--   <tt>String</tt> is the location.
data ErrorCall
ErrorCallWithLocation :: String -> String -> ErrorCall

-- | Arithmetic exceptions.
data ArithException
Overflow :: ArithException
Underflow :: ArithException
LossOfPrecision :: ArithException
DivideByZero :: ArithException
Denormal :: ArithException

RatioZeroDenominator :: ArithException

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

-- | Generalized version of <a>throwIO</a>.
throwIO :: (MonadIO m, Exception e) => e -> m a

-- | Generalized version of <a>ioError</a>.
ioError :: MonadIO m => IOError -> m a

-- | Generalized version of <a>catch</a>.
catch :: (MonadPeelIO m, Exception e) => m a -> (e -> m a) -> m a

-- | Generalized version of <a>catches</a>.
catches :: MonadPeelIO m => m a -> [Handler m a] -> m a

-- | Generalized version of <a>Handler</a>.
data Handler m a
Handler :: (e -> m a) -> Handler m a

-- | Generalized version of <a>catchJust</a>.
catchJust :: (MonadPeelIO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a

-- | Generalized version of <a>handle</a>.
handle :: (MonadPeelIO m, Exception e) => (e -> m a) -> m a -> m a

-- | Generalized version of <a>handleJust</a>.
handleJust :: (MonadPeelIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a

-- | Generalized version of <a>try</a>.
try :: (MonadPeelIO m, Exception e) => m a -> m (Either e a)

-- | Generalized version of <a>tryJust</a>.
tryJust :: (MonadPeelIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)

-- | Generalized version of <a>evaluate</a>.
evaluate :: MonadIO m => a -> m a

-- | Generalized version of <a>bracket</a>. Note, any monadic side effects
--   in <tt>m</tt> of the "release" computation will be discarded; it is
--   run only for its side effects in <tt>IO</tt>.
bracket :: MonadPeelIO m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Generalized version of <a>bracket_</a>. Note, any monadic side effects
--   in <tt>m</tt> of <i>both</i> the "acquire" and "release" computations
--   will be discarded. To keep the monadic side effects of the "acquire"
--   computation, use <a>bracket</a> with constant functions instead.
bracket_ :: MonadPeelIO m => m a -> m b -> m c -> m c

-- | Generalized version of <a>bracketOnError</a>.
bracketOnError :: MonadPeelIO m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Generalized version of <a>finally</a>. Note, any monadic side effects
--   in <tt>m</tt> of the "afterward" computation will be discarded.
finally :: MonadPeelIO m => m a -> m b -> m a

-- | Generalized version of <a>onException</a>.
onException :: MonadPeelIO m => m a -> m b -> m a
