feat: Add ThrottledInvoker utility

Common use case is throttling logging.

SDB-9889

Author: bnbajwa

toolbox/util/Utility.hpp

@@ -167,6 +167,37 @@ inline constexpr std::string_view bool_to_alpha(bool b) noexcept
     return b ? "true" : "false";
 }
 
+/// Throttles the invocation of a callable to not exceed a specified rate.
+/// The rate is controlled by a cooldown interval.
+///
+/// \tparam ClockT The clock type to use for time points.
+/// \tparam DurationT The duration type for the cooldown interval.
+template <typename ClockT, typename DurationT>
+class ThrottledInvoker {
+    using TimePointT = typename ClockT::time_point;
+
+  public:
+    explicit ThrottledInvoker(DurationT cooldown_interval)
+    : cooldown_interval_(cooldown_interval) {}
+
+    template <typename Callable>
+    void operator()(TimePointT now, Callable&& callable)
+    {
+        if (now < last_time_invoked_) [[unlikely]] {
+            return;
+        }
+
+        if (duration_cast<DurationT>(now - last_time_invoked_) > cooldown_interval_) {
+            last_time_invoked_ = now;
+            std::forward<Callable>(callable)();
+        }
+    }
+
+  private:
+    const DurationT cooldown_interval_{};
+    TimePointT last_time_invoked_{};
+};
+
 } // namespace util
 } // namespace toolbox
 

toolbox/util/Utility.ut.cpp

@@ -15,8 +15,12 @@
 // limitations under the License.
 
 #include "Utility.hpp"
+
+#include <toolbox/sys/Time.hpp>
+
 #include <cmath>
 #include <limits>
+#include <thread>
 
 #include <boost/test/unit_test.hpp>
 
@@ -391,4 +395,31 @@ BOOST_AUTO_TEST_CASE(DecDigitSignedCase)
     BOOST_CHECK_EQUAL(dec_digits(std::int64_t{9223372036854775807}), 19);
 }
 
+BOOST_AUTO_TEST_CASE(ThrottledInvokerCheck)
+{
+    constexpr auto threshold = 1'000us;
+    ThrottledInvoker<MonoClock, Micros> throttler{threshold};
+
+    std::size_t count = 0;
+
+    auto check_throttling = [&] {
+        auto now = MonoClock::now();
+        const auto end = now + threshold;
+        while (now < end) {
+            throttler(now, [&]() { ++count; });
+            now = MonoClock::now();
+        }
+    };
+
+    check_throttling();
+    BOOST_CHECK_EQUAL(count, 1);
+
+    // sleep for a bit to pass the cooldown period
+    std::this_thread::sleep_for(threshold);
+
+    // the throttle should invoke again now
+    check_throttling();
+    BOOST_CHECK_EQUAL(count, 2);
+}
+
 BOOST_AUTO_TEST_SUITE_END()