fold-debounce-0.2.0.12: Fold multiple events that happen in a given period of time.

Maintainer | Toshio Ito <debug.ito@gmail.com>
Safe Haskell | Safe-Inferred
Language | Haskell2010

Control.FoldDebounce

Contents

- Create the trigger
- Parameter types
  - Accessors for `Opts`
  - Preset parameters
- Use the trigger
- Finish the trigger
- Exception types

Description

    module Main (main) where

    import System.IO (putStrLn)
    import Control.Concurrent (threadDelay)

    import qualified Control.FoldDebounce as Fdeb

    printValue :: Int -> IO ()
    printValue v = putStrLn ("value = " ++ show v)

    main :: IO ()
    main = do
      trigger <- Fdeb.new Fdeb.Args { Fdeb.cb = printValue, Fdeb.fold = (+), Fdeb.init = 0 }
                          Fdeb.def { Fdeb.delay = 500000 }
      let send' = Fdeb.send trigger
      send' 1
      send' 2
      send' 3
      threadDelay 1000000 -- During this period, "value = 6" is printed.
      send' 4
      threadDelay 1000    -- Nothing is printed.
      send' 5
      threadDelay 1000000 -- During this period, "value = 9" is printed.
      Fdeb.close trigger

This module is similar to Control.Debounce. It debouces input events and regulates the frequency at which the action (callback) is executed.

The difference from Control.Debounce is:

- With Control.Debounce, you cannot pass values to the callback action. This module folds (accumulates) the input events (type `i`) and passes the folded output event (type `o`) to the callback.
- Control.Debounce immediately runs the callback at the first input event. This module just starts a timer at the first input, and runs the callback when the timer expires.

The API and documentation is borrowed from a Perl module called AnyEvent::Debounce. See https://metacpan.org/pod/AnyEvent::Debounce

Synopsis

- new :: Args i o -> Opts i o -> IO (Trigger i o)
- data Trigger i o
- data Args i o = Args {
  - cb :: o -> IO ()
  - fold :: o -> i -> o
  - init :: o
  }
- data Opts i o
- def :: Default a => a
- delay :: Opts i o -> Int
- alwaysResetTimer :: Opts i o -> Bool
- forStack :: ([i] -> IO ()) -> Args i [i]
- forMonoid :: Monoid i => (i -> IO ()) -> Args i i
- forVoid :: IO () -> Args i ()
- send :: Trigger i o -> i -> IO ()
- close :: Trigger i o -> IO ()
- data OpException
  - = AlreadyClosedException
  - | UnexpectedClosedException SomeException

# Create the trigger

new Source #

Arguments

:: Args i o | mandatory parameters
-> Opts i o | optional parameters
-> IO (Trigger i o) | action to create the trigger.

Create a FoldDebounce trigger.

data Trigger i o Source #

A trigger to send input events to FoldDebounce. You input data of type `i` to the trigger, and it outputs data of type `o`.

# Parameter types

data Args i o Source #

Mandatory parameters for `new`.

Constructors

Args |

Fields

- cb :: o -> IO ()

  The callback to be called when the output event is emitted. Note that this action is run in a different thread than the one calling `send`.

  The callback should not throw any exception. In this case, the `Trigger` is abnormally closed, causing `UnexpectedClosedException` when `close`.

- fold :: o -> i -> o

  The binary operation of left-fold. The left-fold is evaluated strictly.

- init :: o

  The initial value of the left-fold.

data Opts i o Source #

Optional parameters for `new`. You can get the default by `def` function.

#### Instances

Instances details

Default (Opts i o) Source # |
Instance details Defined in Control.FoldDebounce Methods def :: Opts i o Source #

def :: Default a => a Source #

The default value for this type.

## Accessors for `Opts`

You can update fields in `Opts` via these accessors.

delay :: Opts i o -> Int Source #

The time (in microsecond) to wait after receiving an event before sending it, in case more events happen in the interim.

Default: 1 second (1000000)

alwaysResetTimer :: Opts i o -> Bool Source #

Normally, when an event is received and it's the first of a series, a timer is started, and when that timer expires, all events are sent. If you set this parameter to True, then the timer is reset after each event is received.

Default: False

## Preset parameters

forStack Source #

Arguments

:: ([i] -> IO ()) | `cb` field.
-> Args i [i] |

`Args` for stacks. Input events are accumulated in a stack, i.e., the last event is at the head of the list.

forMonoid Source #

Arguments

:: Monoid i |
=> (i -> IO ()) | `cb` field.
-> Args i i |

`Args` for monoids. Input events are appended to the tail.

forVoid Source #

Arguments

:: IO () | `cb` field.
-> Args i () |

`Args` that discards input events. Although input events are not folded, they still start the timer and activate the callback.

# Use the trigger

send :: Trigger i o -> i -> IO () Source #

Send an input event.

If the `Trigger` is already closed, it throws `AlreadyClosedException`. If the `Trigger` has been abnormally closed, it throws `UnexpectedClosedException`.

# Finish the trigger

close :: Trigger i o -> IO () Source #

Close and release the `Trigger`. If there is a pending output event, the event is fired immediately.

If the `Trigger` has been abnormally closed, it throws `UnexpectedClosedException`.

# Exception types

data OpException Source #

Exception type used by FoldDebounce operations

Constructors

AlreadyClosedException | You attempted to `send` after the trigger is already `close`d.
UnexpectedClosedException SomeException | The `SomeException` is thrown in the background thread.

#### Instances

Instances details

Exception OpException Source # |
Instance details Defined in Control.FoldDebounce Methods toException :: OpException -> SomeException Source # fromException :: SomeException -> Maybe OpException Source # displayException :: OpException -> String Source #
Show OpException Source # |
Instance details Defined in Control.FoldDebounce Methods showsPrec :: Int -> OpException -> ShowS Source # show :: OpException -> String Source # showList :: [OpException] -> ShowS Source #