polling-cache

* polling-cache

polling-cache is a Haskell library meant to facilitate low-frequency polling for reliability and performance in distributed systems.

More information about the concepts underlying the library can be found on [[https://jordankaye.dev/posts/polling-for-relability][my development blog]] (coming soon).

Detailed technical documentation for the library can be found on [[https://hackage.haskell.org/package/polling-cache][Hackage]] (coming soon).

#+html: <p><img src="https://github.com/jkaye2012/polling-cache/actions/workflows/build-and-test.yml/badge.svg" /></p>

** Quick start guide

*IMPORTANT!* Before attempting to use this library, it's pivotal to understand your use case and whether simple polling is a reasonable solution.
Polling is a strategy generally suitable only for data that must be updated with a relatively low frequency, and for which
periodic failures to update are not catastrophic to the application. Attempting to use polling for data that is expensive to generate or
that must be updated frequently is a very easy way to destroy the performance of your system via self-imposed DDoS.

*** Basic concepts

polling-cache works by allowing users to create ~PollingCache~ instances that automatically update themselves in the background and
expose their currently cached state in a thread-safe manner. The basic steps to work with the library are:

1. Create a ~PollingCache~ by providing an action that generates values and a time span that must pass between invocations of that action
2. Read values from the cache as required by your application
3. Optionally, stop the cache's background operations once the data is no longer required (this invalidates the cache permanently)

*** Example

While polling-cache supports arbitrary execution contexts via ~MonadCache~, nearly all end-users will want to operate in ~IO~.

Here's a simple example that you should be able to compile and run on your own that demonstrates the basic usage of the functions
exposed by polling-cache:

#+begin_src haskell

import Control.Concurrent
import Data.Cache.Polling

-- In "real" code, this generator would likely hit a database or service endpoint of some kind.
-- Any exception thrown from the generator is handled by the CacheResult (see API documentation for details).
dataGenerator :: IO String
dataGenerator = return "Very nice data"

main :: IO ()
main = do
-- 3600000000 microseconds = 1 hour delay between invocations of the generator, ignore failures
let opts = basicOptions (DelayForMicroseconds 3600000000) Ignore
cache <- newPollingCache opts dataGenerator
threadDelay 100 -- Give the runtime a bit of time to execute the action in the background
latestResult <- cachedValue cache
print latestResult
stopPolling cache -- Shut down and invalidate the cache

#+end_src