HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Modulecache-0.1.3.0Haskell2010

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.

  • 1 type
  • 24 values
  • Packagecache-0.1.3.0
  • Exports25
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceCache.hs

How to use this library

0 declarations

All operations are automically 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.

Note that items are not purged automatically in the background when they expire. You have to manually call lookup to purge a single item, or call purgeExpired to purge all expired items.

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

3 declarations
datadata Cache k v
#

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

Create caches with the newCache and copyCache functions.

valuenewCache :: 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

4 declarations
valuedefaultExpiration :: Cache k v -> Maybe TimeSpec
#

The default expiration value of newly added cache items.

See newCache for more information on the default expiration value.

Managing items

0 declarations

Insertion

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

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

valueinsert'
  1. :: (Eq k, Hashable k)
  2. => Cache k v
  3. -> Maybe TimeSpec
  4. -> k
  5. -> v
  6. -> 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.

The expiration value is relative to the current Monotonic time, i.e. it will be automatically added to the result of getTime Monotonic.

valueinsertSTM
  1. :: (Eq k, Hashable k)
  2. => k
  3. -> v
  4. -> Cache k v
  5. -> Maybe TimeSpec
  6. -> STM ()
#

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

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

The expiration value is the absolute Monotonic time the item expires. You should manually construct the absolute Monotonic time, as opposed to the behaviour of insert'.

E.g.

action :: Cache -> IO ()
action c = do
    t <- getTime Monotonic
    let t' = t + (defaultExpiration c)
    atomically $ insertSTM 0 0 c (Just t')

Querying

valuelookup :: (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.

valuelookup' :: (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.

valuekeys :: Cache k v -> IO [k]
#

Return all keys present in the cache.

Deletion

valuedelete :: (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.

valuefilterWithKey
  1. :: (Eq k, Hashable k)
  2. => k -> v -> Bool
  3. -> Cache k v
  4. -> IO ()
#

Keeps elements that satify a predicate (used for cache invalidation). Note that the predicate might be called for expired items.

Combined actions

valuefetchWithCache
  1. :: (Eq k, Hashable k, MonadIO m)
  2. => Cache k v
  3. -> k
  4. -> k -> m v
  5. -> m v
#

Get a value from cache. If not available from cache, use the provided action and update the cache. Note that the cache check and conditional execution of the action is not one atomic action.

Cache information

3 declarations
valuesize :: Cache k v -> IO Int
#

Return the size of the cache, including expired items.

valuetoList :: Cache k v -> IO [(k, v, Maybe TimeSpec)]
#

Returns the cache content as a list. The third element of the tuple is the expiration date. Nothing means that it doesn't expire.