-- 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 Data.Pool.
--   
--   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 Control.Concurrent.QSem.
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 available is 0, the list of
--   threads waiting for a resource (each with an associated MVar)
--   is queue ++ reverse queueR.
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 Pool.
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 PoolConfig with optional parameters having default
--   values.
--   
--   For setting optional parameters have a look at:
--   
--   
--   
- setNumStripes
--   
defaultPoolConfig :: IO a -> (a -> IO ()) -> Double -> Int -> PoolConfig a

-- | Set the number of stripes in the pool.
--   
--   If set to Nothing (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.
--   
--   Note: although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call destroyAllResources 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 LocalPool.
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 takeResource
--   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 MVar.
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 Control.Concurrent.QSem.
data Pool a

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

-- | Create a new striped resource pool.
--   
--   Note: although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call destroyAllResources 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 Pool.
data PoolConfig a

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

-- | Set the number of stripes in the pool.
--   
--   If set to Nothing (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.
--   
--   
--   
- If the pool has an idle resource available, it is used
--   immediately.
--   
- Otherwise, if the maximum number of resources has not yet been
--   reached, a new resource is created and used.
--   
- If the maximum number of resources has been reached, this function
--   blocks until a resource becomes available.
--   
--   
--   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
--   withResource.
--   
--   Note: this function returns both a resource and the
--   LocalPool it came from so that it may either be destroyed (via
--   destroyResource) or returned to the pool (via
--   putResource).
takeResource :: Pool a -> IO (a, LocalPool a)

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

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

-- | Return a resource to the given LocalPool.
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 takeResource
--   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 resource-pool < 0.3.
--   
--   Use newPool instead.

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

-- | A variant of Data.Pool with introspection capabilities.
module Data.Pool.Introspection

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

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

-- | Create a new striped resource pool.
--   
--   Note: although the runtime system will destroy all idle
--   resources when the pool is garbage collected, it's recommended to
--   manually call destroyAllResources 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 Pool.
data PoolConfig a

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

-- | Set the number of stripes in the pool.
--   
--   If set to Nothing (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

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

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

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

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

-- | Return a resource to the given LocalPool.
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 takeResource
--   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.Classes.Eq Data.Pool.Introspection.Acquisition
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Pool.Introspection.Resource a)
instance GHC.Internal.Generics.Generic Data.Pool.Introspection.Acquisition
instance GHC.Internal.Generics.Generic (Data.Pool.Introspection.Resource a)
instance GHC.Internal.Show.Show Data.Pool.Introspection.Acquisition
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Pool.Introspection.Resource a)
