| Copyright | (c) 2016 Henri Verroken |
|---|---|
| License | BSD3 |
| Maintainer | Henri Verroken <henriverroken@gmail.com> |
| Stability | experimental |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Data.Cache
Contents
Description
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.
- data Cache k v
- newCache :: Maybe TimeSpec -> IO (Cache k v)
- defaultExpiration :: Cache k v -> Maybe TimeSpec
- setDefaultExpiration :: Cache k v -> Maybe TimeSpec -> Cache k v
- copyCache :: Cache k v -> IO (Cache k v)
- insert :: (Eq k, Hashable k) => Cache k v -> k -> v -> IO ()
- insert' :: (Eq k, Hashable k) => Cache k v -> Maybe TimeSpec -> k -> v -> IO ()
- lookup :: (Eq k, Hashable k) => Cache k v -> k -> IO (Maybe v)
- lookup' :: (Eq k, Hashable k) => Cache k v -> k -> IO (Maybe v)
- keys :: Cache k v -> IO [k]
- delete :: (Eq k, Hashable k) => Cache k v -> k -> IO ()
- purgeExpired :: (Eq k, Hashable k) => Cache k v -> IO ()
- size :: Cache k v -> IO Int
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
newCache :: Maybe TimeSpec -> IO (Cache k v) Source
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 Source
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 Source
Change the default expiration value of newly added cache items.
See newCache for more information on the default expiration value.
Managing items
Insertion
insert :: (Eq k, Hashable k) => Cache k v -> k -> v -> IO () Source
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 () Source
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) Source
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) Source
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.
Deletion
delete :: (Eq k, Hashable k) => Cache k v -> k -> IO () Source
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 () Source
Delete all items that are expired.
This is one big atomic operation.