Data.Pool.Introspection

A variant of Data.Pool with introspection capabilities.

Pool

data PoolConfig a

Configuration of a Pool.

Constructors

PoolConfig

Fields

• createResource :: !(IO a)

  The action that creates a new resource.

• freeResource :: !(a -> IO ())

  The action that destroys an existing resource.

• poolCacheTTL :: !Double

  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.

• poolMaxResources :: !Int

  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.

data Pool a

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 LocalPool a

A single, capability-local pool.

newPool :: PoolConfig a -> IO (Pool 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.

Resource management

data Resource a

A resource taken from the pool along with additional information.

Constructors

Resource

Fields

• resource :: a
• stripeNumber :: !Int
• availableResources :: !Int
• acquisition :: !Acquisition
• acquisitionTime :: !Double
• creationTime :: !(Maybe Double)

Instances

Eq a => Eq (Resource a)

Defined in Data.Pool.Introspection

Methods

(==) :: Resource a -> Resource a -> Bool

(/=) :: Resource a -> Resource a -> Bool

Show a => Show (Resource a)

Defined in Data.Pool.Introspection

Methods

showsPrec :: Int -> Resource a -> ShowS

show :: Resource a -> String

showList :: [Resource a] -> ShowS

Generic (Resource a)

Defined in Data.Pool.Introspection

Associated Types

type Rep (Resource a) :: Type -> Type

Methods

from :: Resource a -> Rep (Resource a) x

to :: Rep (Resource a) x -> Resource a

type Rep (Resource a)

Defined in Data.Pool.Introspection

type Rep (Resource a) = D1 ('MetaData "Resource" "Data.Pool.Introspection" "resource-pool-0.3.1.0-Fnx9hvfaoooEyNcTCm2Pyr" 'False) (C1 ('MetaCons "Resource" 'PrefixI 'True) ((S1 ('MetaSel ('Just "resource") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a) :*: (S1 ('MetaSel ('Just "stripeNumber") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "availableResources") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int))) :*: (S1 ('MetaSel ('Just "acquisition") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Acquisition) :*: (S1 ('MetaSel ('Just "acquisitionTime") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double) :*: S1 ('MetaSel ('Just "creationTime") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Maybe Double))))))

data Acquisition

Describes how a resource was acquired from the pool.

Constructors

Immediate

A resource was taken from the pool immediately.

Delayed

The thread had to wait until a resource was released.

Instances

Eq Acquisition

Defined in Data.Pool.Introspection

Methods

(==) :: Acquisition -> Acquisition -> Bool

(/=) :: Acquisition -> Acquisition -> Bool

Show Acquisition

Defined in Data.Pool.Introspection

Methods

showsPrec :: Int -> Acquisition -> ShowS

show :: Acquisition -> String

showList :: [Acquisition] -> ShowS

Generic Acquisition

Defined in Data.Pool.Introspection

Associated Types

type Rep Acquisition :: Type -> Type

Methods

from :: Acquisition -> Rep Acquisition x

to :: Rep Acquisition x -> Acquisition

type Rep Acquisition

Defined in Data.Pool.Introspection

type Rep Acquisition = D1 ('MetaData "Acquisition" "Data.Pool.Introspection" "resource-pool-0.3.1.0-Fnx9hvfaoooEyNcTCm2Pyr" 'False) (C1 ('MetaCons "Immediate" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Delayed" 'PrefixI 'False) (U1 :: Type -> Type))

withResource :: Pool a -> (Resource a -> IO r) -> IO r

withResource with introspection capabilities.

takeResource :: Pool a -> IO (Resource a, LocalPool a)

takeResource with introspection capabilities.

tryWithResource :: Pool a -> (Resource a -> IO r) -> IO (Maybe r)

A variant of withResource that doesn't execute the action and returns Nothing instead of blocking if the capability-local pool is exhausted.

tryTakeResource :: Pool a -> IO (Maybe (Resource a, LocalPool a))

A variant of takeResource that returns Nothing instead of blocking if the capability-local pool is exhausted.

putResource :: LocalPool a -> a -> IO ()

Return a resource to the given LocalPool.

destroyResource :: Pool a -> LocalPool a -> a -> IO ()

Destroy a resource.

Note that this will ignore any exceptions in the destroy function.

destroyAllResources :: Pool 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.