feat(interrupt): Add API for tracking and getting the min queue size (#…

…344)

* feat(interrupt): Add API for tracking and getting the min queue size
* Update `Interupt` to track the minimum number of free spaces in the queue and an API for querying it, over the lifetime of the object

* update docs

components/interrupt/example/main/interrupt_example.cpp

@@ -126,6 +126,11 @@ extern "C" void app_main(void) {
     logger.info("Instantaneous state of pins: {}", active_states);
 
     std::this_thread::sleep_for(2s);
+
+    // print out the minimum number of spaces in the interrupt queue over the
+    // last 2 seconds
+    auto min_queue_size = interrupt.get_min_queue_size();
+    logger.info("Minimum queue size over last 4 seconds: {}", min_queue_size);
   }
 
 #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 2, 0)

components/interrupt/include/interrupt.hpp

@@ -135,6 +135,7 @@ class Interrupt : public BaseComponent {
   explicit Interrupt(const Config &config)
       : BaseComponent("Interrupt", config.log_level)
       , queue_(xQueueCreate(config.event_queue_size, sizeof(EventData)))
+      , min_queue_size_(config.event_queue_size)
       , interrupts_(config.interrupts) {
     // create the event queue
     if (!queue_) {
@@ -188,6 +189,18 @@ class Interrupt : public BaseComponent {
     }
   }
 
+  /// \brief Get the minimum number of free spaces in the queue
+  /// \return The minimum number of free spaces in the queue
+  /// \details This will return the minimum number of free spaces in the queue
+  ///          Over the lifetime of the object. This can be used to determine if
+  ///          the queue size is too small for the number of interrupts that are
+  ///          being received. It may also help indicate if the interrupt task
+  ///          priority is too low, preventing the queue from being serviced.
+  ///          Finally, it may also help to indicate if additional filtering may
+  ///          be needed on the interrupt line (either using the FilterType or
+  ///          with hardware filtering).
+  size_t get_min_queue_size() const { return min_queue_size_; }
+
   /// \brief Add an interrupt to the interrupt handler
   /// \param interrupt The interrupt to add
   void add_interrupt(const PinConfig &interrupt) {
@@ -262,6 +275,11 @@ class Interrupt : public BaseComponent {
 
   bool task_callback(std::mutex &m, std::condition_variable &cv, bool &task_notified) {
     EventData event_data;
+    // record the min number of free spaces in the queue
+    size_t free_spaces = uxQueueSpacesAvailable(queue_);
+    if (free_spaces < min_queue_size_) {
+      min_queue_size_ = free_spaces;
+    }
     if (xQueueReceive(queue_, &event_data, portMAX_DELAY)) {
       if (event_data.gpio_num == -1) {
         // we received a stop event, so return true to stop the task
@@ -370,6 +388,7 @@ class Interrupt : public BaseComponent {
   static bool ISR_SERVICE_INSTALLED;
 
   QueueHandle_t queue_{nullptr};
+  std::atomic<size_t> min_queue_size_{0};
   std::recursive_mutex interrupt_mutex_;
   std::vector<PinConfig> interrupts_;
   std::vector<HandlerArgs *> handler_args_;