Data.Cache

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.

How to use this library

All operations are atomically executed in the IO monad. The underlying data structure is Data.HashMap.Strict.

First create a cache using newCache and possibly a default expiration value. Items can now be inserted using insert and insert'.

lookup and lookup' are used to query items. These functions only return a value when the item is in the cache and it is not expired. The lookup function will automatically delete the item if it is expired, while lookup' won't delete the item.

>>> c <- newCache Nothing :: IO (Cache String String)
>>> insert c "key" "value"
>>> lookup c "key"
Just "value"
>>> delete c "key"
>>> lookup c "key"
Nothing

Creating a cache

data Cache k v

The cache with keys of type k and values of type v.

Create caches with the newCache and copyCache functions.

newCache :: Maybe TimeSpec -> IO (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 insert) will be inserted with the default expiration value.

If the specified default expiration value is Nothing, items inserted by insert will never expire.

Cache properties

defaultExpiration :: Cache k v -> Maybe TimeSpec

The default expiration value of newly added cache items.

See newCache for more information on the default expiration value.

setDefaultExpiration :: Cache k v -> Maybe TimeSpec -> Cache k v

Change the default expiration value of newly added cache items.

See newCache for more information on the default expiration value.

copyCache :: Cache k v -> IO (Cache k v)

Create a deep copy of the cache.

Managing items

Insertion

insert :: (Eq k, Hashable k) => Cache k v -> k -> v -> IO ()

Insert an item in the cache, using the default expiration value of the cache.

insert' :: (Eq k, Hashable k) => Cache k v -> Maybe TimeSpec -> k -> v -> IO ()

Insert an item in the cache, with an explicit expiration value.

If the expiration value is Nothing, the item will never expire. The default expiration value of the cache is ignored.

Querying

lookup :: (Eq k, Hashable k) => Cache k v -> k -> IO (Maybe v)

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.

keys :: Cache k v -> IO [k]

Return all keys present in the cache.

Deletion

delete :: (Eq k, Hashable k) => Cache k v -> k -> IO ()

Delete an item from the cache. Won't do anything if the item is not present.

purgeExpired :: (Eq k, Hashable k) => Cache k v -> IO ()

Delete all items that are expired.

This is one big atomic operation.

Cache information

size :: Cache k v -> IO Int

Return the size of the cache, including expired items.