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


-- | Exception safe resource management with dynamic regions
--   
--   Region owns resources and automatically frees them on exit. It is a
--   plain old ADT, so it is possible to pass it to functions, put into
--   mutable references, store in regular data types.
--   
--   Resources can be freed earler or transfered to other regions.
--   
--   Region itself can be used as any other resource. E.g. one region can
--   own other one.
--   
--   The library doesn't pretend to solve double throw issue.
@package io-region
@version 0.1.1


-- | Exception safe resource management
--   
--   Examples:
--   
--   <pre>
--   import Control.IO.Region (region)
--   import qualified Control.IO.Region as R
--   
--   ...
--     region $ \r -&gt; do
--       resource &lt;- R.alloc_ r allocate free
--       use resource
--       -- resource will be automatically freed here
--   
--   ...
--     region $ \r -&gt; do
--       (resource, key) &lt;- R.alloc r allocate free
--       use resource
--       if ...
--         then R.free key  -- free it earler
--         else use resource
--   
--   ...
--     region $ \r1 -&gt; do
--       resource &lt;- region $ \r2 -&gt; do
--         (resource1, key) &lt;- R.alloc r2 allocate free
--         use resource
--         resource `R.moveTo` r1  -- transfer ownership to region r1
--         return resource
--       doSomethingElse resource
--       -- resource will be freed here
--   
--   ...
--     region $ \r1 -&gt; do
--       (r2, r2Key) &lt;- R.alloc r1 R.open R.close  -- region is a resource too
--       resource &lt;- R.alloc r2 allocate free
--       use resource
--       r2Key `R.moveTo` r3  -- move region r2 ownership (and also the resource) to other region
--   </pre>
module Control.IO.Region

-- | Region owns resources and frees them on close
data Region

-- | Each resource is identified by unique key
data Key

-- | Region already closed
data AlreadyClosed
AlreadyClosed :: AlreadyClosed

-- | Resource already freed
data AlreadyFreed
AlreadyFreed :: AlreadyFreed

-- | Create new region. It will be automatically closed on exit
region :: (Region -> IO a) -> IO a

-- | Open new region. Prefer <a>region</a> function.
open :: IO Region

-- | Close the region. You probably should called it when async exceptions
--   are masked. Prefer <a>region</a> function. It is error to close region
--   twice.
--   
--   In case of exception inside any cleanup handler, other handlers will
--   be called anyway. The last exception will be rethrown (that matches
--   the behavior of <a>bracket</a>.)
close :: Region -> IO ()

-- | Allocate resource inside the region
alloc :: Region -> IO a -> (a -> IO ()) -> IO (a, Key)

-- | The same as <a>alloc</a>, but doesn't return the key
alloc_ :: Region -> IO a -> (a -> IO ()) -> IO a

-- | Free the resource earlier then it's region will be closed. It will be
--   removed from the region immediately. It is error to free resource
--   twice
free :: Key -> IO ()

-- | Move resource to other region. The old key becomes invalid and should
--   not be used
moveToSTM :: Key -> Region -> STM Key

-- | Move resource to other region. See also <a>moveToSTM</a>
moveTo :: Key -> Region -> IO Key

-- | Defer action until region is closed
defer :: Region -> IO () -> IO ()
instance GHC.Show.Show Control.IO.Region.AlreadyFreed
instance GHC.Show.Show Control.IO.Region.AlreadyClosed
instance GHC.Show.Show Control.IO.Region.NotFound
instance GHC.Classes.Eq Control.IO.Region.Region
instance GHC.Classes.Eq Control.IO.Region.Key
instance GHC.Exception.Exception Control.IO.Region.AlreadyFreed
instance GHC.Exception.Exception Control.IO.Region.AlreadyClosed
instance GHC.Exception.Exception Control.IO.Region.NotFound
