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


-- | Efficiently run periodic, on-demand actions
--   
@package auto-update
@version 0.1.2


-- | This module provides the ability to create reapers: dedicated cleanup
--   threads. These threads will automatically spawn and die based on the
--   presence of a workload to process on.
module Control.Reaper

-- | Settings for creating a reaper. This type has two parameters:
--   <tt>workload</tt> gives the entire workload, whereas <tt>item</tt>
--   gives an individual piece of the queue. A common approach is to have
--   <tt>workload</tt> be a list of <tt>item</tt>s. This is encouraged by
--   <a>defaultReaperSettings</a> and <a>mkListAction</a>.
--   
--   Since 0.1.1
data ReaperSettings workload item

-- | Default <tt>ReaperSettings</tt> value, biased towards having a list of
--   work items.
--   
--   Since 0.1.1
defaultReaperSettings :: ReaperSettings [item] item

-- | The action to perform on a workload. The result of this is a "workload
--   modifying" function. In the common case of using lists, the result
--   should be a difference list that prepends the remaining workload to
--   the temporary workload. For help with setting up such an action, see
--   <a>mkListAction</a>.
--   
--   Default: do nothing with the workload, and then prepend it to the
--   temporary workload. This is incredibly useless; you should definitely
--   override this default.
--   
--   Since 0.1.1
reaperAction :: ReaperSettings workload item -> workload -> IO (workload -> workload)

-- | Number of microseconds to delay between calls of <a>reaperAction</a>.
--   
--   Default: 30 seconds.
--   
--   Since 0.1.1
reaperDelay :: ReaperSettings workload item -> Int

-- | Add an item onto a workload.
--   
--   Default: list consing.
--   
--   Since 0.1.1
reaperCons :: ReaperSettings workload item -> item -> workload -> workload

-- | Check if a workload is empty, in which case the worker thread will
--   shut down.
--   
--   Default: <a>null</a>.
--   
--   Since 0.1.1
reaperNull :: ReaperSettings workload item -> workload -> Bool

-- | An empty workload.
--   
--   Default: empty list.
--   
--   Since 0.1.1
reaperEmpty :: ReaperSettings workload item -> workload

-- | A data structure to hold reaper APIs.
data Reaper workload item
Reaper :: (item -> IO ()) -> IO workload -> IO workload -> Reaper workload item

-- | Adding an item to the workload
reaperAdd :: Reaper workload item -> item -> IO ()

-- | Reading workload.
reaperRead :: Reaper workload item -> IO workload

-- | Stopping the reaper thread if exists. The current workload is
--   returned.
reaperStop :: Reaper workload item -> IO workload

-- | Create a reaper addition function. This funciton can be used to add
--   new items to the workload. Spawning of reaper threads will be handled
--   for you automatically.
--   
--   Since 0.1.1
mkReaper :: ReaperSettings workload item -> IO (Reaper workload item)

-- | A helper function for creating <a>reaperAction</a> functions. You
--   would provide this function with a function to process a single work
--   item and return either a new work item, or <tt>Nothing</tt> if the
--   work item is expired.
--   
--   Since 0.1.1
mkListAction :: (item -> IO (Maybe item')) -> [item] -> IO ([item'] -> [item'])


-- | Debounce an action, ensuring it doesn't occur more than once for a
--   given period of time.
--   
--   This is useful as an optimization, for example to ensure that logs are
--   only flushed to disk at most once per second. See the fast-logger
--   package for an example usage.
--   
--   Since 0.1.2
module Control.Debounce

-- | Settings to control how debouncing should work.
--   
--   This should be constructed using <tt>defaultDebounceSettings</tt> and
--   record update syntax, e.g.:
--   
--   <pre>
--   let set = defaultDebounceSettings { debounceAction = flushLog }
--   </pre>
--   
--   Since 0.1.2
data DebounceSettings

-- | Default value for creating a <tt>DebounceSettings</tt>.
--   
--   Since 0.1.2
defaultDebounceSettings :: DebounceSettings

-- | Microseconds lag required between subsequence calls to the debounced
--   action.
--   
--   Default: 1 second (1000000)
--   
--   Since 0.1.2
debounceFreq :: DebounceSettings -> Int

-- | Action to be performed.
--   
--   Note: all exceptions thrown by this action will be silently discarded.
--   
--   Default: does nothing.
--   
--   Since 0.1.2
debounceAction :: DebounceSettings -> IO ()

-- | Generate an action which will trigger the debounced action to be
--   performed. The action will either be performed immediately, or after
--   the current cooldown period has expired.
--   
--   Since 0.1.2
mkDebounce :: DebounceSettings -> IO (IO ())


-- | A common problem is the desire to have an action run at a scheduled
--   interval, but only if it is needed. For example, instead of having
--   every web request result in a new <tt>getCurrentTime</tt> call, we'd
--   like to have a single worker thread run every second, updating an
--   <tt>IORef</tt>. However, if the request frequency is less than once
--   per second, this is a pessimization, and worse, kills idle GC.
--   
--   This library allows you to define actions which will either be
--   performed by a dedicated thread or, in times of low volume, will be
--   executed by the calling thread.
module Control.AutoUpdate

-- | Settings to control how values are updated.
--   
--   This should be constructed using <tt>defaultUpdateSettings</tt> and
--   record update syntax, e.g.:
--   
--   <pre>
--   let set = defaultUpdateSettings { updateAction = getCurrentTime }
--   </pre>
--   
--   Since 0.1.0
data UpdateSettings a

-- | Default value for creating an <tt>UpdateSettings</tt>.
--   
--   Since 0.1.0
defaultUpdateSettings :: UpdateSettings ()

-- | Microseconds between update calls. Same considerations as
--   <tt>threadDelay</tt> apply.
--   
--   Default: 1 second (1000000)
--   
--   Since 0.1.0
updateFreq :: UpdateSettings a -> Int

-- | NOTE: This value no longer has any effect, since worker threads are
--   dedicated instead of spawned on demand.
--   
--   Previously, this determined: How many times the data must be requested
--   before we decide to spawn a dedicated thread.
--   
--   Default: 3
--   
--   Since 0.1.0
updateSpawnThreshold :: UpdateSettings a -> Int

-- | Action to be performed to get the current value.
--   
--   Default: does nothing.
--   
--   Since 0.1.0
updateAction :: UpdateSettings a -> IO a

-- | Generate an action which will either read from an automatically
--   updated value, or run the update action in the current thread.
--   
--   Since 0.1.0
mkAutoUpdate :: UpdateSettings a -> IO (IO a)