Data.Cache.Polling

A cache implementation that periodically (and asynchronously) polls an external action for updated values.

Entry-point types and typeclasses

class (MonadCatch m, MonadIO m) => MonadCache m where

The top-level Monad in which caching operations are performed.

This exists primarily for testing purposes. Production uses should drop in IO and forget that this exists.

Methods

currentTime :: m UTCTime

The current system time.

randomize :: (Int, Int) -> m Int

Generate a random number between two bounds (inclusive).

delay :: Int -> m ()

Delay execution of the current thread for a number of microseconds.

newThread :: m () -> m ThreadId

Spawn a new thread of execution to run an action.

repeatedly :: m () -> m ()

Run an action forever.

killCache :: ThreadId -> m ()

Stop a thread of execution. The thread can be assumed to have been started using newThread.

Instances

MonadCache IO

Defined in Data.Cache.Internal

Methods

currentTime :: IO UTCTime

randomize :: (Int, Int) -> IO Int

delay :: Int -> IO ()

newThread :: IO () -> IO ThreadId

repeatedly :: IO () -> IO ()

killCache :: ThreadId -> IO ()

data PollingCache a

An opaque type containing the internals necessary for background polling and caching.

Library functions will allow the user to create and interact with a PollingCache, but the raw data is not exposed to users so that the library can maintain invariants.

Types for working with cached results

data CacheMiss

The supported "empty" states for a PollingCache.

See CacheResult for a more in-depth explanation of why this is necessary.

Constructors

NotYetLoaded

A value has never been loaded into the cache.

LoadFailed UTCTime

The external action used to populate the cache threw an exception at some point in time.

Stopped

The cache has been shut down and can no longer be used.

Instances

Eq CacheMiss

Defined in Data.Cache.Polling

Methods

(==) :: CacheMiss -> CacheMiss -> Bool

(/=) :: CacheMiss -> CacheMiss -> Bool

Show CacheMiss

Defined in Data.Cache.Polling

Methods

showsPrec :: Int -> CacheMiss -> ShowS

show :: CacheMiss -> String

showList :: [CacheMiss] -> ShowS

type CacheHit a = (a, UTCTime)

A successfully cached value with the time at which it was generated.

type CacheResult a = Either CacheMiss (CacheHit a)

The result of reading a value from a PollingCache, including the possibility of failure.

Due to the asynchronous (and likely effectful) nature of executing external actions to populate the cache, it's possible for the cache to be "empty" at any point in time. The possible empty states are controlled by the FailureMode selected by the user when creating the PollingCache instance.

Types for cache creation

data FailureMode

The supported failure handling modes for a PollingCache instance.

In the context of the cache action, "failure" means an Exception thrown from the user-supplied action that generates values to populate the cache.

Because these operations are performed in a background thread, the user must decide how failures are to be handled upon cache creation.

Constructors

Ignore

Failures should be ignored entirely; the most relaxed failure handling strategy.

This means that LoadFailed will never be populated as a cache result.

EvictImmediately

If a failure occurs, any previously cached value is immediately evicted from the cache; the strictest failure handling strategy.

EvictAfterTime NominalDiffTime

Failures will be ignored unless they persist beyond the supplied time span.

This is a middle-ground failure handling strategy that probably makes sense to use in most scenarios. The nature of asynchronous polling implies that somewhat stale values are not an issue to the consumer; therefore, allowing some level of transient failure can often improve reliability without sacrificing correctness.

Instances

Eq FailureMode

Defined in Data.Cache.Internal

Methods

(==) :: FailureMode -> FailureMode -> Bool

(/=) :: FailureMode -> FailureMode -> Bool

Show FailureMode

Defined in Data.Cache.Internal

Methods

showsPrec :: Int -> FailureMode -> ShowS

show :: FailureMode -> String

showList :: [FailureMode] -> ShowS

data DelayMode a

The supported delay modes for a PollingCache instance.

The delay associated with a cache instance define the amount of time that will pass between cache refreshes.

Constructors

DelayForMicroseconds Int

Delay for static number of microseconds between each refresh.

DelayDynamically (Either SomeException a -> Int)

Delay for a dynamic number of microseconds between each refresh.

This is useful if different delays should be used for successes or failures, or if the result being retrieved contains information that could affect the delay period.

DelayDynamicallyWithBounds (Int, Int) (Either SomeException a -> Int)

Delay for a dynamic number of microseconds between each refresh within a set of bounds.

This is similarly useful to DelayDynamically, but when a known lower and upper bound should be applied to the delay period. Regardless of the dynamic delay generated by the user-supplied function, the delay period will never be below the lower bound or above the upper bound.

type ThreadDelay = Int

The minimum amount of time (in microseconds) that should pass before a cache reload is attempted.

data CacheOptions a

Options that dictate the behavior of a PollingCache instance.

Functions for creating and interacting with caches

basicOptions :: DelayMode a -> FailureMode -> CacheOptions a

Create a CacheOptions with basic functionality enabled.

Record update syntax can be use to further customize options created using this function:

basicOpts = basicOptions (DelayForMicroseconds 60000000) EvictImmediately
customOpts = basicOpts { delayFuzzing = Just 100 }

newPollingCache :: forall a m. MonadCache m => CacheOptions a -> m a -> m (PollingCache a)

Creates a new PollingCache.

The supplied action is used to generate values that are stored in the cache. The action is executed in the background with its delay, failure, and fuzzing behavior controlled by the provided CacheOptions.

cachedValue :: MonadCache m => PollingCache a -> m (CacheResult a)

Retrieve the current values from a PollingCache.

stopPolling :: MonadCache m => PollingCache a -> m ()

Stops the background processing thread associated with a PollingCache.

Calling this function will place the Stopped value into the cache after stopping the processing thread, ensuring that a PollingCache that has been stopped can no longer be used to query stale values.