-- 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
--   <tt>pipes</tt> ecosystem.
--   
--   Notable features include:
--   
--   <ul>
--   <li><i>Resource Safety</i>: Guarantee finalization using
--   <tt>finally</tt>, <tt>bracket</tt> and more</li>
--   <li><i>Exception Safety</i>: Even against asynchronous
--   exceptions!</li>
--   <li><i>Laziness</i>: Only acquire resources when you need them</li>
--   <li><i>Promptness</i>: Finalize resources early when you are done with
--   them</li>
--   <li><i>Native Exception Handling</i>: Catch and resume from exceptions
--   inside pipes</li>
--   <li><i>No Buy-in</i>: Mix resource-safe pipes with unmanaged pipes
--   using <tt>hoist</tt></li>
--   </ul>
@package pipes-safe
@version 2.3.5


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

-- | <a>SafeT</a> is a monad transformer that extends the base monad with
--   the ability to <a>register</a> and <a>release</a> finalizers.
--   
--   All unreleased finalizers are called at the end of the <a>SafeT</a>
--   block, even in the event of exceptions.
newtype SafeT (m :: Type -> Type) r

-- | Constructor exported in case it's necessary for integrating
--   <a>SafeT</a> with other libraries. For example, implementing
--   <tt>mtl</tt>-like Monad<i>Something</i> instances will often require
--   access to the <a>SafeT</a> constructor.
--   
--   Warning: Using the <a>Env</a> outside the corresponding <a>SafeT</a>
--   scope will result in undefined behavior.
SafeT :: ReaderT (Env m) m r -> SafeT (m :: Type -> Type) r

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

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

-- | Token used to <a>release</a> a previously <a>register</a>ed finalizer
data ReleaseKey

-- | <a>MonadSafe</a> lets you <a>register</a> and <a>release</a>
--   finalizers that execute in a <a>Base</a> monad
class (MonadCatch m, MonadMask m, MonadIO m, MonadIO Base m) => MonadSafe (m :: Type -> Type) where {
    
    -- | The monad used to run resource management actions, corresponding to
    --   the monad directly beneath <a>SafeT</a>
    type Base (m :: Type -> Type) :: Type -> Type;
}

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

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

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

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

-- | Transform a <a>Proxy</a> into one that catches any exceptions caused
--   by its effects, and returns the resulting exception.
tryP :: forall (m :: Type -> Type) e a' a b' b r. (MonadSafe m, Exception e) => Proxy a' a b' b m r -> Proxy a' a b' b m (Either e r)

-- | Allows direct handling of exceptions raised by the effects in a
--   <a>Proxy</a>.
catchP :: forall (m :: Type -> Type) e a' a b' b r. (MonadSafe m, Exception e) => Proxy a' a b' b m r -> (e -> Proxy a' a b' b m r) -> Proxy a' a b' b m r

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

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

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

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

-- | Internal <a>SafeT</a> read-write environment. Exported only so that it
--   can be passed around unmodified by users of the <a>SafeT</a>
--   constructor.
--   
--   Warning: Using the <a>Env</a> outside the corresponding <a>SafeT</a>
--   scope will result in undefined behavior.
data Env (m :: Type -> Type)
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
displayException :: Exception e => e -> String
backtraceDesired :: Exception e => e -> Bool
data SomeException
class MonadThrow m => MonadCatch (m :: Type -> Type)
catch :: (MonadCatch m, HasCallStack, Exception e) => m a -> (e -> m a) -> m a
class Monad m => MonadThrow (m :: Type -> Type)
throwM :: (MonadThrow m, HasCallStack, Exception e) => e -> m a
class MonadCatch m => MonadMask (m :: Type -> Type)
mask :: (MonadMask m, HasCallStack) => ((forall a. () => m a -> m a) -> m b) -> m b
uninterruptibleMask :: (MonadMask m, HasCallStack) => ((forall a. () => m a -> m a) -> m b) -> m b
generalBracket :: (MonadMask m, HasCallStack) => m a -> (a -> ExitCase b -> m c) -> (a -> m b) -> m (b, c)
data ExitCase a
ExitCaseSuccess :: a -> ExitCase a
ExitCaseException :: SomeException -> ExitCase a
ExitCaseAbort :: ExitCase a
mask_ :: (HasCallStack, MonadMask m) => m a -> m a
uninterruptibleMask_ :: (HasCallStack, MonadMask m) => m a -> m a
catchAll :: (HasCallStack, MonadCatch m) => m a -> (SomeException -> m a) -> m a
catchIOError :: (HasCallStack, MonadCatch m) => m a -> (IOError -> m a) -> m a
catchJust :: (HasCallStack, MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
catchIf :: (HasCallStack, MonadCatch m, Exception e) => (e -> Bool) -> m a -> (e -> m a) -> m a
data Handler (m :: Type -> Type) a
Handler :: (e -> m a) -> Handler (m :: Type -> Type) a
catches :: (HasCallStack, Foldable f, MonadCatch m) => m a -> f (Handler m a) -> m a
handle :: (HasCallStack, MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
handleAll :: (HasCallStack, MonadCatch m) => (SomeException -> m a) -> m a -> m a
handleIOError :: (HasCallStack, MonadCatch m) => (IOError -> m a) -> m a -> m a
handleJust :: (HasCallStack, MonadCatch m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
handleIf :: (HasCallStack, MonadCatch m, Exception e) => (e -> Bool) -> (e -> m a) -> m a -> m a
tryJust :: (HasCallStack, MonadCatch m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
displayException :: Exception e => e -> String
backtraceDesired :: Exception e => e -> Bool
data SomeException
SomeException :: e -> SomeException
instance GHC.Internal.Base.Alternative m => GHC.Internal.Base.Alternative (Pipes.Safe.SafeT m)
instance GHC.Internal.Base.Applicative m => GHC.Internal.Base.Applicative (Pipes.Safe.SafeT m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Pipes.Safe.SafeT m)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Pipes.Safe.SafeT m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.Safe.SafeT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Pipes.Safe.SafeT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Pipes.Safe.SafeT m)
instance GHC.Internal.Control.Monad.Fail.MonadFail m => GHC.Internal.Control.Monad.Fail.MonadFail (Pipes.Safe.SafeT m)
instance GHC.Internal.Control.Monad.Fix.MonadFix m => GHC.Internal.Control.Monad.Fix.MonadFix (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.IO.Class.MonadIO m) => Control.Monad.Catch.MonadMask (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Pipes.Safe.SafeT m)
instance GHC.Internal.Base.MonadPlus m => GHC.Internal.Base.MonadPlus (Pipes.Safe.SafeT m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Monad (Pipes.Safe.SafeT 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.Identity.IdentityT m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Pipes.Internal.Proxy a' a b' b m)
instance (Pipes.Safe.MonadSafe m, GHC.Internal.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.RWS.Strict.RWST i w s m)
instance (Pipes.Safe.MonadSafe m, GHC.Internal.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.RWS.Lazy.RWST i w s m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.Reader.ReaderT i 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 (Control.Monad.Trans.State.Strict.StateT s m)
instance Pipes.Safe.MonadSafe m => Pipes.Safe.MonadSafe (Control.Monad.Trans.State.Lazy.StateT s m)
instance (Pipes.Safe.MonadSafe m, GHC.Internal.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Pipes.Safe.MonadSafe m, GHC.Internal.Base.Monoid w) => Pipes.Safe.MonadSafe (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Pipes.Safe.SafeT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.Safe.SafeT m)
instance Control.Monad.Trans.Class.MonadTrans Pipes.Safe.SafeT
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.Safe.SafeT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Pipes.Safe.SafeT m)


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

-- | Acquire a <a>Handle</a> within <a>MonadSafe</a>
--   
--   The file is opened in text mode. See also: <a>withBinaryFile</a>
withFile :: MonadSafe m => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Like <a>withFile</a>, but open the file in binary mode
--   
--   See <a>hSetBinaryMode</a> for the differences between binary and text
--   mode.
withBinaryFile :: MonadSafe m => FilePath -> IOMode -> (Handle -> m r) -> m r

-- | Acquire a <a>Handle</a> within <a>MonadSafe</a>
--   
--   The <a>ReleaseKey</a> can be used to close the handle with
--   <a>release</a>; otherwise the handle will be closed automatically at
--   the conclusion of the <a>MonadSafe</a> block.
--   
--   The file is opened in text mode. See also: <a>openBinaryFile</a>
openFile :: MonadSafe m => FilePath -> IOMode -> m (ReleaseKey, Handle)

-- | Like <a>openFile</a>, but open the file in binary mode
--   
--   See <a>hSetBinaryMode</a> for the differences between binary and text
--   mode.
openBinaryFile :: MonadSafe m => FilePath -> IOMode -> m (ReleaseKey, Handle)

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

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

-- | Acquire some resource with a guarantee that it will eventually be
--   released
--   
--   The <a>ReleaseKey</a> can be passed to <a>release</a> to release the
--   resource manually. If this has not been done by the end of the
--   <a>MonadSafe</a> block, the resource will be released automatically.
allocate :: MonadSafe m => Base m a -> (a -> Base m ()) -> m (ReleaseKey, a)

-- | Like <a>allocate</a>, but for when the resource itself is not needed
--   
--   The acquire action runs immediately. The <a>ReleaseKey</a> can be
--   passed to <a>release</a> to run the release action. If this has not
--   been done by the end of the <a>MonadSafe</a> block, the release action
--   will be run automatically.
allocate_ :: MonadSafe m => Base m a -> Base m () -> m ReleaseKey
