Control.Debounce

auto-update-0.2.6: Efficiently run periodic, on-demand actions

Safe Haskell | None
Language | Haskell2010

Control.Debounce

Contents

- Creation
- Settings
  - Accessors
  - Edge types

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

- mkDebounce :: DebounceSettings -> IO (IO ())
- data DebounceSettings
- defaultDebounceSettings :: DebounceSettings
- debounceFreq :: DebounceSettings -> Int
- debounceAction :: DebounceSettings -> IO ()
- debounceEdge :: DebounceSettings -> DebounceEdge
- debounceThreadName :: DebounceSettings -> String
- leadingEdge :: DebounceEdge
- leadingMuteEdge :: DebounceEdge
- trailingEdge :: DebounceEdge
- trailingDelayEdge :: DebounceEdge

# Creation

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

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 #

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 #

Default value for creating a `DebounceSettings`.

Since: 0.1.2

## Accessors

debounceFreq :: DebounceSettings -> Int #

Length of the debounce timeout period in microseconds.

Default: 1 second (1000000)

Since: 0.1.2

debounceAction :: DebounceSettings -> IO () #

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 #

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

Default: `leadingEdge`.

Since: 0.1.6

debounceThreadName :: DebounceSettings -> String #

Label of the thread spawned when debouncing.

Default: `Debounce`.

Since: 0.2.2

## Edge types

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

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

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

Since: 0.1.6

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

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

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

Since: 0.1.6

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

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

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

Since: 0.1.6

trailingDelayEdge :: 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.

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