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


-- | IO without any non-error, synchronous exceptions
--   
--   When you've caught all the exceptions that can be handled safely, this
--   is what you're left with.
--   
--   It is intended that you use qualified imports with this library.
--   
--   <pre>
--   import UnexceptionalIO (UIO)
--   import qualified UnexceptionalIO as UIO
--   </pre>
--   
--   You may also wish to investigate unexceptionalio-trans if you like
--   monad transformers.
--   
--   Blog post: <a>http://sngpl.ma/p4uT0</a>
@package unexceptionalio
@version 0.5.1


-- | When you've caught all the exceptions that can be handled safely, this
--   is what you're left with.
--   
--   <pre>
--   runEitherIO . fromIO ≡ id
--   </pre>
--   
--   It is intended that you use qualified imports with this library.
--   
--   <pre>
--   import UnexceptionalIO (UIO)
--   import qualified UnexceptionalIO as UIO
--   </pre>
module UnexceptionalIO

-- | Like IO, but throws only <a>PseudoException</a>
data UIO a

-- | Monads in which <a>UIO</a> computations may be embedded
class (Monad m) => Unexceptional m
lift :: Unexceptional m => UIO a -> m a

-- | Catch any exception but <a>PseudoException</a> in an <a>IO</a> action
fromIO :: Unexceptional m => IO a -> m (Either SomeNonPseudoException a)

-- | Catch any <tt>e</tt> in an <a>IO</a> action, with a default mapping
--   for unexpected cases
fromIO' :: (Exception e, Unexceptional m) => (SomeNonPseudoException -> e) -> IO a -> m (Either e a)

-- | Re-embed <a>UIO</a> into <a>IO</a>
run :: UIO a -> IO a

-- | Re-embed <a>UIO</a> and possible exception back into <a>IO</a>
runEitherIO :: Exception e => UIO (Either e a) -> IO a

-- | You promise there are no exceptions but <a>PseudoException</a> thrown
--   by this <a>IO</a> action
unsafeFromIO :: Unexceptional m => IO a -> m a

-- | Every <a>SomeException</a> but <a>PseudoException</a>
data SomeNonPseudoException

-- | Not everything handled by the exception system is a run-time error you
--   can handle. This is the class of unrecoverable pseudo-exceptions.
--   
--   Additionally, except for <a>ExitCode</a> any of these
--   pseudo-exceptions you could never guarantee to have caught. Since they
--   can come from anywhere at any time, we could never guarentee that
--   <a>UIO</a> does not contain them.
data PseudoException

-- | Mistakes programmers make
ProgrammerError :: ProgrammerError -> PseudoException

-- | Errors thrown by the runtime
ExternalError :: ExternalError -> PseudoException

-- | Process exit requests
Exit :: ExitCode -> PseudoException

-- | Pseudo-exceptions caused by a programming error
--   
--   Partial functions, <a>error</a>, <a>undefined</a>, etc
data ProgrammerError
TypeError :: TypeError -> ProgrammerError
ArithException :: ArithException -> ProgrammerError
ArrayException :: ArrayException -> ProgrammerError
AssertionFailed :: AssertionFailed -> ProgrammerError
ErrorCall :: ErrorCall -> ProgrammerError
NestedAtomically :: NestedAtomically -> ProgrammerError
NoMethodError :: NoMethodError -> ProgrammerError
PatternMatchFail :: PatternMatchFail -> ProgrammerError
RecConError :: RecConError -> ProgrammerError
RecSelError :: RecSelError -> ProgrammerError
RecUpdError :: RecSelError -> ProgrammerError

-- | Pseudo-exceptions thrown by the runtime environment
data ExternalError
CompactionFailed :: CompactionFailed -> ExternalError
FixIOException :: FixIOException -> ExternalError
AsyncException :: SomeAsyncException -> ExternalError
BlockedIndefinitelyOnSTM :: BlockedIndefinitelyOnSTM -> ExternalError
BlockedIndefinitelyOnMVar :: BlockedIndefinitelyOnMVar -> ExternalError
Deadlock :: Deadlock -> ExternalError
NonTermination :: NonTermination -> ExternalError

-- | When you're doing resource handling, <a>PseudoException</a> matters.
--   You still need to use the <a>bracket</a> pattern to handle cleanup.
bracket :: Unexceptional m => UIO a -> (a -> UIO ()) -> (a -> UIO c) -> m c

-- | Mirrors <a>forkFinally</a>, but since the body is <a>UIO</a>, the
--   thread must terminate successfully or because of
--   <a>PseudoException</a>
forkFinally :: Unexceptional m => UIO a -> (Either PseudoException a -> UIO ()) -> m ThreadId

-- | Mirrors <a>forkIO</a>, but re-throws errors to the parent thread
--   
--   <ul>
--   <li>Ignores manual thread kills, since those are on purpose.</li>
--   <li>Re-throws async exceptions (<tt>SomeAsyncException</tt>) as
--   is.</li>
--   <li>Re-throws <a>ExitCode</a> as is in an attempt to exit with the
--   requested code.</li>
--   <li>Wraps synchronous <a>PseudoException</a> in async
--   <a>ChildThreadError</a>.</li>
--   </ul>
fork :: Unexceptional m => UIO () -> m ThreadId

-- | Async signal that a child thread ended due to non-async
--   PseudoException
newtype ChildThreadError
ChildThreadError :: PseudoException -> ChildThreadError
instance GHC.Show.Show UnexceptionalIO.ProgrammerError
instance GHC.Show.Show UnexceptionalIO.ExternalError
instance GHC.Show.Show UnexceptionalIO.PseudoException
instance GHC.Show.Show UnexceptionalIO.SomeNonPseudoException
instance GHC.Show.Show UnexceptionalIO.ChildThreadError
instance GHC.Exception.Type.Exception UnexceptionalIO.ChildThreadError
instance UnexceptionalIO.Unexceptional UnexceptionalIO.UIO
instance UnexceptionalIO.Unexceptional GHC.Types.IO
instance GHC.Base.Functor UnexceptionalIO.UIO
instance GHC.Base.Applicative UnexceptionalIO.UIO
instance GHC.Base.Monad UnexceptionalIO.UIO
instance Control.Monad.Fix.MonadFix UnexceptionalIO.UIO
instance GHC.Exception.Type.Exception UnexceptionalIO.SomeNonPseudoException
instance GHC.Exception.Type.Exception UnexceptionalIO.PseudoException
instance GHC.Exception.Type.Exception UnexceptionalIO.ExternalError
instance GHC.Exception.Type.Exception UnexceptionalIO.ProgrammerError
