on master help sign in
Merge pull request #756 from codedownio/master

Leading vs. trailing edges for Control.Debounce

commitae64943c2e44295bd0436ad001ad2617473261c4 authorMichael Snoyman <michael@snoyman.com> dateTue 9 Jul 2019, 10:40 (7 years ago) parent135c56f64a360a
7 files changed+308−114
auto-update/ChangeLog.md+5 auto-update/Control/Debounce.hs+19−53 auto-update/Control/Debounce/Internal.hs+98 auto-update/auto-update.cabal+11−9 auto-update/test/Control/AutoUpdateSpec.hs+26−25 auto-update/test/Control/DebounceSpec.hs+120 auto-update/test/Control/ReaperSpec.hs+29−27
auto-update/ChangeLog.md+5
@@ -1,5 +1,10 @@
11# ChangeLog for auto-update
22
3+## 0.1.6
4+
5+* Add control of activation on leading vs. trailing edges for Control.Debounce
6+ [#756](https://github.com/yesodweb/wai/pull/756)
7+
38## 0.1.5
49
510* Using the Strict and StrictData language extensions for GHC >8.
auto-update/Control/Debounce.hs+19−53
@@ -11,6 +11,7 @@
1111-- printString <- 'mkDebounce' 'defaultDebounceSettings'
1212-- { 'debounceAction' = putStrLn "Running action"
1313-- , 'debounceFreq' = 5000000 -- 5 seconds
14+-- , 'debounceEdge' = 'DI.trailingEdge' -- Trigger on the trailing edge
1415-- }
1516-- @
1617--
@@ -25,70 +26,35 @@
2526-- @since 0.1.2
2627module Control.Debounce
2728 ( -- * Type
28− DebounceSettings
29+ DI.DebounceSettings
2930 , defaultDebounceSettings
3031 -- * Accessors
31− , debounceFreq
32− , debounceAction
32+ , DI.debounceFreq
33+ , DI.debounceAction
34+ , DI.debounceEdge
35+ , DI.leadingEdge
36+ , DI.trailingEdge
3337 -- * Creation
3438 , mkDebounce
3539 ) where
3640
37−import Control.Concurrent (forkIO, threadDelay)
38−import Control.Concurrent.MVar (newEmptyMVar, takeMVar, tryPutMVar)
39−import Control.Exception (SomeException, handle, mask_)
40−import Control.Monad (forever, void)
41−
42−-- | Settings to control how debouncing should work.
43−--
44−-- This should be constructed using 'defaultDebounceSettings' and record
45−-- update syntax, e.g.:
46−--
47−-- @
48−-- let settings = 'defaultDebounceSettings' { 'debounceAction' = flushLog }
49−-- @
50−--
51−-- @since 0.1.2
52−data DebounceSettings = DebounceSettings
53− { debounceFreq :: Int
54− -- ^ Microseconds lag required between subsequence calls to the debounced
55− -- action.
56− --
57− -- Default: 1 second (1000000)
58− --
59− -- @since 0.1.2
60− , debounceAction :: IO ()
61− -- ^ Action to be performed.
62− --
63− -- Note: all exceptions thrown by this action will be silently discarded.
64− --
65− -- Default: does nothing.
66− --
67− -- @since 0.1.2
68− }
41+import Control.Concurrent (newEmptyMVar, threadDelay)
42+import qualified Control.Debounce.Internal as DI
6943
7044-- | Default value for creating a 'DebounceSettings'.
7145--
7246-- @since 0.1.2
73−defaultDebounceSettings :: DebounceSettings
74−defaultDebounceSettings = DebounceSettings
75− { debounceFreq = 1000000
76− , debounceAction = return ()
47+defaultDebounceSettings :: DI.DebounceSettings
48+defaultDebounceSettings = DI.DebounceSettings
49+ { DI.debounceFreq = 1000000
50+ , DI.debounceAction = return ()
51+ , DI.debounceEdge = DI.leadingEdge
7752 }
7853
79−-- | Generate an action which will trigger the debounced action to be
80−-- performed. The action will either be performed immediately, or after the
81−-- current cooldown period has expired.
54+-- | Generate an action which will trigger the debounced action to be performed.
8255--
8356-- @since 0.1.2
84−mkDebounce :: DebounceSettings -> IO (IO ())
85−mkDebounce (DebounceSettings freq action) = do
86− baton <- newEmptyMVar
87− mask_ $ void $ forkIO $ forever $ do
88− takeMVar baton
89− ignoreExc action
90− threadDelay freq
91− return $ void $ tryPutMVar baton ()
92−
93−ignoreExc :: IO () -> IO ()
94−ignoreExc = handle $ \(_ :: SomeException) -> return ()
57+mkDebounce :: DI.DebounceSettings -> IO (IO ())
58+mkDebounce settings = do
59+ baton <- newEmptyMVar
60+ DI.mkDebounceInternal baton threadDelay settings
auto-update/Control/Debounce/Internal.hsnew file+98
@@ -0,0 +1,98 @@
1+{-# LANGUAGE ScopedTypeVariables #-}
2+
3+-- | Unstable API which exposes internals for testing.
4+module Control.Debounce.Internal (
5+ DebounceSettings(..)
6+ , DebounceEdge(..)
7+ , leadingEdge
8+ , trailingEdge
9+ , mkDebounceInternal
10+ ) where
11+
12+import Control.Concurrent (forkIO)
13+import Control.Concurrent.MVar (takeMVar, tryPutMVar, tryTakeMVar, MVar)
14+import Control.Exception (SomeException, handle, mask_)
15+import Control.Monad (forever, void)
16+
17+-- | Settings to control how debouncing should work.
18+--
19+-- This should be constructed using 'defaultDebounceSettings' and record
20+-- update syntax, e.g.:
21+--
22+-- @
23+-- let settings = 'defaultDebounceSettings' { 'debounceAction' = flushLog }
24+-- @
25+--
26+-- @since 0.1.2
27+data DebounceSettings = DebounceSettings
28+ { debounceFreq :: Int
29+ -- ^ Length of the debounce timeout period in microseconds.
30+ --
31+ -- Default: 1 second (1000000)
32+ --
33+ -- @since 0.1.2
34+ , debounceAction :: IO ()
35+ -- ^ Action to be performed.
36+ --
37+ -- Note: all exceptions thrown by this action will be silently discarded.
38+ --
39+ -- Default: does nothing.
40+ --
41+ -- @since 0.1.2
42+ , debounceEdge :: DebounceEdge
43+ -- ^ Whether to perform the action on the leading edge or trailing edge of
44+ -- the timeout.
45+ --
46+ -- Default: 'trailingEdge'.
47+ --
48+ -- @since 0.1.6
49+ }
50+
51+-- | Setting to control whether the action happens at the leading and/or trailing
52+-- edge of the timeout.
53+--
54+-- @since 0.1.6
55+data DebounceEdge =
56+ Leading
57+ -- ^ Perform the action immediately, and then begin a cooldown period.
58+ -- If the trigger happens again during the cooldown, wait until the end of the cooldown
59+ -- and then perform the action again, then enter a new cooldown period.
60+ | Trailing
61+ -- ^ Start a cooldown period and perform the action when the period ends. If another trigger
62+ -- happens during the cooldown, it has no effect.
63+ deriving (Show, Eq)
64+
65+
66+-- | Perform the action immediately, and then begin a cooldown period.
67+-- If the trigger happens again during the cooldown, wait until the end of the cooldown
68+-- and then perform the action again, then enter a new cooldown period.
69+--
70+-- @since 0.1.6
71+leadingEdge :: DebounceEdge
72+leadingEdge = Leading
73+
74+-- | Start a cooldown period and perform the action when the period ends. If another trigger
75+-- happens during the cooldown, it has no effect.
76+--
77+-- @since 0.1.6
78+trailingEdge :: DebounceEdge
79+trailingEdge = Trailing
80+
81+mkDebounceInternal :: MVar () -> (Int -> IO ()) -> DebounceSettings -> IO (IO ())
82+mkDebounceInternal baton delayFn (DebounceSettings freq action edge) = do
83+ mask_ $ void $ forkIO $ forever $ do
84+ takeMVar baton
85+ case edge of
86+ Leading -> do
87+ ignoreExc action
88+ delayFn freq
89+ Trailing -> do
90+ delayFn freq
91+ -- Empty the baton of any other activations during the interval
92+ void $ tryTakeMVar baton
93+ ignoreExc action
94+
95+ return $ void $ tryPutMVar baton ()
96+
97+ignoreExc :: IO () -> IO ()
98+ignoreExc = handle $ \(_ :: SomeException) -> return ()
auto-update/auto-update.cabal+11−9
@@ -1,5 +1,5 @@
11name: auto-update
2−version: 0.1.5
2+version: 0.1.6
33synopsis: Efficiently run periodic, on-demand actions
44description: API docs and the README are available at <http://www.stackage.org/package/auto-update>.
55homepage: https://github.com/yesodweb/wai
@@ -17,6 +17,7 @@ library
1717 ghc-options: -Wall
1818 exposed-modules: Control.AutoUpdate
1919 Control.Debounce
20+ Control.Debounce.Internal
2021 Control.Reaper
2122 other-modules: Control.AutoUpdate.Util
2223 build-depends: base >= 4 && < 5
@@ -26,11 +27,12 @@ library
2627
2728-- Test suite is currently not robust enough, gives too many false negatives.
2829
29−-- test-suite spec
30−-- main-is: Spec.hs
31−-- other-modules: Control.AutoUpdateSpec
32−-- Control.ReaperSpec
33−-- hs-source-dirs: test
34−-- type: exitcode-stdio-1.0
35−-- build-depends: base, auto-update, hspec
36−-- default-language: Haskell2010
30+test-suite spec
31+ main-is: Spec.hs
32+ other-modules: Control.AutoUpdateSpec
33+ Control.DebounceSpec
34+ Control.ReaperSpec
35+ hs-source-dirs: test
36+ type: exitcode-stdio-1.0
37+ build-depends: base, auto-update, exceptions, hspec, retry, HUnit
38+ default-language: Haskell2010
auto-update/test/Control/AutoUpdateSpec.hs+26−25
@@ -1,34 +1,35 @@
11module Control.AutoUpdateSpec (spec) where
22
3−import Test.Hspec
4−import Test.Hspec.QuickCheck
5−import Data.IORef
3+import Control.AutoUpdate
64import Control.Concurrent (threadDelay)
75import Control.Monad (replicateM_, forM_)
8−import Control.AutoUpdate
6+import Data.IORef
7+import Test.Hspec
8+import Test.Hspec.QuickCheck
99
1010spec :: Spec
11−spec = do
12− prop "incrementer" $ \st' -> do
13− let st = abs st' `mod` 10000
14− ref <- newIORef 0
15− next <- mkAutoUpdate defaultUpdateSettings
16− { updateAction = atomicModifyIORef ref $ \i ->
17− let i' = succ i in i' `seq` (i', i')
18− , updateSpawnThreshold = st
19− , updateFreq = 10000
20− }
11+spec = return ()
12+ -- do
13+ -- prop "incrementer" $ \st' -> do
14+ -- let st = abs st' `mod` 10000
15+ -- ref <- newIORef 0
16+ -- next <- mkAutoUpdate defaultUpdateSettings
17+ -- { updateAction = atomicModifyIORef ref $ \i ->
18+ -- let i' = succ i in i' `seq` (i', i')
19+ -- , updateSpawnThreshold = st
20+ -- , updateFreq = 10000
21+ -- }
2122
22− forM_ [1..st + 1] $ \i -> do
23− j <- next
24− j `shouldBe` i
23+ -- forM_ [1..st + 1] $ \i -> do
24+ -- j <- next
25+ -- j `shouldBe` i
2526
26− replicateM_ 50 $ do
27− i <- next
28− i `shouldBe` st + 2
27+ -- replicateM_ 50 $ do
28+ -- i <- next
29+ -- i `shouldBe` st + 2
2930
30− threadDelay 60000
31− last1 <- readIORef ref
32− threadDelay 20000
33− last2 <- readIORef ref
34− last2 `shouldBe` last1
31+ -- threadDelay 60000
32+ -- last1 <- readIORef ref
33+ -- threadDelay 20000
34+ -- last2 <- readIORef ref
35+ -- last2 `shouldBe` last1
auto-update/test/Control/DebounceSpec.hsnew file+120
@@ -0,0 +1,120 @@
1+{-# LANGUAGE ScopedTypeVariables #-}
2+module Control.DebounceSpec (spec) where
3+
4+import Control.Concurrent
5+import Control.Debounce
6+import qualified Control.Debounce.Internal as DI
7+import Control.Monad
8+import Control.Monad.Catch
9+import Control.Retry
10+import Data.IORef
11+import Test.HUnit.Lang
12+import Test.Hspec
13+
14+spec :: Spec
15+spec = describe "mkDebounce" $ do
16+ describe "Leading edge" $ do
17+ it "works for a single event" $ do
18+ (ref, debounced, baton, returnFromWait) <- getDebounce leadingEdge
19+
20+ debounced
21+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 1)
22+
23+ returnFromWait
24+ pause
25+ readIORef ref >>= (`shouldBe` 1)
26+
27+ -- Try another round
28+ debounced
29+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 2)
30+
31+ returnFromWait
32+ pause
33+ readIORef ref >>= (`shouldBe` 2)
34+
35+ it "works for multiple events" $ do
36+ (ref, debounced, baton, returnFromWait) <- getDebounce leadingEdge
37+
38+ debounced
39+ waitForBatonToBeTaken baton
40+ debounced
41+ pause
42+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 1)
43+
44+ returnFromWait
45+ pause
46+ readIORef ref >>= (`shouldBe` 2)
47+
48+ describe "Trailing edge" $ do
49+ it "works for a single event" $ do
50+ (ref, debounced, baton, returnFromWait) <- getDebounce trailingEdge
51+
52+ debounced
53+ pause
54+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 0)
55+
56+ returnFromWait
57+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 1)
58+
59+ -- Try another round
60+ debounced
61+ pause
62+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 1)
63+
64+ returnFromWait
65+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 2)
66+
67+ it "works for multiple events" $ do
68+ (ref, debounced, baton, returnFromWait) <- getDebounce trailingEdge
69+
70+ debounced
71+ waitForBatonToBeTaken baton
72+ debounced
73+ pause
74+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 0)
75+
76+ returnFromWait
77+ waitUntil 5 $ readIORef ref >>= (`shouldBe` 1)
78+
79+
80+-- | Make a controllable delay function
81+getWaitAction :: IO (p -> IO (), IO ())
82+getWaitAction = do
83+ waitVar <- newEmptyMVar
84+ let waitAction _ = takeMVar waitVar
85+ let returnFromWait = putMVar waitVar ()
86+ return (waitAction, returnFromWait)
87+
88+-- | Get a debounce system with access to the internals for testing
89+getDebounce :: DI.DebounceEdge -> IO (IORef Int, IO (), MVar (), IO ())
90+getDebounce edge = do
91+ ref :: IORef Int <- newIORef 0
92+ let action = modifyIORef ref (+ 1)
93+
94+ (waitAction, returnFromWait) <- getWaitAction
95+
96+ baton <- newEmptyMVar
97+
98+ debounced <- DI.mkDebounceInternal baton waitAction defaultDebounceSettings {
99+ debounceFreq = 5000000 -- unused
100+ , debounceAction = action
101+ , debounceEdge = edge
102+ }
103+
104+ return (ref, debounced, baton, returnFromWait)
105+
106+-- | Pause briefly (100ms)
107+pause :: IO ()
108+pause = threadDelay 100000
109+
110+waitForBatonToBeTaken :: MVar () -> IO ()
111+waitForBatonToBeTaken baton = waitUntil 5 $ tryReadMVar baton >>= (`shouldBe` Nothing)
112+
113+-- | Wait up to n seconds for an action to complete without throwing an HUnitFailure
114+waitUntil :: Int -> IO a -> IO ()
115+waitUntil n action = recovering policy [handler] (\_status -> void action)
116+ where policy = constantDelay 1000 `mappend` limitRetries (n * 1000) -- 1ms * n * 1000 tries = n seconds
117+ handler _status = Handler (\(HUnitFailure {}) -> return True)
118+
119+main :: IO ()
120+main = hspec spec
auto-update/test/Control/ReaperSpec.hs+29−27
@@ -1,37 +1,39 @@
11module Control.ReaperSpec (spec) where
22
3−import Control.Reaper
43import Control.Concurrent
4+import Control.Reaper
5+import Data.IORef
56import Test.Hspec
67import Test.Hspec.QuickCheck
7−import Data.IORef
88
9−type Item = (Int, IORef Int)
10−
11−action = mkListAction $ \(i, ref) -> do
12− modifyIORef ref succ
13− return $ if i > 1
14− then Just (pred i, ref)
15− else Nothing
169
1710spec :: Spec
18−spec = prop "works" $ \is -> do
19− reaper <- mkReaper defaultReaperSettings
20− { reaperAction = action
21− , reaperDelay = 1000
22− }
11+spec = return ()
12+-- prop "works" $ \is -> do
13+-- reaper <- mkReaper defaultReaperSettings
14+-- { reaperAction = action
15+-- , reaperDelay = 1000
16+-- }
17+
18+-- let mkTestCase i = do
19+-- ref <- newIORef 0
20+-- let expected = (abs i `mod` 10) + 1
21+-- reaperAdd reaper (expected, ref)
22+-- return (expected, ref)
23+-- testCases <- mapM mkTestCase is
24+
25+-- let test (expected, ref) = do
26+-- actual <- readIORef ref
27+-- actual `shouldBe` (expected :: Int)
28+-- threadDelay 100000
29+-- mapM_ test testCases
30+-- [] <- reaperRead reaper
31+-- return ()
2332
24− let mkTestCase i = do
25− ref <- newIORef 0
26− let expected = (abs i `mod` 10) + 1
27− reaperAdd reaper (expected, ref)
28− return (expected, ref)
29− testCases <- mapM mkTestCase is
33+-- type Item = (Int, IORef Int)
3034
31− let test (expected, ref) = do
32− actual <- readIORef ref
33− actual `shouldBe` (expected :: Int)
34− threadDelay 100000
35− mapM_ test testCases
36− [] <- reaperRead reaper
37− return ()
35+-- action = mkListAction $ \(i, ref) -> do
36+-- modifyIORef ref succ
37+-- return $ if i > 1
38+-- then Just (pred i, ref)
39+-- else Nothing