Safe Haskell	Safe
Language	Haskell2010

Data.ConcurrentResourceMap

Synopsis

data ConcurrentResourceMap k r
newResourceMap :: Ord k => IO (ConcurrentResourceMap k r)
withSharedResource :: Ord k => ConcurrentResourceMap k r -> k -> IO r -> (r -> IO ()) -> (r -> IO a) -> IO a

Documentation

data ConcurrentResourceMap k r Source #

A map of shared resources r keyed by k.

newResourceMap :: Ord k => IO (ConcurrentResourceMap k r) Source #

Create an empty resource map.

withSharedResource Source #

Arguments

:: Ord k
=> ConcurrentResourceMap k r	Resource map. Create with `newResourceMap`.
-> k	Key for the resource. This allows you to have many of the same type of resource but separated: for example, one group of threads could be holding onto a logging handle to syslog while another could be holding a handle to a file.
-> IO r	Initialise resource. Only ran if the resource is not yet initialised. Does not run in masked context so if you need to stop async exceptions, you should use `mask` yourself. If the action fails (throws an exception), the user fails and we enter cleanup.
-> (r -> IO ())	Destroy the resource if it was initialised. Ran by last alive user when it's exiting. Unlike initialisation, this _is_ ran in masked context. If this action fails (by throwing an exception itself), the resource will be assumed to be uninitialised and the exception will be re-thrown. Therefore, if your cleanup can fail in a way that you have to know about/recover from, you should catch exceptions coming out out `withSharedResource`. As you get reference to the resource in the `act`, you're able to store it/monitor it yourself and decide to take any appropriate actions in the future such as blocking other threads from running initialisation again until you've cleaned up the resource yourself.
-> (r -> IO a)	Run an actionwith the initialised resource. Note that the availability of this resource only ensures that the user-given initialisers/destructors have been ran appropriate number of times: it of course makes no guarantees as to what the resource represents. For example, if it's a `ProcessHandle` or a database connection, there's no guarantee that the process is alive or that the database connection is still available. For resources that can dynamically fail, you should implement some sort of monitoring yourself.
-> IO a

Use a resource that can be accessed concurrently via multiple threads but is only initialised and destroyed on as-needed basis. If number of users falls to 0, the resource is destroyed. If a new user joins and resource is not available, it's created.

Calls to withSharedResource can even be nested if you need access to resources with different keys in the same map. Calling withSharedResource in a nested matter on same resource key should have no real adverse effects either.