-- 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.4.0.0


-- | Internal implementation details for <a>Data.Pool</a>.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Data.Pool.Internal

-- | Striped resource pool based on <a>Control.Concurrent.QSem</a>.
data Pool a
Pool :: !PoolConfig a -> !SmallArray (LocalPool a) -> !IORef () -> Pool a
[poolConfig] :: Pool a -> !PoolConfig a
[localPools] :: Pool a -> !SmallArray (LocalPool a)
[reaperRef] :: Pool a -> !IORef ()

-- | A single, local pool.
data LocalPool a
LocalPool :: !Int -> !MVar (Stripe a) -> !IORef () -> LocalPool a
[stripeId] :: LocalPool a -> !Int
[stripeVar] :: LocalPool a -> !MVar (Stripe a)
[cleanerRef] :: LocalPool a -> !IORef ()

-- | Stripe of a resource pool. If <tt>available</tt> is 0, the list of
--   threads waiting for a resource (each with an associated <a>MVar</a>)
--   is <tt>queue ++ reverse queueR</tt>.
data Stripe a
Stripe :: !Int -> ![Entry a] -> !Queue a -> !Queue a -> Stripe a
[available] :: Stripe a -> !Int
[cache] :: Stripe a -> ![Entry a]
[queue] :: Stripe a -> !Queue a
[queueR] :: Stripe a -> !Queue a

-- | An existing resource currently sitting in a pool.
data Entry a
Entry :: a -> !Double -> Entry a
[entry] :: Entry a -> a
[lastUsed] :: Entry a -> !Double

-- | A queue of MVarS corresponding to threads waiting for resources.
--   
--   Basically a monomorphic list to save two pointer indirections.
data Queue a
Queue :: !MVar (Maybe a) -> Queue a -> Queue a
Empty :: Queue a

-- | Configuration of a <a>Pool</a>.
data PoolConfig a
PoolConfig :: !IO a -> !a -> IO () -> !Double -> !Int -> !Maybe Int -> PoolConfig a
[createResource] :: PoolConfig a -> !IO a
[freeResource] :: PoolConfig a -> !a -> IO ()
[poolCacheTTL] :: PoolConfig a -> !Double
[poolMaxResources] :: PoolConfig a -> !Int
[poolNumStripes] :: PoolConfig a -> !Maybe Int

-- | Create a <a>PoolConfig</a> with optional parameters having default
--   values.
--   
--   For setting optional parameters have a look at:
--   
--   <ul>
--   <li><a>setNumStripes</a></li>
--   </ul>
defaultPoolConfig :: IO a -> (a -> IO ()) -> Double -> Int -> PoolConfig a

-- | Set the number of stripes in the pool.
--   
--   If set to <a>Nothing</a> (the default value), the pool will create the
--   amount of stripes equal to the number of capabilities. This ensures
--   that threads never compete over access to the same stripe and results
--   in a very good performance in a multi-threaded environment.
setNumStripes :: Maybe Int -> PoolConfig a -> PoolConfig a

-- | Create a new striped resource pool.
--   
--   <i>Note:</i> although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call <a>destroyAllResources</a> when you're done with the
--   pool so that the resources are freed up as soon as possible.
newPool :: PoolConfig a -> IO (Pool 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 <tt>takeResource</tt>
--   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 ()

-- | Get a local pool.
getLocalPool :: SmallArray (LocalPool a) -> IO (LocalPool a)

-- | Wait for the resource to be put into a given <a>MVar</a>.
waitForResource :: MVar (Stripe a) -> MVar (Maybe a) -> IO (Maybe a)

-- | If an exception is received while a resource is being created, restore
--   the original size of the stripe.
restoreSize :: MVar (Stripe a) -> IO ()

-- | Free resource entries in the stripes that fulfil a given condition.
cleanStripe :: (Entry a -> Bool) -> (a -> IO ()) -> MVar (Stripe a) -> IO ()
signal :: Stripe a -> Maybe a -> IO (Stripe a)
reverseQueue :: Queue a -> Queue a


-- | A high-performance pooling abstraction for managing flexibly-sized
--   collections of resources such as database connections.
module Data.Pool

-- | Striped resource pool based on <a>Control.Concurrent.QSem</a>.
data Pool a

-- | A single, local pool.
data LocalPool a

-- | Create a new striped resource pool.
--   
--   <i>Note:</i> although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call <a>destroyAllResources</a> when you're done with the
--   pool so that the resources are freed up as soon as possible.
newPool :: PoolConfig a -> IO (Pool a)

-- | Configuration of a <a>Pool</a>.
data PoolConfig a

-- | Create a <a>PoolConfig</a> with optional parameters having default
--   values.
--   
--   For setting optional parameters have a look at:
--   
--   <ul>
--   <li><a>setNumStripes</a></li>
--   </ul>
defaultPoolConfig :: IO a -> (a -> IO ()) -> Double -> Int -> PoolConfig a

-- | Set the number of stripes in the pool.
--   
--   If set to <a>Nothing</a> (the default value), the pool will create the
--   amount of stripes equal to the number of capabilities. This ensures
--   that threads never compete over access to the same stripe and results
--   in a very good performance in a multi-threaded environment.
setNumStripes :: Maybe Int -> PoolConfig a -> PoolConfig a

-- | Take a resource from the pool, 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 :: Pool a -> (a -> IO r) -> IO r

-- | Take a resource from the pool, following the same results as
--   <a>withResource</a>.
--   
--   <i>Note:</i> this function returns both a resource and the
--   <a>LocalPool</a> 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)

-- | A variant of <a>withResource</a> that doesn't execute the action and
--   returns <a>Nothing</a> instead of blocking if the local pool is
--   exhausted.
tryWithResource :: Pool a -> (a -> IO r) -> IO (Maybe r)

-- | A variant of <a>takeResource</a> that returns <a>Nothing</a> instead
--   of blocking if the local pool is exhausted.
tryTakeResource :: Pool a -> IO (Maybe (a, LocalPool a))

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

-- | Destroy a resource.
--   
--   Note that this will ignore any exceptions in the destroy function.
destroyResource :: Pool a -> 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 <tt>takeResource</tt>
--   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 ()

-- | Provided for compatibility with <tt>resource-pool &lt; 0.3</tt>.
--   
--   Use <a>newPool</a> instead.

-- | <i>Deprecated: Use newPool instead</i>
createPool :: IO a -> (a -> IO ()) -> Int -> NominalDiffTime -> Int -> IO (Pool a)


-- | A variant of <a>Data.Pool</a> with introspection capabilities.
module Data.Pool.Introspection

-- | Striped resource pool based on <a>Control.Concurrent.QSem</a>.
data Pool a

-- | A single, local pool.
data LocalPool a

-- | Create a new striped resource pool.
--   
--   <i>Note:</i> although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call <a>destroyAllResources</a> when you're done with the
--   pool so that the resources are freed up as soon as possible.
newPool :: PoolConfig a -> IO (Pool a)

-- | Configuration of a <a>Pool</a>.
data PoolConfig a

-- | Create a <a>PoolConfig</a> with optional parameters having default
--   values.
--   
--   For setting optional parameters have a look at:
--   
--   <ul>
--   <li><a>setNumStripes</a></li>
--   </ul>
defaultPoolConfig :: IO a -> (a -> IO ()) -> Double -> Int -> PoolConfig a

-- | Set the number of stripes in the pool.
--   
--   If set to <a>Nothing</a> (the default value), the pool will create the
--   amount of stripes equal to the number of capabilities. This ensures
--   that threads never compete over access to the same stripe and results
--   in a very good performance in a multi-threaded environment.
setNumStripes :: Maybe Int -> PoolConfig a -> PoolConfig a

-- | A resource taken from the pool along with additional information.
data Resource a
Resource :: a -> !Int -> !Int -> !Acquisition -> !Double -> !Maybe Double -> Resource a
[resource] :: Resource a -> a
[stripeNumber] :: Resource a -> !Int
[availableResources] :: Resource a -> !Int
[acquisition] :: Resource a -> !Acquisition
[acquisitionTime] :: Resource a -> !Double
[creationTime] :: Resource a -> !Maybe Double

-- | Describes how a resource was acquired from the pool.
data Acquisition

-- | A resource was taken from the pool immediately.
Immediate :: Acquisition

-- | The thread had to wait until a resource was released.
Delayed :: Acquisition

-- | <a>withResource</a> with introspection capabilities.
withResource :: Pool a -> (Resource a -> IO r) -> IO r

-- | <a>takeResource</a> with introspection capabilities.
takeResource :: Pool a -> IO (Resource a, LocalPool a)

-- | A variant of <a>withResource</a> that doesn't execute the action and
--   returns <a>Nothing</a> instead of blocking if the local pool is
--   exhausted.
tryWithResource :: Pool a -> (Resource a -> IO r) -> IO (Maybe r)

-- | A variant of <a>takeResource</a> that returns <a>Nothing</a> instead
--   of blocking if the local pool is exhausted.
tryTakeResource :: Pool a -> IO (Maybe (Resource a, LocalPool a))

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

-- | Destroy a resource.
--   
--   Note that this will ignore any exceptions in the destroy function.
destroyResource :: Pool a -> 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 <tt>takeResource</tt>
--   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 GHC.Generics.Generic Data.Pool.Introspection.Acquisition
instance GHC.Show.Show Data.Pool.Introspection.Acquisition
instance GHC.Classes.Eq Data.Pool.Introspection.Acquisition
instance GHC.Generics.Generic (Data.Pool.Introspection.Resource a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Pool.Introspection.Resource a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Pool.Introspection.Resource a)
