resource-pool-0.4.0.0: A high-performance striped resource pooling implementation

Safe Haskell | None
Language | Haskell2010

Data.Pool.Introspection

Contents

- Pool
  - Configuration
- Resource management

Description

A variant of Data.Pool with introspection capabilities.

Synopsis

- data Pool a
- data LocalPool a
- newPool :: PoolConfig a -> IO (Pool a)
- data PoolConfig a
- defaultPoolConfig :: IO a -> (a -> IO ()) -> Double -> Int -> PoolConfig a
- setNumStripes :: Maybe Int -> PoolConfig a -> PoolConfig a
- data Resource a = Resource {
  - resource :: a
  - stripeNumber :: !Int
  - availableResources :: !Int
  - acquisition :: !Acquisition
  - acquisitionTime :: !Double
  - creationTime :: !(Maybe Double)
  }
- data Acquisition
  - = Immediate
  - | Delayed
- withResource :: Pool a -> (Resource a -> IO r) -> IO r
- takeResource :: Pool a -> IO (Resource a, LocalPool a)
- tryWithResource :: Pool a -> (Resource a -> IO r) -> IO (Maybe r)
- tryTakeResource :: Pool a -> IO (Maybe (Resource a, LocalPool a))
- putResource :: LocalPool a -> a -> IO ()
- destroyResource :: Pool a -> LocalPool a -> a -> IO ()
- destroyAllResources :: Pool a -> IO ()

# Pool

data Pool a Source #

Striped resource pool based on Control.Concurrent.QSem.

data LocalPool a Source #

A single, local pool.

newPool :: PoolConfig a -> IO (Pool a) Source #

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 Source #

Configuration of a `Pool`.

defaultPoolConfig Source #

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 Source #

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

data Resource a Source #

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

Instances details

Generic (Resource a) Source # |

Instance details

Defined in Data.Pool.Introspection

Associated Types

type Rep (Resource a) |

Instance details

Defined in Data.Pool.Introspection

type Rep (Resource a) = D1 ('MetaData "Resource" "Data.Pool.Introspection" "resource-pool-0.4.0.0-JAoD4KCIxoh1g6d8FRZKpg" '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))))))

Methods

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

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

Show a => Show (Resource a) Source # |
Instance details Defined in Data.Pool.Introspection Methods showsPrec :: Int -> Resource a -> ShowS Source # show :: Resource a -> String Source # showList :: [Resource a] -> ShowS Source #
Eq a => Eq (Resource a) Source # |
Instance details Defined in Data.Pool.Introspection Methods (==) :: Resource a -> Resource a -> Bool Source # (/=) :: Resource a -> Resource a -> Bool Source #
type Rep (Resource a) Source # |

Instance details

Defined in Data.Pool.Introspection

type Rep (Resource a) = D1 ('MetaData "Resource" "Data.Pool.Introspection" "resource-pool-0.4.0.0-JAoD4KCIxoh1g6d8FRZKpg" '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 Source #

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

Instances details

Generic Acquisition Source # |

Instance details

Defined in Data.Pool.Introspection

Associated Types

type Rep Acquisition |
Instance details Defined in Data.Pool.Introspection type Rep Acquisition = D1 ('MetaData "Acquisition" "Data.Pool.Introspection" "resource-pool-0.4.0.0-JAoD4KCIxoh1g6d8FRZKpg" 'False) (C1 ('MetaCons "Immediate" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Delayed" 'PrefixI 'False) (U1 :: Type -> Type))

Methods

from :: Acquisition -> Rep Acquisition x Source #

to :: Rep Acquisition x -> Acquisition Source #

Show Acquisition Source # |
Instance details Defined in Data.Pool.Introspection Methods showsPrec :: Int -> Acquisition -> ShowS Source # show :: Acquisition -> String Source # showList :: [Acquisition] -> ShowS Source #
Eq Acquisition Source # |
Instance details Defined in Data.Pool.Introspection Methods (==) :: Acquisition -> Acquisition -> Bool Source # (/=) :: Acquisition -> Acquisition -> Bool Source #
type Rep Acquisition Source # |
Instance details Defined in Data.Pool.Introspection type Rep Acquisition = D1 ('MetaData "Acquisition" "Data.Pool.Introspection" "resource-pool-0.4.0.0-JAoD4KCIxoh1g6d8FRZKpg" '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 Source #

`withResource` with introspection capabilities.

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

`takeResource` with introspection capabilities.

tryWithResource :: Pool a -> (Resource 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 local pool is exhausted.

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

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

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

Return a resource to the given `LocalPool`.

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.