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


-- | Package implementing core logic for refreshing of expiring data.
--   
--   This package can be used for refreshing of expiring data according to
--   a user-provided action. Using callbacks, the user can decide how she
--   or he would like to be informed about data refreshing.
@package async-refresh
@version 0.3.0.0


-- | The async-refresh package provides the logic for periodic refreshing
--   of arbitrary data. This module implements the core of the package and
--   exposes its API.
module Control.Concurrent.Async.Refresh

-- | Data type defining an async refresh configuration.
data AsyncRefreshConf m a

-- | Data type denoting a running async refresher.
data AsyncRefresh

-- | Type synonym for async refresh callbacks.
type AsyncRefreshCallback m a = Either SomeException (RefreshResult a) -> m ()

-- | Data type returned by async refresh actions.
data RefreshResult a
RefreshResult :: a -> Maybe Int -> RefreshResult a

-- | Actual result.
[refreshResult] :: RefreshResult a -> a

-- | In milliseconds.
[refreshExpiry] :: RefreshResult a -> Maybe Int

-- | Default refresh interval is one minute (in milliseconds).
defaultAsyncRefreshInterval :: Int

-- | Given a refresh action, create a new configuration.
newAsyncRefreshConf :: MonadIO m => m (RefreshResult a) -> AsyncRefreshConf m a

-- | Set default refresh interval, specified in milliseconds, in the given
--   configuration. If a refresh action fails or does not produce an expiry
--   time, this interval will be used.
asyncRefreshConfSetDefaultInterval :: Int -> AsyncRefreshConf m a -> AsyncRefreshConf m a

-- | Set the label in the provided configuration. This is a human readable
--   text, used for logging purposes.
asyncRefreshConfSetLabel :: Text -> AsyncRefreshConf m a -> AsyncRefreshConf m a

-- | Set the refresh factor. When a refresh gives an explicit expiry time
--   after a succesful refresh run, then this expiry time will be
--   multiplied by this factor, yielding the effective expiry time after
--   which a new refresh run will be scheduled.
asyncRefreshConfSetFactor :: Double -> AsyncRefreshConf m a -> AsyncRefreshConf m a

-- | Set a refresh callback for the provided configuration. This callback
--   will be called after a refresh run.
asyncRefreshConfSetCallback :: AsyncRefreshCallback m a -> AsyncRefreshConf m a -> AsyncRefreshConf m a

-- | Start a new thread taking care of refreshing of data according to the
--   given configuration.
newAsyncRefresh :: (MonadUnliftIO m, MonadCatch m, MonadMask m, MonadLogger m) => AsyncRefreshConf m a -> m AsyncRefresh
asyncRefreshAsync :: AsyncRefresh -> Async ()
