-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Concurrent resource map
--   
--   Please see the README on GitHub at
--   <a>https://github.com/Fuuzetsu/concurrent-resource-map#readme</a>
@package concurrent-resource-map
@version 0.2.0.0

module Data.ConcurrentResourceMap

-- | A map of shared resources <tt>r</tt> keyed by <tt>k</tt>.
data ConcurrentResourceMap m v

-- | Resource maps should implement this small set of operations that we
--   expect maps to have.
--   
--   This allows you to use whatever fast underlying map type you'd like,
--   depending on your resources.
class ResourceMap m where {
    type family Key m :: *;
}
empty :: ResourceMap m => m v
delete :: ResourceMap m => Key m -> m v -> m v
insert :: ResourceMap m => Key m -> v -> m v -> m v
lookup :: ResourceMap m => Key m -> m v -> Maybe v

-- | Create an empty resource map.
newResourceMap :: ResourceMap m => IO (ConcurrentResourceMap m r)

-- | This is like <a>withSharedResource</a> but will only execute the user
--   action if the resource already exists. This is useful if you create
--   your resources in one place but would like to use them conditionally
--   in another place if they are still alive.
--   
--   Action is given Nothing if the resource does not exist or is not
--   initialised.
withInitialisedResource :: ResourceMap m => ConcurrentResourceMap m r -> Key m -> (r -> IO ()) -> (Maybe r -> IO a) -> 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 <a>withSharedResource</a> can even be nested if you need
--   access to resources with different keys in the same map. Calling
--   <a>withSharedResource</a> in a nested matter on same resource key
--   should have no real adverse effects either.
withSharedResource :: ResourceMap m => ConcurrentResourceMap m r -> Key m -> IO r -> (r -> IO ()) -> (r -> IO a) -> IO a