-- 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.3.1.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. -- -- The number of stripes is arranged to be equal to the number of -- capabilities so that they never compete over access to the same -- stripe. This results in a very good performance in a multi-threaded -- environment. 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, capability-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 -> PoolConfig a -- | The action that creates a new resource. [createResource] :: PoolConfig a -> !IO a -- | The action that destroys an existing resource. [freeResource] :: PoolConfig a -> !a -> IO () -- | The amount of seconds for which an unused resource is kept around. The -- smallest acceptable value is 0.5. -- -- Note: the elapsed time before destroying a resource may be a -- little longer than requested, as the collector thread wakes at -- 1-second intervals. [poolCacheTTL] :: PoolConfig a -> !Double -- | The maximum number of resources to keep open across all stripes. The -- smallest acceptable value is 1. -- -- Note: for each stripe the number of resources is divided by the -- number of capabilities and rounded up. Therefore the pool might end up -- creating up to N - 1 resources more in total than specified, -- where N is the number of capabilities. [poolMaxResources] :: PoolConfig a -> !Int -- | Create a new striped resource pool. -- -- The number of stripes is equal to the number of capabilities. -- -- 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 capability-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 -- | Configuration of a Pool. data PoolConfig a PoolConfig :: !IO a -> !a -> IO () -> !Double -> !Int -> PoolConfig a -- | The action that creates a new resource. [createResource] :: PoolConfig a -> !IO a -- | The action that destroys an existing resource. [freeResource] :: PoolConfig a -> !a -> IO () -- | The amount of seconds for which an unused resource is kept around. The -- smallest acceptable value is 0.5. -- -- Note: the elapsed time before destroying a resource may be a -- little longer than requested, as the collector thread wakes at -- 1-second intervals. [poolCacheTTL] :: PoolConfig a -> !Double -- | The maximum number of resources to keep open across all stripes. The -- smallest acceptable value is 1. -- -- Note: for each stripe the number of resources is divided by the -- number of capabilities and rounded up. Therefore the pool might end up -- creating up to N - 1 resources more in total than specified, -- where N is the number of capabilities. [poolMaxResources] :: PoolConfig a -> !Int -- | Striped resource pool based on Control.Concurrent.QSem. -- -- The number of stripes is arranged to be equal to the number of -- capabilities so that they never compete over access to the same -- stripe. This results in a very good performance in a multi-threaded -- environment. data Pool a -- | A single, capability-local pool. data LocalPool a -- | Create a new striped resource pool. -- -- The number of stripes is equal to the number of capabilities. -- -- 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) -- | Take a resource from the pool, perform an action with it and return it -- to the pool afterwards. -- -- -- -- 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 capability-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 capability-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 -- | Configuration of a Pool. data PoolConfig a PoolConfig :: !IO a -> !a -> IO () -> !Double -> !Int -> PoolConfig a -- | The action that creates a new resource. [createResource] :: PoolConfig a -> !IO a -- | The action that destroys an existing resource. [freeResource] :: PoolConfig a -> !a -> IO () -- | The amount of seconds for which an unused resource is kept around. The -- smallest acceptable value is 0.5. -- -- Note: the elapsed time before destroying a resource may be a -- little longer than requested, as the collector thread wakes at -- 1-second intervals. [poolCacheTTL] :: PoolConfig a -> !Double -- | The maximum number of resources to keep open across all stripes. The -- smallest acceptable value is 1. -- -- Note: for each stripe the number of resources is divided by the -- number of capabilities and rounded up. Therefore the pool might end up -- creating up to N - 1 resources more in total than specified, -- where N is the number of capabilities. [poolMaxResources] :: PoolConfig a -> !Int -- | Striped resource pool based on Control.Concurrent.QSem. -- -- The number of stripes is arranged to be equal to the number of -- capabilities so that they never compete over access to the same -- stripe. This results in a very good performance in a multi-threaded -- environment. data Pool a -- | A single, capability-local pool. data LocalPool a -- | Create a new striped resource pool. -- -- The number of stripes is equal to the number of capabilities. -- -- 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) -- | 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 capability-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 capability-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.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)