Z.IO.Resource

This module also implements Gabriel Gonzalez'd idea on Resource applicative: http://www.haskellforall.com/2013/06/the-resource-applicative.html. The Applicative and Monad instance is especially useful when you want safely combine multiple resources.

A high performance resource pool based on STM is also provided.

Resource management

newtype Resource a

A Resource is an IO action which acquires some resource of type a and also returns a finalizer of type IO () that releases the resource.

The only safe way to use a Resource is withResource and withResource', You should not use the acquire field directly, unless you want to implement your own resource management. In the later case, you should mask_ acquire since some resource initializations may assume async exceptions are masked.

MonadIO instance is provided so that you can lift IO computation inside Resource, this is convenient for propagating Resource around since many IO computations carry finalizers.

A convention in Z-IO is that functions returning a Resource should be named in initXXX format, users are strongly recommended to follow this convention.

There're two additional guarantees we made in Z-IO:

• All resources in Z-IO can track its own liveness, throw ResourceVanished exception using throwECLOSED or throwECLOSEDSTM when used after resource is closed.
• All resources' clean up action in Z-IO is idempotent.

Library authors providing initXXX are also encouraged to provide these guarantees.

Constructors

Resource

Fields

• acquire :: HasCallStack => IO (a, IO ())

Instances

Monad Resource

Defined in Z.IO.Resource

Methods

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

(>>) :: Resource a -> Resource b -> Resource b

return :: a -> Resource a

Functor Resource

Defined in Z.IO.Resource

Methods

fmap :: (a -> b) -> Resource a -> Resource b

(<$) :: a -> Resource b -> Resource a

Applicative Resource

Defined in Z.IO.Resource

Methods

pure :: a -> Resource a

(<*>) :: Resource (a -> b) -> Resource a -> Resource b

liftA2 :: (a -> b -> c) -> Resource a -> Resource b -> Resource c

(*>) :: Resource a -> Resource b -> Resource b

(<*) :: Resource a -> Resource b -> Resource a

MonadIO Resource

Defined in Z.IO.Resource

Methods

liftIO :: IO a -> Resource a

initResource :: IO a -> (a -> IO ()) -> Resource a

Create Resource from create and release action.

Note, resource doesn't open resource itself, resource is created when you use with / with'.

initResource_ :: IO () -> IO () -> Resource ()

Create Resource from create and release action.

This function is useful when you want to add some initialization and clean up action inside Resource monad.

withResource :: (MonadMask m, MonadIO m, HasCallStack) => Resource a -> (a -> m b) -> m b

Create a new resource and run some computation, resource is guarantee to be closed.

Be care don't leak the resource through computation return value, because after the computation finishes, the resource is closed already.

withResource' :: (MonadMask m, MonadIO m, HasCallStack) => Resource a -> (a -> m () -> m b) -> m b

Create a new resource and run some computation, resource is guarantee to be closed.

The difference from with is that the computation will receive an extra close action, which can be used to close the resource early before the whole computation finished, the close action can be called multiple times, only the first call will clean up the resource.

Resource pool

data Pool a

A high performance resource pool based on STM.

We choose to not divide pool into strips due to the difficults in resource balancing. If there is a high contention on resource (see statPool), just increase the maximum number of resources can be opened.

data PoolState

Constructors

PoolClosed

PoolScanning

PoolEmpty

Instances

Eq PoolState

Defined in Z.IO.Resource

Methods

(==) :: PoolState -> PoolState -> Bool

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

Show PoolState

Defined in Z.IO.Resource

Methods

showsPrec :: Int -> PoolState -> ShowS

show :: PoolState -> String

showList :: [PoolState] -> ShowS

initPool

Arguments

:: Resource a

-> Int

maximum number of resources can be opened

-> Int

amount of time after which an unused resource can be released (in seconds).

-> Resource (Pool a)

Initialize a resource pool with given Resource

Like other initXXX functions, this function won't open a resource pool until you use withResource. And this resource pool follow the same resource management pattern like other resources.

initInPool :: Pool a -> Resource a

Obtain the pooled resource inside a given resource pool.

You shouldn't use withResource with this resource after you closed the pool, a ResourceVanished will be thrown.

withResourceInPool :: (MonadMask m, MonadIO m, HasCallStack) => Pool a -> (a -> m b) -> m b

Open resource inside a given resource pool and do some computation.

poolStat :: Pool a -> IO PoolState

Get a resource pool's PoolState

This function is useful when debug, under load lots of PoolEmpty may indicate contention on resources, i.e. the limit on maximum number of resources can be opened should be adjusted to a higher number. On the otherhand, lots of PoolScanning may indicate there're too much free resources.

poolInUse :: Pool a -> IO Int

Get how many resource is being used within a resource pool.

This function is useful when debug, under load in use number alway reaches limit may indicate contention on resources, i.e. the limit on maximum number of resources can be opened should be adjusted to a higher number.