-- 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.1.1


-- | This modules exposes some of the internals of <a>Cache</a> as well as
--   some auxiliary functions for expert users.
module Data.Cache.Internal

-- | The cache with keys of type <tt>k</tt> and values of type <tt>v</tt>.
--   
--   Create caches with the <tt>newCache</tt> and <tt>copyCache</tt>
--   functions.
data Cache k v
Cache :: TVar (HashMap k (CacheItem v)) -> Maybe TimeSpec -> Cache k v
[container] :: Cache k v -> TVar (HashMap k (CacheItem v))

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

-- | A container data type holding a cache item.
data CacheItem v
CacheItem :: v -> Maybe TimeSpec -> CacheItem v
[item] :: CacheItem v -> v
[itemExpiration] :: CacheItem v -> Maybe TimeSpec

-- | Get the current time in the <a>STM</a> monad using
--   <a>unsafeIOToSTM</a>.
nowSTM :: STM TimeSpec


-- | 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. 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 <tt>newCache</tt> and <tt>copyCache</tt>
--   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)

-- | STM variant of <a>newCache</a>
newCacheSTM :: Maybe TimeSpec -> STM (Cache k v)

-- | The default expiration value of newly added cache items.
--   
--   See <tt>newCache</tt> 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)
copyCacheSTM :: Cache k v -> STM (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.
--   
--   The expiration value is relative to the current <a>Monotonic</a> time,
--   i.e. it will be automatically added to the result of <tt>getTime
--   Monotonic</tt>.
insert' :: (Eq k, Hashable k) => Cache k v -> Maybe TimeSpec -> k -> v -> IO ()

-- | Insert an item in the cache, with an explicit expiration value, in the
--   <a>STM</a> monad.
--   
--   If the expiration value is <a>Nothing</a>, the item will never expire.
--   The default expiration value of the cache is ignored.
--   
--   The expiration value is the absolute <a>Monotonic</a> time the item
--   expires. You should manually construct the absolute <a>Monotonic</a>
--   time, as opposed to the behaviour of <a>insert'</a>.
--   
--   E.g.
--   
--   <pre>
--   action :: Cache -&gt; IO ()
--   action c = do
--       t &lt;- getTime Monotonic
--       let t' = t + (defaultExpiration c)
--       atomically $ insertSTM 0 0 c (Just t')
--   </pre>
insertSTM :: (Eq k, Hashable k) => k -> v -> Cache k v -> Maybe TimeSpec -> STM ()

-- | 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)

-- | Lookup an item with a given key in the <a>STM</a> monad, given the
--   current <a>Monotonic</a> time.
--   
--   STM variant of <a>lookup</a> and <a>lookup'</a>
lookupSTM :: (Eq k, Hashable k) => Bool -> k -> Cache k v -> TimeSpec -> STM (Maybe v)

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

-- | STM variant of <a>keys</a>.
keysSTM :: Cache k v -> STM [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 ()

-- | STM variant of <a>delete</a>.
deleteSTM :: (Eq k, Hashable k) => k -> Cache k v -> STM ()

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

-- | STM variant of <a>purgeExpired</a>.
--   
--   The <a>TimeSpec</a> argument should be the current <a>Monotonic</a>
--   time, i.e. <tt>getTime Monotonic</tt>.
purgeExpiredSTM :: (Eq k, Hashable k) => Cache k v -> TimeSpec -> STM ()

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

-- | STM variant of <a>size</a>
sizeSTM :: Cache k v -> STM Int