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


-- | A monad for managed values
--   
--   In Haskell you very often acquire values using the <tt>with...</tt>
--   idiom using functions of type <tt>(a -&gt; IO r) -&gt; IO r</tt>. This
--   idiom forms a <tt>Monad</tt>, which is a special case of the
--   <tt>ContT</tt> monad (from <tt>transformers</tt>) or the
--   <tt>Codensity</tt> monad (from <tt>kan-extensions</tt>). The main
--   purpose behind this package is to provide a restricted form of these
--   monads specialized to this unusually common case.
--   
--   The reason this package defines a specialized version of these types
--   is to:
--   
--   <ul>
--   <li>be more beginner-friendly,</li>
--   <li>simplify inferred types and error messages, and:</li>
--   <li>provide some additional type class instances that would otherwise
--   be orphan instances</li>
--   </ul>
@package managed
@version 1.0.5


-- | An example Haskell program to copy data from one handle to another
--   might look like this:
--   
--   <pre>
--   main =
--       withFile "inFile.txt" ReadMode $ \inHandle -&gt;
--           withFile "outFile.txt" WriteMode $ \outHandle -&gt;
--               copy inHandle outHandle
--   
--   -- A hypothetical function that copies data from one handle to another
--   copy :: Handle -&gt; Handle -&gt; IO ()
--   </pre>
--   
--   <a>withFile</a> is one of many functions that acquire some resource in
--   an exception-safe way. These functions take a callback function as an
--   argument and they invoke the callback on the resource when it becomes
--   available, guaranteeing that the resource is properly disposed if the
--   callback throws an exception.
--   
--   These functions usually have a type that ends with the following
--   pattern:
--   
--   <pre>
--                      Callback
--   --                -----------
--   withXXX :: ... -&gt; (a -&gt; IO r) -&gt; IO r
--   </pre>
--   
--   Here are some examples of this pattern from the <tt>base</tt>
--   libraries:
--   
--   <pre>
--   withArray      :: Storable a =&gt; [a] -&gt; (Ptr a   -&gt; IO r) -&gt; IO r
--   withBuffer     ::          Buffer e -&gt; (Ptr e   -&gt; IO r) -&gt; IO r
--   withCAString   ::            String -&gt; (CString -&gt; IO r) -&gt; IO r
--   withForeignPtr ::      ForeignPtr a -&gt; (Ptr a   -&gt; IO r) -&gt; IO r
--   withMVar       ::            Mvar a -&gt; (a       -&gt; IO r) -&gt; IO r
--   withPool       ::                      (Pool    -&gt; IO r) -&gt; IO r
--   </pre>
--   
--   Acquiring multiple resources in this way requires nesting callbacks.
--   However, you can wrap anything of the form <tt>((a -&gt; IO r) -&gt;
--   IO r)</tt> in the <a>Managed</a> monad, which translates binds to
--   callbacks for you:
--   
--   <pre>
--   import Control.Monad.Managed
--   import System.IO
--   
--   inFile :: FilePath -&gt; Managed Handle
--   inFile filePath = managed (withFile filePath ReadMode)
--   
--   outFile :: FilePath -&gt; Managed Handle
--   outFile filePath = managed (withFile filePath WriteMode)
--   
--   main = runManaged $ do
--       inHandle  &lt;- inFile "inFile.txt"
--       outHandle &lt;- outFile "outFile.txt"
--       liftIO (copy inHandle outHandle)
--   </pre>
--   
--   ... or you can just wrap things inline:
--   
--   <pre>
--   main = runManaged $ do
--       inHandle  &lt;- managed (withFile "inFile.txt" ReadMode)
--       outHandle &lt;- managed (withFile "outFile.txt" WriteMode)
--       liftIO (copy inHandle outHandle)
--   </pre>
--   
--   Additionally, since <a>Managed</a> is a <a>Monad</a>, you can take
--   advantage of all your favorite combinators from <a>Control.Monad</a>.
--   For example, the <a>withMany</a> function from
--   <a>Foreign.Marshal.Utils</a> becomes a trivial wrapper around
--   <a>mapM</a>:
--   
--   <pre>
--   withMany :: (a -&gt; (b -&gt; IO r) -&gt; IO r) -&gt; [a] -&gt; ([b] -&gt; IO r) -&gt; IO r
--   withMany f = with . mapM (Managed . f)
--   </pre>
--   
--   Another reason to use <a>Managed</a> is that if you wrap a
--   <a>Monoid</a> value in <a>Managed</a> you get back a new
--   <a>Monoid</a>:
--   
--   <pre>
--   instance Monoid a =&gt; Monoid (Managed a)
--   </pre>
--   
--   This lets you combine managed resources transparently. You can also
--   lift operations from some numeric type classes this way, too, such as
--   the <a>Num</a> type class.
--   
--   NOTE: <a>Managed</a> may leak space if used in an infinite loop like
--   this example:
--   
--   <pre>
--   import Control.Monad
--   import Control.Monad.Managed
--   
--   main = runManaged (forever (liftIO (print 1)))
--   </pre>
--   
--   If you need to acquire a resource for a long-lived loop, you can
--   instead acquire the resource first and run the loop in <a>IO</a>,
--   using either of the following two equivalent idioms:
--   
--   <pre>
--   with resource (\r -&gt; forever (useThe r))
--   
--   do r &lt;- resource
--      liftIO (forever (useThe r))
--   </pre>
module Control.Monad.Managed

-- | A managed resource that you acquire using <a>with</a>
data Managed a

-- | You can embed a <a>Managed</a> action within any <a>Monad</a> that
--   implements <a>MonadManaged</a> by using the <a>using</a> function
--   
--   All instances must obey the following two laws:
--   
--   <pre>
--   using (return x) = return x
--   
--   using (m &gt;&gt;= f) = using m &gt;&gt;= \x -&gt; using (f x)
--   </pre>
class MonadIO m => MonadManaged m
using :: MonadManaged m => Managed a -> m a

-- | Build a <a>Managed</a> value
managed :: (forall r. (a -> IO r) -> IO r) -> Managed a

-- | Like <a>managed</a> but for resource-less operations.
managed_ :: (forall r. IO r -> IO r) -> Managed ()

-- | Acquire a <a>Managed</a> value
with :: Managed a -> (a -> IO r) -> IO r

-- | Run a <a>Managed</a> computation, enforcing that no acquired resources
--   leak
runManaged :: Managed () -> IO ()
instance GHC.Base.Functor Control.Monad.Managed.Managed
instance GHC.Base.Applicative Control.Monad.Managed.Managed
instance GHC.Base.Monad Control.Monad.Managed.Managed
instance Control.Monad.IO.Class.MonadIO Control.Monad.Managed.Managed
instance GHC.Base.Monoid a => GHC.Base.Monoid (Control.Monad.Managed.Managed a)
instance GHC.Num.Num a => GHC.Num.Num (Control.Monad.Managed.Managed a)
instance GHC.Real.Fractional a => GHC.Real.Fractional (Control.Monad.Managed.Managed a)
instance GHC.Float.Floating a => GHC.Float.Floating (Control.Monad.Managed.Managed a)
instance Control.Monad.Managed.MonadManaged Control.Monad.Managed.Managed
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Cont.ContT r m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monoid w, Control.Monad.Managed.MonadManaged m) => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, Control.Monad.Managed.MonadManaged m) => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Managed.MonadManaged m => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Managed.MonadManaged m) => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Managed.MonadManaged m) => Control.Monad.Managed.MonadManaged (Control.Monad.Trans.Writer.Lazy.WriterT w m)


-- | This module is a safer subset of <a>Control.Monad.Managed</a> that
--   only lets you unwrap the <a>Managed</a> type using <a>runManaged</a>.
--   This enforces that you never leak acquired resources from a
--   <a>Managed</a> computation.
--   
--   In general, you should strive to propagate the <a>Managed</a> type as
--   much as possible and use <a>runManaged</a> when you are done with
--   acquired resources. However, there are legitimate circumstances where
--   you want to return a value other than acquired resource from the
--   bracketed computation, which requires using <a>with</a>.
--   
--   This module is not the default because you can also use the
--   <a>Managed</a> type for callback-based code that is completely
--   unrelated to resources.
module Control.Monad.Managed.Safe

-- | A managed resource that you acquire using <a>with</a>
data Managed a

-- | You can embed a <a>Managed</a> action within any <a>Monad</a> that
--   implements <a>MonadManaged</a> by using the <a>using</a> function
--   
--   All instances must obey the following two laws:
--   
--   <pre>
--   using (return x) = return x
--   
--   using (m &gt;&gt;= f) = using m &gt;&gt;= \x -&gt; using (f x)
--   </pre>
class MonadIO m => MonadManaged m
using :: MonadManaged m => Managed a -> m a

-- | Build a <a>Managed</a> value
managed :: (forall r. (a -> IO r) -> IO r) -> Managed a

-- | Like <a>managed</a> but for resource-less operations.
managed_ :: (forall r. IO r -> IO r) -> Managed ()

-- | Run a <a>Managed</a> computation, enforcing that no acquired resources
--   leak
runManaged :: Managed () -> IO ()
