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


-- | A high-performance striped resource pooling implementation
--   
--   A high-performance striped pooling abstraction for managing
--   flexibly-sized collections of resources such as database connections.
@package resource-pool
@version 0.2.3.2


-- | A high-performance striped pooling abstraction for managing
--   flexibly-sized collections of resources such as database connections.
--   
--   "Striped" means that a single <a>Pool</a> consists of several
--   sub-pools, each managed independently. A single stripe is fine for
--   many applications, and probably what you should choose by default.
--   More stripes will lead to reduced contention in high-performance
--   multicore applications, at a trade-off of causing the maximum number
--   of simultaneous resources in use to grow.
module Data.Pool
data Pool a

-- | A single striped pool.
data LocalPool a

-- | Create a striped resource pool.
--   
--   Although the garbage collector will destroy all idle resources when
--   the pool is garbage collected it's recommended to manually
--   <a>destroyAllResources</a> when you're done with the pool so that the
--   resources are freed up as soon as possible.
createPool :: IO a -> (a -> IO ()) -> Int -> NominalDiffTime -> Int -> IO (Pool a)

-- | Temporarily take a resource from a <a>Pool</a>, perform an action with
--   it, and return it to the pool afterwards.
--   
--   <ul>
--   <li>If the pool has an idle resource available, it is used
--   immediately.</li>
--   <li>Otherwise, if the maximum number of resources has not yet been
--   reached, a new resource is created and used.</li>
--   <li>If the maximum number of resources has been reached, this function
--   blocks until a resource becomes available.</li>
--   </ul>
--   
--   If the action throws an exception of any type, the resource is
--   destroyed, and not returned to the pool.
--   
--   It probably goes without saying that you should never manually destroy
--   a pooled resource, as doing so will almost certainly cause a
--   subsequent user (who expects the resource to be valid) to throw an
--   exception.
withResource :: MonadBaseControl IO m => Pool a -> (a -> m b) -> m b

-- | Take a resource from the pool, following the same results as
--   <a>withResource</a>. Note that this function should be used with
--   caution, as improper exception handling can lead to leaked resources.
--   
--   This function returns both a resource and the <tt>LocalPool</tt> it
--   came from so that it may either be destroyed (via
--   <a>destroyResource</a>) or returned to the pool (via
--   <a>putResource</a>).
takeResource :: Pool a -> IO (a, LocalPool a)

-- | Similar to <a>withResource</a>, but only performs the action if a
--   resource could be taken from the pool <i>without blocking</i>.
--   Otherwise, <a>tryWithResource</a> returns immediately with
--   <a>Nothing</a> (ie. the action function is <i>not</i> called).
--   Conversely, if a resource can be borrowed from the pool without
--   blocking, the action is performed and it's result is returned, wrapped
--   in a <a>Just</a>.
tryWithResource :: MonadBaseControl IO m => Pool a -> (a -> m b) -> m (Maybe b)

-- | A non-blocking version of <a>takeResource</a>. The
--   <a>tryTakeResource</a> function returns immediately, with
--   <a>Nothing</a> if the pool is exhausted, or <tt><a>Just</a> (a,
--   <a>LocalPool</a> a)</tt> if a resource could be borrowed from the pool
--   successfully.
tryTakeResource :: Pool a -> IO (Maybe (a, LocalPool a))

-- | Destroy a resource. Note that this will ignore any exceptions in the
--   destroy function.
destroyResource :: Pool a -> LocalPool a -> a -> IO ()

-- | Return a resource to the given <a>LocalPool</a>.
putResource :: LocalPool a -> a -> IO ()

-- | Destroy all resources in all stripes in the pool. Note that this will
--   ignore any exceptions in the destroy function.
--   
--   This function is useful when you detect that all resources in the pool
--   are broken. For example after a database has been restarted all
--   connections opened before the restart will be broken. In that case
--   it's better to close those connections so that <a>takeResource</a>
--   won't take a broken connection from the pool but will open a new
--   connection instead.
--   
--   Another use-case for this function is that when you know you are done
--   with the pool you can destroy all idle resources immediately instead
--   of waiting on the garbage collector to destroy them, thus freeing up
--   those resources sooner.
destroyAllResources :: Pool a -> IO ()
instance Typeable LocalPool
instance Typeable Pool
instance Show (Pool a)