This module defines a key/value store (Polysemy) effect. Rather than return the usual Maybe v from a lookup, the cache returns a Maybe (WithCacheTime v), where WithCacheTime a wraps a value of type a along with a time-stamp (of type UTCTime). This module provides a thread-safe in-memory implementation as well as a disk-based persistent implementation and a combination of the two, where the disk-based layer sits behind the in-memory layer. In our use case, the stored values will be arrays of bytes, the result of serializing whatever data we wish to cache.

WithCacheTime is intended to simplify tracking dependencies among cached computations. For example, imagine you have two long running computations which you wish to cache so you need only run those computations once:

computeA :: m a
computeA = ...

computeB :: m b
computeB = ...

cachedA :: WithCacheTime m a 
cachedA :: retrieveOrMake serialize "a.bin" (pure ()) (const computeA)

cachedB :: WithCacheTime m b
cachedB = retrieveOrMake serialize "b.bin" (pure ()) (const computeB)

and you have a computation which depends on a and b and should also be cached, but we want to make sure it gets recomputed if either a or b do. We use the applicative instance of WithCacheTime to combine cached results into and inject them into later computations while taking into account the newest time-stamp among the dependencies:

computeC :: a -> b -> m c
computeC a b = ...

cDeps :: WithCachedTime m (a, b)
cDeps = (,) $ cachedA <*> cachedB

cachedC :: WithCacheTime m c
cachedC = retrieveOrMake serialize "c.bin" cDeps $ \(a, b) -> computeC a b

As with cachedA and cachedB, cachedC will run the computation if the key, "c.bin" in this case, is absent from the cache. In addition, cachedC will be recomputed even if it is in the cache, if the time-stamp of the cached value is older than either the time stamp of cachedA or cachedB.

WithCacheTime m a holds the time-stamp and a monadic computation which will produce an a. This allows deferral of the deserialization of cached data until we know that we need to use it. In the example above, suppose a is retrieved from cache, and b is computed fresh. cachedA holds a timestamp (the modification time of the file in cache or the time a was cached in memory) and a monadic computation which will deserialize the cached byte array retrieved for a. cachedB holds a time-stamp (the time the computation of b completes) and the trivial monadic action return b. Since b was just computed, the cached c is outdated and will be recomputed. At that point a is deserialized, b is unwrapped and thse are given to the function to compute c, which is then stored in cache as well as returned in the WithCacheTime m c, holding a new time-stamp.

If multiple threads attempt to lookup or retrieveOrMake at the same key at close to the same time, the first request will proceed, loading from cache if possible, and the other threads will block until the in-memory cache is populated or the first thread fails to fill in data.

This is intended to save CPU in the relatively common case that, e.g., several threads are launched to analyze the same data. The functions which load that data from on-disk-cache or produce it from other analyses need only be run once. Using the cache to facilitate this sharing still requires each thread to deserialize the data. If that cost is significant, you may want to compute the data before launching the threads.

NB: Should the action given to create the data, the (b -> m a) argument of retrieveOrMake somehow fail, this may lead to a situation where it runs on the first thread, fails, then runs on all the other threads simultaneously, presumably failing all those times as well.

Examples are available, and might be useful for seeing how all this works.