| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.Pool
Description
A high-performance pooling abstraction for managing flexibly-sized collections of resources such as database connections.
Synopsis
-
data
PoolConfig
a =
PoolConfig
{
- createResource :: !( IO a)
- freeResource :: !(a -> IO ())
- poolCacheTTL :: ! Double
- poolMaxResources :: ! Int
- data Pool a
- data LocalPool a
- newPool :: PoolConfig a -> IO ( Pool a)
- withResource :: Pool a -> (a -> IO r) -> IO r
- takeResource :: Pool a -> IO (a, LocalPool a)
- tryWithResource :: Pool a -> (a -> IO r) -> IO ( Maybe r)
- tryTakeResource :: Pool a -> IO ( Maybe (a, LocalPool a))
- putResource :: LocalPool a -> a -> IO ()
- destroyResource :: Pool a -> LocalPool a -> a -> IO ()
- destroyAllResources :: Pool a -> IO ()
- createPool :: IO a -> (a -> IO ()) -> Int -> NominalDiffTime -> Int -> IO ( Pool a)
Pool
data PoolConfig a Source #
Configuration of a
Pool
.
Constructors
| PoolConfig | |
|
Fields
|
|
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.
newPool :: PoolConfig a -> IO ( Pool a) Source #
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
withResource :: Pool a -> (a -> IO r) -> IO r Source #
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) Source #
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) Source #
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 (a, LocalPool a)) Source #
A variant of
takeResource
that returns
Nothing
instead of blocking if
the capability-local pool is exhausted.
destroyResource :: Pool a -> LocalPool a -> a -> IO () Source #
Destroy a resource.
Note that this will ignore any exceptions in the destroy function.
destroyAllResources :: Pool a -> IO () Source #
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.