-- 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: -- -- 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: -- -- 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 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: -- -- 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.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)