Updates

Author: 27pchrisl

README.md

@@ -185,25 +185,24 @@ $pi->input1()->monitor(new DigitalMonitor, function($newValue) {
 
 #### Monitor::debounce
 
-Wraps a callback to fire **only after changes stop** for the given interval (in milliseconds).
+Configures the monitor to fire **only after changes stop** for the given interval (in milliseconds).
 
 ```php
-$pi->input1()->monitor(new DigitalMonitor, Monitor::debounce(function($value) {
+$pi->input1()->monitor((new DigitalMonitor)->debounce(200), function($value) {
     // Handle change after quiet period
-}, 200));
+});
 ```
 
 #### Monitor::throttle
 
-Wraps a callback to fire **at most once per interval** (in milliseconds).
+Configures the monitor to fire **at most once per interval** (in milliseconds).
 
 ```php
-$pi->input1()->monitor(new DigitalMonitor, Monitor::throttle(function($value) {
+$pi->input1()->monitor((new DigitalMonitor)->throttle(200), function($value) {
     // Handle change no more than every 200ms
-}, 200));
+});
 ```
 
-
 ### Process Image (Low-Level)
 
 Get the raw process image interface for advanced access:

src/Modules/Module.php

@@ -62,11 +62,13 @@ public function cancel(): void
 
     public function monitor(string $variable, Monitor $monitor, callable $callback): void
     {
-        Event::listen(PollingEvent::class, function () use ($callback, $variable, $monitor) {
+        $wrapped = $monitor->wrap($callback);
+
+        Event::listen(PollingEvent::class, function () use ($wrapped, $variable, $monitor) {
             $next = $this->getProcessImage()->readVariable($variable);
 
             if ($monitor->evaluate($next)) {
-                $callback($next);
+                $wrapped($next);
             }
         });
     }

src/Monitors/Monitor.php

@@ -8,9 +8,40 @@
 
 abstract class Monitor
 {
+    protected ?int $rateLimit = null;
+
+    protected RateLimit $rateLimitType = RateLimit::None;
+
+    public function debounce(int $milliseconds): static
+    {
+        $this->rateLimit = $milliseconds;
+        $this->rateLimitType = RateLimit::Debounce;
+
+        return $this;
+    }
+
+    public function throttle(int $milliseconds): static
+    {
+        $this->rateLimit = $milliseconds;
+        $this->rateLimitType = RateLimit::Throttle;
+
+        return $this;
+    }
+
+    public function wrap(callable $callback): callable
+    {
+        assert($this->rateLimitType === RateLimit::None || is_int($this->rateLimit));
+
+        return match ($this->rateLimitType) {
+            RateLimit::None => $callback,
+            RateLimit::Debounce => $this->_debouncer($callback, (int) $this->rateLimit),
+            RateLimit::Throttle => $this->_throttler($callback, (int) $this->rateLimit),
+        };
+    }
+
     abstract public function evaluate(int|bool $next): bool;
 
-    public static function debounce(callable $callback, int $milliseconds): callable
+    protected function _debouncer(callable $callback, int $milliseconds): callable
     {
         $timerId = null;
 
@@ -26,7 +57,7 @@ public static function debounce(callable $callback, int $milliseconds): callable
         };
     }
 
-    public static function throttle(callable $callback, int $milliseconds): callable
+    protected function _throttler(callable $callback, int $milliseconds): callable
     {
         $throttling = false;
 

src/Monitors/RateLimit.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flat3\RevPi\Monitors;
+
+enum RateLimit
+{
+    case None;
+    case Debounce;
+    case Throttle;
+}

tests/Monitors/MonitorTest.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace Flat3\RevPi\Tests\Monitors;
+
+use Flat3\RevPi\Monitors\DigitalMonitor;
+use Flat3\RevPi\Tests\TestCase;
+use Flat3\RevPi\Tests\UsesVirtualEnvironment;
+
+class MonitorTest extends TestCase implements UsesVirtualEnvironment
+{
+    /**
+     * Helper to advance the event loop n times (simulate time passing).
+     */
+    public function test_no_throttle_debounce(): void
+    {
+        $monitor = new DigitalMonitor;
+        $results = [];
+
+        $callback = function ($val) use (&$results) {
+            $results[] = $val;
+        };
+
+        $wrapped = $monitor->wrap($callback);
+
+        // Simulate variable changes
+        $inputs = [0, 0, 1, 1, 0, 1, 1, 0];
+        foreach ($inputs as $i => $value) {
+            if ($monitor->evaluate($value)) {
+                $wrapped($value);
+            }
+            $this->loop(1, 2);
+        }
+
+        // Only trigger callback on CHANGE (not same value twice),
+        // DigitalMonitor returns true for a transition.
+        self::assertSame([1, 0, 1, 0], $results);
+    }
+
+    public function test_fast_debounce(): void
+    {
+        $monitor = (new DigitalMonitor)->debounce(1); // 1ms debounce
+        $results = [];
+        $callback = function ($val) use (&$results) {
+            $results[] = $val;
+        };
+        $wrapped = $monitor->wrap($callback);
+
+        $inputs = [0, 1, 0, 1, 0];
+        foreach ($inputs as $value) {
+            if ($monitor->evaluate($value)) {
+                $wrapped($value);
+            }
+            $this->loop(1, 2);
+        }
+
+        // Advance loop to fire debounce once
+        $this->loop(2, 2);
+
+        self::assertSame([0], $results);
+
+        // Debounce with enough time between events so each triggers
+        $monitor = (new DigitalMonitor)->debounce(1);
+        $results = [];
+        $wrapped = $monitor->wrap(function ($v) use (&$results) {
+            $results[] = $v;
+        });
+
+        $transitions = [0, 1, 0, 1, 0];
+        foreach ($transitions as $value) {
+            if ($monitor->evaluate($value)) {
+                $wrapped($value);
+            }
+            $this->loop(2, 2); // Let debounce interval expire
+        }
+        self::assertSame([1, 0, 1, 0], $results);
+    }
+
+    public function test_fast_throttle(): void
+    {
+        $monitor = (new DigitalMonitor)->throttle(2); // 2ms throttle
+        $results = [];
+        $callback = function ($val) use (&$results) {
+            $results[] = $val;
+        };
+        $wrapped = $monitor->wrap($callback);
+
+        $inputs = [0, 1, 0, 1, 0];
+
+        // Submit all transitions rapidly with 0ms gap, before throttle can expire
+        foreach ($inputs as $value) {
+            if ($monitor->evaluate($value)) {
+                $wrapped($value);
+            }
+        }
+        // Should only fire the first one!
+        $this->loop(3, 2);
+
+        // Now let throttle window expire, and send another transition
+        if ($monitor->evaluate(1)) {
+            $wrapped(1);
+        }
+        $this->loop(3, 2);
+
+        self::assertSame([1, 1], $results);
+    }
+}