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

-- | Safety for the pipes ecosystem
--   
--   This package adds resource management and exception handling to the
--   pipes ecosystem.
--   
--   Notable features include:
--   
--   
--   
- Resource Safety: Guarantee finalization using
--   finally, bracket and more
--   
- Exception Safety: Even against asynchronous
--   exceptions!
--   
- Laziness: Only acquire resources when you need them
--   
- Promptness: Finalize resources early when you are done with
--   them
--   
- Native Exception Handling: Catch and resume from exceptions
--   inside pipes
--   
- No Buy-in: Mix resource-safe pipes with unmanaged pipes
--   using hoist
--   
@package pipes-safe
@version 2.2.3

-- | This module provides an orphan MonadCatch instance for
--   Proxy of the form:
--   
--   
--   instance (MonadCatch m, MonadIO m) => MonadCatch (Proxy a' a b' b m) where
--   
--   
--   ... so you can throw and catch exceptions within pipes using all
--   MonadCatch operations.
--   
--   This module also provides generalized versions of some
--   MonadCatch operations so that you can also protect against
--   premature termination of connected components. For example, if you
--   protect a readFile computation using bracket from this
--   module:
--   
--   
--   -- readFile.hs
--   import Pipes
--   import qualified Pipes.Prelude as P
--   import Pipes.Safe
--   import qualified System.IO as IO
--   import Prelude hiding (readFile)
--   
--   readFile :: FilePath -> Producer' String (SafeT IO) ()
--   readFile file = bracket
--       (do h <- IO.openFile file IO.ReadMode
--           putStrLn $ "{" ++ file ++ " open}"
--           return h )
--       (\h -> do
--           IO.hClose h
--           putStrLn $ "{" ++ file ++ " closed}" )
--       P.fromHandle
--   
--   
--   ... then this generalized bracket will guard against both
--   exceptions and premature termination of other pipes:
--   
--   
--   >>> runSafeT $ runEffect $ readFile "readFile.hs" >-> P.take 4 >-> P.stdoutLn
--   {readFile.hs open}
--   -- readFile.hs
--   import Pipes
--   import qualified Pipes.Prelude as P
--   import Pipes.Safe
--   {readFile.hs closed}
--   
--   
--   Note that the MonadCatch instance for Proxy provides
--   weaker versions of mask and uninterruptibleMask that do
--   not completely prevent asynchronous exceptions. Instead, they provide
--   a weaker guarantee that asynchronous exceptions will only occur during
--   awaits or yields and nowhere else. For example, if you
--   write:
--   
--   
--   mask_ $ do
--       x <- await
--       lift $ print x
--       lift $ print x
--   
--   
--   ... then you may receive an asynchronous exception during the
--   await, but you will not receive an asynchronous exception
--   during or in between the two print statements. This weaker
--   guarantee suffices to provide asynchronous exception safety.
module Pipes.Safe

-- | SafeT is a monad transformer that extends the base monad with
--   the ability to register and release finalizers.
--   
--   All unreleased finalizers are called at the end of the SafeT
--   block, even in the event of exceptions.
data SafeT m r

-- | Run the SafeT monad transformer, executing all unreleased
--   finalizers at the end of the computation
runSafeT :: (MonadMask m, MonadIO m) => SafeT m r -> m r

-- | Run SafeT in the base monad, executing all unreleased
--   finalizers at the end of the computation
--   
--   Use runSafeP to safely flush all unreleased finalizers and
--   ensure prompt finalization without exiting the Proxy monad.
runSafeP :: (MonadMask m, MonadIO m) => Effect (SafeT m) r -> Effect' m r

-- | Token used to release a previously registered finalizer
data ReleaseKey

-- | MonadSafe lets you register and release
--   finalizers that execute in a Base monad
class (MonadCatch m, MonadMask m, MonadIO m, MonadIO (Base m)) => MonadSafe m where type family Base (m :: * -> *) :: * -> *

-- | Lift an action from the Base monad
liftBase :: MonadSafe m => Base m r -> m r

-- | register a finalizer, ensuring that the finalizer gets called
--   if the finalizer is not released before the end of the
--   surrounding SafeT block.
register :: MonadSafe m => Base m () -> m ReleaseKey

-- | release a registered finalizer
--   
--   You can safely call release more than once on the same
--   ReleaseKey. Every release after the first one does
--   nothing.
release :: MonadSafe m => ReleaseKey -> m ()

-- | Analogous to onException from Control.Monad.Catch,
--   except this also protects against premature termination
--   
--   (`onException` io) is a monad morphism.
onException :: (MonadSafe m) => m a -> Base m b -> m a

-- | Analogous to finally from Control.Monad.Catch, except
--   this also protects against premature termination
finally :: (MonadSafe m) => m a -> Base m b -> m a

-- | Analogous to bracket from Control.Monad.Catch, except
--   this also protects against premature termination
bracket :: (MonadSafe m) => Base m a -> (a -> Base m b) -> (a -> m c) -> m c

-- | Analogous to bracket_ from Control.Monad.Catch, except
--   this also protects against premature termination
bracket_ :: (MonadSafe m) => Base m a -> Base m b -> m c -> m c

-- | Analogous to bracketOnError from Control.Monad.Catch,
--   except this also protects against premature termination
bracketOnError :: (MonadSafe m) => Base m a -> (a -> Base m b) -> (a -> m c) -> m c
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Pipes.Safe.SafeT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.Safe.SafeT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Pipes.Safe.SafeT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.Safe.SafeT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Pipes.Safe.SafeT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Pipes.Safe.SafeT m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Pipes.Safe.SafeT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Pipes.Safe.SafeT m)
instance GHC.Base.Alternative m => GHC.Base.Alternative (Pipes.Safe.SafeT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Pipes.Safe.SafeT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.Internal.Proxy a' a b' b m)
instance (Control.Monad.Catch.MonadMask m, Control.Monad.IO.Class.MonadIO m) => Control.Monad.Catch.MonadMask (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Trans.Class.MonadTrans Pipes.Safe.SafeT
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Pipes.Safe.SafeT m)
instance (Control.Monad.IO.Class.MonadIO m, Control.Monad.Catch.MonadCatch m, Control.Monad.Catch.MonadMask m) => Pipes.Safe.MonadSafe (Pipes.Safe.SafeT m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Pipes.Internal.Proxy a' a b' b m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.Identity.IdentityT m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Catch.Pure.CatchT m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.Reader.ReaderT i m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.State.Lazy.StateT s m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.State.Strict.StateT s m)
instance (Pipes.Safe.MonadSafe m, GHC.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Pipes.Safe.MonadSafe m, GHC.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Pipes.Safe.MonadSafe m, GHC.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.RWS.Lazy.RWST i w s m)
instance (Pipes.Safe.MonadSafe m, GHC.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.RWS.Strict.RWST i w s m)

-- | Simple resource management functions
module Pipes.Safe.Prelude

-- | Acquire a Handle within MonadSafe
withFile :: (MonadSafe m) => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Read lines from a file, automatically opening and closing the file as
--   necessary
readFile :: (MonadSafe m) => FilePath -> Producer' String m ()

-- | Write lines to a file, automatically opening and closing the file as
--   necessary
writeFile :: (MonadSafe m) => FilePath -> Consumer' String m r
