-- 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.2.4


-- | 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

-- | Label of the thread being forked.
--   
--   Default: <tt><a>AutoUpdate</a></tt>
updateThreadName :: UpdateSettings a -> String

-- | 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)


-- | Unstable API which exposes internals for testing.
module Control.Debounce.Internal

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

-- | Length of the debounce timeout period in microseconds.
--   
--   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 ()

-- | Whether to perform the action on the leading edge or trailing edge of
--   the timeout.
--   
--   Default: <a>leadingEdge</a>.
[debounceEdge] :: DebounceSettings -> DebounceEdge

-- | Label of the thread spawned when debouncing.
--   
--   Default: <tt><a>Debounce</a></tt>.
[debounceThreadName] :: DebounceSettings -> String

-- | Setting to control whether the action happens at the leading and/or
--   trailing edge of the timeout.
data DebounceEdge

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, wait until the end of
--   the cooldown and then perform the action again, then enter a new
--   cooldown period.
Leading :: DebounceEdge

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, it is ignored.
LeadingMute :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it has no effect.
Trailing :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it restarts the
--   cooldown again.
TrailingDelay :: DebounceEdge

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, wait until the end of
--   the cooldown and then perform the action again, then enter a new
--   cooldown period.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !   !         !            !
--    ....... ....... .......    .......
--   X       X       X          X
--   </pre>
leadingEdge :: DebounceEdge

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, it is ignored.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !   !      !     !
--    .......    .......
--   X          X
--   </pre>
leadingMuteEdge :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it has no effect.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !     !     !  !
--    .......     .......
--           X           X
--   </pre>
trailingEdge :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it restarts the
--   cooldown again.
--   
--   <i>N.B. If a trigger happens DURING the <a>debounceAction</a> it
--   starts a new cooldown.</i> <i>So if the <a>debounceAction</a> takes
--   longer than the <a>debounceFreq</a>, it might run</i> <i>again before
--   the previous action has ended.</i>
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !           !  !    !
--    .......     ...............
--           X                   X
--   </pre>
trailingDelayEdge :: DebounceEdge
mkDebounceInternal :: MVar () -> (Int -> IO ()) -> DebounceSettings -> IO (IO ())
instance GHC.Classes.Eq Control.Debounce.Internal.DebounceEdge
instance GHC.Show.Show Control.Debounce.Internal.DebounceEdge


-- | 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>
--   &gt; printString &lt;- <a>mkDebounce</a> <a>defaultDebounceSettings</a>
--                    { <tt>debounceAction</tt> = putStrLn "Running action"
--                    , <tt>debounceFreq</tt> = 5000000 -- 5 seconds
--                    , <tt>debounceEdge</tt> = <a>trailingEdge</a> -- Trigger on the trailing edge
--                    }
--   &gt; printString
--   Running action
--   &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

-- | Generate an action which will trigger the debounced action to be
--   performed.
--   
--   <i>N.B. The generated action will always immediately return,
--   regardless of the <tt>debounceFreq</tt>,</i> <i>as the debounced
--   action (and the delay/cooldown) is always performed in a separate
--   thread.</i>
mkDebounce :: DebounceSettings -> IO (IO ())

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

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

-- | Length of the debounce timeout period in microseconds.
--   
--   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 ()

-- | Whether to perform the action on the leading edge or trailing edge of
--   the timeout.
--   
--   Default: <a>leadingEdge</a>.
debounceEdge :: DebounceSettings -> DebounceEdge

-- | Label of the thread spawned when debouncing.
--   
--   Default: <tt><a>Debounce</a></tt>.
debounceThreadName :: DebounceSettings -> String

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, wait until the end of
--   the cooldown and then perform the action again, then enter a new
--   cooldown period.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !   !         !            !
--    ....... ....... .......    .......
--   X       X       X          X
--   </pre>
leadingEdge :: DebounceEdge

-- | Perform the action immediately, and then begin a cooldown period. If
--   the trigger happens again during the cooldown, it is ignored.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !   !      !     !
--    .......    .......
--   X          X
--   </pre>
leadingMuteEdge :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it has no effect.
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !     !     !  !
--    .......     .......
--           X           X
--   </pre>
trailingEdge :: DebounceEdge

-- | Start a cooldown period and perform the action when the period ends.
--   If another trigger happens during the cooldown, it restarts the
--   cooldown again.
--   
--   <i>N.B. If a trigger happens DURING the <a>debounceAction</a> it
--   starts a new cooldown.</i> <i>So if the <a>debounceAction</a> takes
--   longer than the <a>debounceFreq</a>, it might run</i> <i>again before
--   the previous action has ended.</i>
--   
--   Example of how this style debounce works:
--   
--   <pre>
--   ! = function execution
--   . = cooldown period
--   X = debounced code execution
--   
--   !           !  !    !
--    .......     ...............
--           X                   X
--   </pre>
trailingDelayEdge :: DebounceEdge

module Control.Reaper.Internal

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

-- | Modify the workload. The resulting workload is returned.
--   
--   If there is no reaper thread, the modifier will not be applied and
--   <tt>reaperEmpty</tt> will be returned.
--   
--   If the reaper is currently executing jobs, those jobs will not be in
--   the given workload and the workload might appear empty.
--   
--   If all jobs are removed by the modifier, the reaper thread will not be
--   killed. The reaper thread will only terminate if <a>reaperKill</a> is
--   called or the result of <tt>reaperAction</tt> satisfies
--   <tt>reaperNull</tt>.
[reaperModify] :: Reaper workload item -> (workload -> workload) -> 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 ()


-- | 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

-- | Label of the thread spawned by the reaper.
--   
--   Default: <tt><a>Reaper</a></tt>.
reaperThreadName :: ReaperSettings workload item -> String

-- | A data structure to hold reaper APIs.
data Reaper workload item

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

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

-- | Modify the workload. The resulting workload is returned.
--   
--   If there is no reaper thread, the modifier will not be applied and
--   <tt>reaperEmpty</tt> will be returned.
--   
--   If the reaper is currently executing jobs, those jobs will not be in
--   the given workload and the workload might appear empty.
--   
--   If all jobs are removed by the modifier, the reaper thread will not be
--   killed. The reaper thread will only terminate if <a>reaperKill</a> is
--   called or the result of <tt>reaperAction</tt> satisfies
--   <tt>reaperNull</tt>.
reaperModify :: Reaper workload item -> (workload -> workload) -> 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'])