Z-IO-0.1.9.0: Simple and high performance IO toolkit for Haskell
Copyright(c) Dong Han 2017
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Z.IO.Resource

Description

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.

Synopsis

Resource management

newtype Resource a Source #

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:

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

Constructors

Resource 

Fields

Instances

Instances details
Monad Resource Source # 
Instance details

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

Defined in Z.IO.Resource

Methods

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

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

Applicative Resource Source # 
Instance details

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

Defined in Z.IO.Resource

Methods

liftIO :: IO a -> Resource a #

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

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

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

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

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

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

Instances

Instances details
Eq PoolState Source # 
Instance details

Defined in Z.IO.Resource

Show PoolState Source # 
Instance details

Defined in Z.IO.Resource

initPool Source #

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

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

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

poolStat :: Pool a -> IO PoolState Source #

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

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.