-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Cache infrequently updated data for simpler distributed systems.
--   
--   Cache infrequently updated data for simpler distributed systems. See
--   <a>https://github.com/jkaye2012/polling-cache</a> for more details.
@package polling-cache
@version 0.0.1.0


-- | Caching implementation internals.
--   
--   This module is not part of the Data.Cache public API and should not be
--   directly relied upon by users. Anything meant for external use defined
--   here will be re-exported by a public module.
module Data.Cache.Internal

-- | The top-level <a>Monad</a> in which caching operations are performed.
--   
--   This exists primarily for testing purposes. Production uses should
--   drop in <a>IO</a> and forget that this exists.
class (MonadCatch m, MonadIO m) => MonadCache m

-- | The current system time.
currentTime :: MonadCache m => m UTCTime

-- | Generate a random number between two bounds (inclusive).
randomize :: MonadCache m => (Int, Int) -> m Int

-- | Delay execution of the current thread for a number of microseconds.
delay :: MonadCache m => Int -> m ()

-- | Spawn a new thread of execution to run an action.
newThread :: MonadCache m => m () -> m ThreadId

-- | Run an action forever.
repeatedly :: MonadCache m => m () -> m ()

-- | Stop a thread of execution. The thread can be assumed to have been
--   started using <a>newThread</a>.
killCache :: MonadCache m => ThreadId -> m ()

-- | The supported delay modes for a <a>PollingCache</a> instance.
--   
--   The delay associated with a cache instance define the amount of time
--   that will pass between cache refreshes.
data DelayMode a

-- | Delay for static number of microseconds between each refresh.
DelayForMicroseconds :: Int -> DelayMode a

-- | 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.
DelayDynamically :: (Either SomeException a -> Int) -> DelayMode a

-- | Delay for a dynamic number of microseconds between each refresh within
--   a set of bounds.
--   
--   This is similarly useful to <a>DelayDynamically</a>, 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.
DelayDynamicallyWithBounds :: (Int, Int) -> (Either SomeException a -> Int) -> DelayMode a

-- | The supported failure handling modes for a <a>PollingCache</a>
--   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.
data FailureMode

-- | Failures should be ignored entirely; the most relaxed failure handling
--   strategy.
--   
--   This means that <a>LoadFailed</a> will never be populated as a cache
--   result.
Ignore :: FailureMode

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

-- | 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.
EvictAfterTime :: NominalDiffTime -> FailureMode

-- | Options that dictate the behavior of a <a>PollingCache</a> instance.
data CacheOptions a
CacheOptions :: DelayMode a -> FailureMode -> Maybe Int -> CacheOptions a

-- | The <a>DelayMode</a> to use.
[delayMode] :: CacheOptions a -> DelayMode a

-- | The <a>FailureMode</a> to use.
[failureMode] :: CacheOptions a -> FailureMode

-- | An optional fuzzing factor.
--   
--   If provided, this factor defines the maximum number of microseconds
--   that can be randomly added to each delay period. This means that when
--   fuzzing is enabled, the delay between any two refreshes will always be
--   greater than the delay period generated by the cache's
--   <a>DelayMode</a>. <a>Nothing</a> disables fuzzing completely.
[delayFuzzing] :: CacheOptions a -> Maybe Int
instance GHC.Show.Show Data.Cache.Internal.FailureMode
instance GHC.Classes.Eq Data.Cache.Internal.FailureMode
instance Data.Cache.Internal.MonadCache GHC.Types.IO


-- | A cache implementation that periodically (and asynchronously) polls an
--   external action for updated values.
module Data.Cache.Polling

-- | The top-level <a>Monad</a> in which caching operations are performed.
--   
--   This exists primarily for testing purposes. Production uses should
--   drop in <a>IO</a> and forget that this exists.
class (MonadCatch m, MonadIO m) => MonadCache m

-- | The current system time.
currentTime :: MonadCache m => m UTCTime

-- | Generate a random number between two bounds (inclusive).
randomize :: MonadCache m => (Int, Int) -> m Int

-- | Delay execution of the current thread for a number of microseconds.
delay :: MonadCache m => Int -> m ()

-- | Spawn a new thread of execution to run an action.
newThread :: MonadCache m => m () -> m ThreadId

-- | Run an action forever.
repeatedly :: MonadCache m => m () -> m ()

-- | Stop a thread of execution. The thread can be assumed to have been
--   started using <a>newThread</a>.
killCache :: MonadCache m => ThreadId -> m ()

-- | An opaque type containing the internals necessary for background
--   polling and caching.
--   
--   Library functions will allow the user to create and interact with a
--   <a>PollingCache</a>, but the raw data is not exposed to users so that
--   the library can maintain invariants.
data PollingCache a

-- | The supported "empty" states for a <a>PollingCache</a>.
--   
--   See <a>CacheResult</a> for a more in-depth explanation of why this is
--   necessary.
data CacheMiss

-- | A value has never been loaded into the cache.
NotYetLoaded :: CacheMiss

-- | The external action used to populate the cache threw an exception at
--   some point in time.
LoadFailed :: UTCTime -> CacheMiss

-- | The cache has been shut down and can no longer be used.
Stopped :: CacheMiss

-- | A successfully cached value with the time at which it was generated.
type CacheHit a = (a, UTCTime)

-- | The result of reading a value from a <a>PollingCache</a>, 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 <a>FailureMode</a> selected by the user when
--   creating the <a>PollingCache</a> instance.
type CacheResult a = Either CacheMiss (CacheHit a)

-- | The supported failure handling modes for a <a>PollingCache</a>
--   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.
data FailureMode

-- | Failures should be ignored entirely; the most relaxed failure handling
--   strategy.
--   
--   This means that <a>LoadFailed</a> will never be populated as a cache
--   result.
Ignore :: FailureMode

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

-- | 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.
EvictAfterTime :: NominalDiffTime -> FailureMode

-- | The supported delay modes for a <a>PollingCache</a> instance.
--   
--   The delay associated with a cache instance define the amount of time
--   that will pass between cache refreshes.
data DelayMode a

-- | Delay for static number of microseconds between each refresh.
DelayForMicroseconds :: Int -> DelayMode a

-- | 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.
DelayDynamically :: (Either SomeException a -> Int) -> DelayMode a

-- | Delay for a dynamic number of microseconds between each refresh within
--   a set of bounds.
--   
--   This is similarly useful to <a>DelayDynamically</a>, 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.
DelayDynamicallyWithBounds :: (Int, Int) -> (Either SomeException a -> Int) -> DelayMode a

-- | The minimum amount of time (in microseconds) that should pass before a
--   cache reload is attempted.
type ThreadDelay = Int

-- | Options that dictate the behavior of a <a>PollingCache</a> instance.
data CacheOptions a

-- | Create a <a>CacheOptions</a> with basic functionality enabled.
--   
--   Record update syntax can be use to further customize options created
--   using this function:
--   
--   <pre>
--   basicOpts = basicOptions (DelayForMicroseconds 60000000) EvictImmediately
--   customOpts = basicOpts { delayFuzzing = Just 100 }
--   </pre>
basicOptions :: DelayMode a -> FailureMode -> CacheOptions a

-- | Creates a new <a>PollingCache</a>.
--   
--   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
--   <a>CacheOptions</a>.
newPollingCache :: forall a m. MonadCache m => CacheOptions a -> m a -> m (PollingCache a)

-- | Retrieve the current values from a <a>PollingCache</a>.
cachedValues :: MonadCache m => PollingCache a -> m (CacheResult a)

-- | Stops the background processing thread associated with a
--   <a>PollingCache</a>.
--   
--   Calling this function will place the <a>Stopped</a> value into the
--   cache after stopping the processing thread, ensuring that a
--   <a>PollingCache</a> that has been stopped can no longer be used to
--   query stale values.
stopPolling :: MonadCache m => PollingCache a -> m ()
instance GHC.Show.Show Data.Cache.Polling.CacheMiss
instance GHC.Classes.Eq Data.Cache.Polling.CacheMiss


-- | Cache implementations.
module Data.Cache