Data.Pool

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

Pool

data Pool a

Striped resource pool based on Control.Concurrent.QSem.

data LocalPool a

A single, local pool.

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

Configuration

data PoolConfig a

Configuration of a Pool.

defaultPoolConfig

Arguments

:: IO a

The action that creates a new resource.

-> (a -> IO ())

The action that destroys an existing resource.

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

-> 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 stripes and rounded up, hence the pool might end up creating up to N - 1 resources more in total than specified, where N is the number of stripes.

-> PoolConfig a

Create a PoolConfig with optional parameters having default values.

For setting optional parameters have a look at:

• setNumStripes

Since: 0.4.0.0

setNumStripes :: Maybe Int -> PoolConfig a -> 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.

Since: 0.4.0.0

Resource management

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

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.

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

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

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

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

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

A variant of takeResource that returns Nothing instead of blocking if the 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.

Compatibility with 0.2

createPool :: IO a -> (a -> IO ()) -> Int -> NominalDiffTime -> Int -> IO (Pool a)

Deprecated: Use newPool instead

Provided for compatibility with resource-pool < 0.3.

Use newPool instead.