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

MaintainerToshio Ito <debug.ito@gmail.com>
Safe HaskellNone
LanguageHaskell2010

Control.FoldDebounce

Contents

Description

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

Synopsis

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

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

UnexpectedClosedException SomeException

The SomeException is thrown in the background thread.