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


-- | An in-memory key/value store with expiration support
--   
--   An in-memory key/value store with expiration support, similar to
--   patrickmn/go-cache for Go.
--   
--   The cache is a shared mutable HashMap implemented using STM and with
--   support for expiration times.
@package cache
@version 0.1.0.0


-- | An in-memory key/value store with expiration support, similar to
--   patrickmn/go-cache for GO.
--   
--   The cache is a shard mutable HashMap implemented using STM. It
--   supports item expiration.
module Data.Cache

-- | The cache with keys of type <tt>k</tt> and values of type <tt>v</tt>.
--   
--   Create caches with the <a>newCache</a> and <a>copyCache</a> functions.
data Cache k v

-- | Create a new cache with a default expiration value for newly added
--   cache items.
--   
--   Items that are added to the cache without an explicit expiration value
--   (using <a>insert</a>) will be inserted with the default expiration
--   value.
--   
--   If the specified default expiration value is <a>Nothing</a>, items
--   inserted by <a>insert</a> will never expire.
newCache :: Maybe TimeSpec -> IO (Cache k v)

-- | The default expiration value of newly added cache items.
--   
--   See <a>newCache</a> for more information on the default expiration
--   value.
defaultExpiration :: Cache k v -> Maybe TimeSpec

-- | Change the default expiration value of newly added cache items.
--   
--   See <a>newCache</a> for more information on the default expiration
--   value.
setDefaultExpiration :: Cache k v -> Maybe TimeSpec -> Cache k v

-- | Create a deep copy of the cache.
copyCache :: Cache k v -> IO (Cache k v)

-- | Insert an item in the cache, using the default expiration value of the
--   cache.
insert :: (Eq k, Hashable k) => Cache k v -> k -> v -> IO ()

-- | Insert an item in the cache, with an explicit expiration value.
--   
--   If the expiration value is <a>Nothing</a>, the item will never expire.
--   The default expiration value of the cache is ignored.
insert' :: (Eq k, Hashable k) => Cache k v -> Maybe TimeSpec -> k -> v -> IO ()

-- | Lookup an item with the given key, and delete it if it is expired.
--   
--   The function will only return a value if it is present in the cache
--   and if the item is not expired.
--   
--   The function will eagerly delete the item from the cache if it is
--   expired.
lookup :: (Eq k, Hashable k) => Cache k v -> k -> IO (Maybe v)

-- | Lookup an item with the given key, but don't delete it if it is
--   expired.
--   
--   The function will only return a value if it is present in the cache
--   and if the item is not expired.
--   
--   The function will not delete the item from the cache.
lookup' :: (Eq k, Hashable k) => Cache k v -> k -> IO (Maybe v)

-- | Return all keys present in the cache.
keys :: Cache k v -> IO [k]

-- | Delete an item from the cache. Won't do anything if the item is not
--   present.
delete :: (Eq k, Hashable k) => Cache k v -> k -> IO ()

-- | Delete all items that are expired.
--   
--   This is one big atomic operation.
purgeExpired :: (Eq k, Hashable k) => Cache k v -> IO ()

-- | Return the size of the cache, including expired items.
size :: Cache k v -> IO Int