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


-- | Efficiently run periodic, on-demand actions
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/auto-update</a>.
@package auto-update
@version 0.1.5


-- | In a multithreaded environment, running actions on a regularly
--   scheduled background thread can dramatically improve performance. For
--   example, web servers need to return the current time with each HTTP
--   response. For a high-volume server, it's much faster for a dedicated
--   thread to run every second, and write the current time to a shared
--   <tt>IORef</tt>, than it is for each request to make its own call to
--   <tt>getCurrentTime</tt>.
--   
--   But for a low-volume server, whose request frequency is less than once
--   per second, that approach will result in <i>more</i> calls to
--   <tt>getCurrentTime</tt> than necessary, and worse, kills idle GC.
--   
--   This library solves that problem by allowing 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.
--   
--   Example usage:
--   
--   <pre>
--   import <a>Data.Time</a>
--   import <a>Control.AutoUpdate</a>
--   
--   getTime &lt;- <a>mkAutoUpdate</a> <a>defaultUpdateSettings</a>
--                { <a>updateAction</a> = <a>getCurrentTime</a>
--                , <a>updateFreq</a> = 1000000 -- The default frequency, once per second
--                }
--   currentTime &lt;- getTime
--   </pre>
--   
--   For more examples, <a>see the blog post introducing this library</a>.
module Control.AutoUpdate

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

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

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

-- | Microseconds between update calls. Same considerations as
--   <a>threadDelay</a> apply.
--   
--   Default: 1 second (1000000)
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
updateSpawnThreshold :: UpdateSettings a -> Int

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

-- | Generate an action which will either read from an automatically
--   updated value, or run the update action in the current thread if the
--   first time or the provided modify action after that.
mkAutoUpdateWithModify :: UpdateSettings a -> (a -> IO a) -> IO (IO a)


-- | 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.
--   
--   Example usage:
--   
--   <pre>
--   printString &lt;- <a>mkDebounce</a> <a>defaultDebounceSettings</a>
--                    { <a>debounceAction</a> = putStrLn "Running action"
--                    , <a>debounceFreq</a> = 5000000 -- 5 seconds
--                    }
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; printString
--   Running action
--   
--   &gt;&gt;&gt; printString
--   &lt;Wait five seconds&gt;
--   Running action
--   </pre>
--   
--   See the fast-logger package (<a>System.Log.FastLogger</a>) for
--   real-world usage.
module Control.Debounce

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

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

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

-- | Action to be performed.
--   
--   Note: all exceptions thrown by this action will be silently discarded.
--   
--   Default: does nothing.
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.
mkDebounce :: DebounceSettings -> IO (IO ())


-- | 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. Example uses include:
--   
--   <ul>
--   <li>Killing long-running jobs</li>
--   <li>Closing unused connections in a connection pool</li>
--   <li>Pruning a cache of old items (see example below)</li>
--   </ul>
--   
--   For real-world usage, search the <a>WAI family of packages</a> for
--   imports of <a>Control.Reaper</a>.
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>.
data ReaperSettings workload item

-- | Default <tt>ReaperSettings</tt> value, biased towards having a list of
--   work items.
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. The temporary workload here refers to items
--   added to the workload while the reaper action is running. 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.
reaperAction :: ReaperSettings workload item -> workload -> IO (workload -> workload)

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

-- | Add an item onto a workload.
--   
--   Default: list consing.
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>.
reaperNull :: ReaperSettings workload item -> workload -> Bool

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

-- | A data structure to hold reaper APIs.
data Reaper workload item
Reaper :: (item -> IO ()) -> IO workload -> IO workload -> IO () -> 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

-- | Killing the reaper thread immediately if exists.
[reaperKill] :: Reaper workload item -> IO ()

-- | Create a reaper addition function. This function can be used to add
--   new items to the workload. Spawning of reaper threads will be handled
--   for you automatically.
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.
mkListAction :: (item -> IO (Maybe item')) -> [item] -> IO ([item'] -> [item'])