Control.FoldDebounce

Synopsis:

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.

IMPORTANT NOTE: currently you have to add -threaded option to ghc linker to use this module. I'm not sure if you can use it with other compilers.

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

Create the trigger

new

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

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

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

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

Instances

Default (Opts i o)

def :: Default a => a

The default value for this type.

Accessors for Opts

You can update fields in Opts via these accessors.

delay :: Opts i o -> Int

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

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

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

Arguments

:: Monoid i

=> (i -> IO ())

cb field.

-> Args i i

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

forVoid

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

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

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

Exception type used by FoldDebounce operations

Constructors

AlreadyClosedException

You attempted to send after the trigger is already closed.

UnexpectedClosedException SomeException

The SomeException is thrown in the background thread.

Instances

Show OpException

Exception OpException

Typeable * OpException