auto-update-0.2.4: Efficiently run periodic, on-demand actions
Safe HaskellSafe-Inferred
LanguageHaskell2010

Control.Debounce

Description

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:

> printString <- mkDebounce defaultDebounceSettings
                 { debounceAction = putStrLn "Running action"
                 , debounceFreq = 5000000 -- 5 seconds
                 , debounceEdge = trailingEdge -- Trigger on the trailing edge
                 }
> printString
Running action
> printString
<Wait five seconds>
Running action

See the fast-logger package (System.Log.FastLogger) for real-world usage.

Since: 0.1.2

Synopsis

Creation

mkDebounce :: DebounceSettings -> IO (IO ()) Source #

Generate an action which will trigger the debounced action to be performed.

N.B. The generated action will always immediately return, regardless of the debounceFreq, as the debounced action (and the delay/cooldown) is always performed in a separate thread.

Since: 0.1.2

Settings

data DebounceSettings Source #

Settings to control how debouncing should work.

This should be constructed using defaultDebounceSettings and record update syntax, e.g.:

let settings = defaultDebounceSettings { debounceAction = flushLog }

Since: 0.1.2

defaultDebounceSettings :: DebounceSettings Source #

Default value for creating a DebounceSettings.

Since: 0.1.2

Accessors

debounceFreq :: DebounceSettings -> Int Source #

Length of the debounce timeout period in microseconds.

Default: 1 second (1000000)

Since: 0.1.2

debounceAction :: DebounceSettings -> IO () Source #

Action to be performed.

Note: all exceptions thrown by this action will be silently discarded.

Default: does nothing.

Since: 0.1.2

debounceEdge :: DebounceSettings -> DebounceEdge Source #

Whether to perform the action on the leading edge or trailing edge of the timeout.

Default: leadingEdge.

Since: 0.1.6

debounceThreadName :: DebounceSettings -> String Source #

Label of the thread spawned when debouncing.

Default: Debounce.

Since: 0.2.2

Edge types

leadingEdge :: DebounceEdge Source #

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:

! = function execution
. = cooldown period
X = debounced code execution

!   !         !            !
 ....... ....... .......    .......
X       X       X          X

Since: 0.1.6

leadingMuteEdge :: DebounceEdge Source #

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:

! = function execution
. = cooldown period
X = debounced code execution

!   !      !     !
 .......    .......
X          X

Since: 0.1.6

trailingEdge :: DebounceEdge Source #

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:

! = function execution
. = cooldown period
X = debounced code execution

!     !     !  !
 .......     .......
        X           X

Since: 0.1.6

trailingDelayEdge :: DebounceEdge Source #

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

N.B. If a trigger happens DURING the debounceAction it starts a new cooldown. So if the debounceAction takes longer than the debounceFreq, it might run again before the previous action has ended.

Example of how this style debounce works:

! = function execution
. = cooldown period
X = debounced code execution

!           !  !    !
 .......     ...............
        X                   X

Since: 0.1.6