Update Timer and Task Implementation and add some new example / tests.

components/task/example/main/task_example.cpp

@@ -284,6 +284,52 @@ extern "C" void app_main(void) {
   test_duration = std::chrono::duration<float>(test_end - test_start).count();
   fmt::print("Test ran for {:.03f} seconds\n", test_duration);
 
+  /**
+   *   Show an example of the task auto-stopping itself from within the task
+   *   callback function and then starting it again.
+   */
+  test_start = std::chrono::high_resolution_clock::now();
+  {
+    fmt::print("Spawning 1 task for {} seconds!\n", num_seconds_to_run);
+    //! [Task Request Stop Then Restart example]
+    auto task_fn = [&num_seconds_to_run](std::mutex &m, std::condition_variable &cv) {
+      static auto begin = std::chrono::high_resolution_clock::now();
+      auto now = std::chrono::high_resolution_clock::now();
+      auto elapsed = std::chrono::duration<float>(now - begin).count();
+      if (elapsed > num_seconds_to_run) {
+        static int num_times_run{0};
+        fmt::print("Task stopping early after {} runs!\n", ++num_times_run);
+        // we've gone long enough, time to stop our task!
+        return true;
+      }
+      // NOTE: sleeping in this way allows the sleep to exit early when the
+      // task is being stopped / destroyed
+      {
+        std::unique_lock<std::mutex> lk(m);
+        cv.wait_for(lk, 10ms);
+      }
+      // we don't want to stop yet, so return false
+      return false;
+    };
+    auto task = espp::Task({.name = "AutoStop Task",
+                            .callback = task_fn,
+                            .log_level = espp::Logger::Verbosity::DEBUG});
+    task.start();
+    while (task.is_started()) {
+      std::this_thread::sleep_for(10ms);
+    }
+    // restart the task without explicitly cancelling it
+    fmt::print("Restarting task...\n");
+    task.start();
+    while (task.is_started()) {
+      std::this_thread::sleep_for(10ms);
+    }
+    //! [Task Request Stop Then Restart example]
+  }
+  test_end = std::chrono::high_resolution_clock::now();
+  test_duration = std::chrono::duration<float>(test_end - test_start).count();
+  fmt::print("Test ran for {:.03f} seconds\n", test_duration);
+
   fmt::print("Task example complete!\n");
 
   while (true) {

components/task/include/task.hpp

@@ -193,6 +193,10 @@ class Task {
     }
 #endif
 
+    if (thread_.joinable()) {
+      thread_.join();
+    }
+
     // set the atomic so that when the thread starts it won't immediately
     // exit.
     started_ = true;

components/timer/example/main/timer_example.cpp

@@ -111,6 +111,29 @@ extern "C" void app_main(void) {
     std::this_thread::sleep_for(num_seconds_to_run * 1s);
   }
 
+  // oneshot timer example cancel itself then start it again with delay
+  {
+    logger.info("[{:.3f}] Starting oneshot timer cancel itself then restart example", elapsed());
+    //! [timer oneshot restart example]
+    auto timer_fn = []() {
+      static size_t iterations{0};
+      fmt::print("[{:.3f}] #iterations = {}\n", elapsed(), iterations);
+      iterations++;
+      // we don't want to stop, so return false
+      return true;
+    };
+    auto timer = espp::Timer({.name = "Timer 1",
+                              .period = 0ms, // one shot timer
+                              .delay = 500ms,
+                              .callback = timer_fn,
+                              .log_level = espp::Logger::Verbosity::DEBUG});
+    std::this_thread::sleep_for(2s);
+    timer.cancel();  // it will have already been cancelled by here, but this should be harmless
+    timer.start(1s); // restart the timer with a 1 second delay
+    //! [timer oneshot restart example]
+    std::this_thread::sleep_for(num_seconds_to_run * 1s);
+  }
+
   logger.info("Test ran for {:.03f} seconds", elapsed());
 
   logger.info("Example complete!");

components/timer/include/timer.hpp

@@ -43,6 +43,8 @@ namespace espp {
 /// \snippet timer_example.cpp timer oneshot example
 /// \section timer_ex4 Timer Cancel Itself Example
 /// \snippet timer_example.cpp timer cancel itself example
+/// \section timer_ex5 Oneshot Timer Cancel Itself Then Start again with Delay Example
+/// \snippet timer_example.cpp timer oneshot restart example
 class Timer {
 public:
   typedef std::function<bool()>
@@ -74,12 +76,13 @@ class Timer {
                                              .level = config.log_level}) {
     // make the task
     task_ = espp::Task::make_unique({
-        .name = config.name,
+        .name = std::string(config.name) + "_task",
         .callback = std::bind(&Timer::timer_callback_fn, this, std::placeholders::_1,
                               std::placeholders::_2),
         .stack_size_bytes = config.stack_size_bytes,
         .priority = config.priority,
         .core_id = config.core_id,
+        .log_level = config.log_level,
     });
     period_float = std::chrono::duration<float>(period_).count();
     delay_float = std::chrono::duration<float>(delay_).count();
@@ -136,34 +139,40 @@ class Timer {
 
 protected:
   bool timer_callback_fn(std::mutex &m, std::condition_variable &cv) {
+    logger_.debug("callback entered");
     if (!callback_) {
       // stop the timer, the callback is null
       return true;
     }
     // initial delay, if any - this is only used the first time the timer
     // runs
-    if (delay_.count() > 0) {
+    if (delay_float > 0) {
+      auto start = std::chrono::steady_clock::now();
       logger_.debug("waiting for delay {:.3f} s", delay_float);
       std::unique_lock<std::mutex> lock(m);
-      auto cv_retval = cv.wait_for(lock, delay_);
-      // now set the delay to 0
-      delay_ = std::chrono::microseconds(0);
+      auto cv_retval = cv.wait_until(lock, start + delay_);
       if (cv_retval == std::cv_status::no_timeout) {
         // if there was no timeout, then we were notified, which means that the timer
         // was canceled while waiting for the delay, so we should go ahead and return
+        logger_.debug("delay canceled, stopping");
         return true;
       }
+      // now set the delay to 0
+      delay_ = std::chrono::microseconds(0);
+      delay_float = 0;
     }
     // now run the callback
     auto start = std::chrono::steady_clock::now();
+    logger_.debug("running callback");
     bool requested_stop = callback_();
-    if (requested_stop || period_.count() <= 0) {
+    if (requested_stop || period_float <= 0) {
       // stop the timer if requested or if the period is <= 0
+      logger_.debug("callback requested stop or period is <= 0, stopping");
       return true;
     }
     auto end = std::chrono::steady_clock::now();
     float elapsed = std::chrono::duration<float>(end - start).count();
-    if (elapsed > period_.count()) {
+    if (elapsed > period_float) {
       // if the callback took longer than the period, then we should just
       // return and run the callback again immediately
       logger_.warn_rate_limited("callback took longer ({:.3f} s) than period ({:.3f} s)", elapsed,

docs/adc/adc_types.html

@@ -145,7 +145,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADC Types</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/adc_types.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -162,7 +162,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/adc/include/adc_types.hpp">components/adc/include/adc_types.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/43b9241/components/adc/include/adc_types.hpp">components/adc/include/adc_types.hpp</a></p></li>
 </ul>
 </section>
 </section>

docs/adc/ads1x15.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADS1x15 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/ads1x15.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/ads1x15.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -163,7 +163,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/ads1x15/include/ads1x15.hpp">components/ads1x15/include/ads1x15.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/ads1x15/include/ads1x15.hpp">components/ads1x15/include/ads1x15.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/ads7138.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>ADS7138 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/ads7138.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/ads7138.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -168,7 +168,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/ads7138/include/ads7138.hpp">components/ads7138/include/ads7138.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/ads7138/include/ads7138.hpp">components/ads7138/include/ads7138.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/continuous_adc.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>Continuous ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/continuous_adc.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/continuous_adc.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -168,7 +168,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/adc/include/continuous_adc.hpp">components/adc/include/continuous_adc.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/adc/include/continuous_adc.hpp">components/adc/include/continuous_adc.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/index.html

@@ -138,7 +138,7 @@
       <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
       <li>ADC APIs</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/index.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/index.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>

docs/adc/oneshot_adc.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>Oneshot ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/oneshot_adc.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/oneshot_adc.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -167,7 +167,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/adc/include/oneshot_adc.hpp">components/adc/include/oneshot_adc.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/adc/include/oneshot_adc.hpp">components/adc/include/oneshot_adc.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/adc/tla2528.html

@@ -146,7 +146,7 @@
           <li><a href="index.html">ADC APIs</a> &raquo;</li>
       <li>TLA2528 I2C ADC</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/adc/tla2528.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/adc/tla2528.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -168,7 +168,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/tla2528/include/tla2528.hpp">components/tla2528/include/tla2528.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/tla2528/include/tla2528.hpp">components/tla2528/include/tla2528.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/bldc/bldc_driver.html

@@ -142,7 +142,7 @@
           <li><a href="index.html">BLDC APIs</a> &raquo;</li>
       <li>BLDC Driver</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/bldc/bldc_driver.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/bldc/bldc_driver.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -159,7 +159,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/bldc_driver/include/bldc_driver.hpp">components/bldc_driver/include/bldc_driver.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/bldc_driver/include/bldc_driver.hpp">components/bldc_driver/include/bldc_driver.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">

docs/bldc/bldc_motor.html

@@ -144,7 +144,7 @@
           <li><a href="index.html">BLDC APIs</a> &raquo;</li>
       <li>BLDC Motor</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/bldc/bldc_motor.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/bldc/bldc_motor.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -175,7 +175,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/bldc_motor/include/bldc_motor.hpp">components/bldc_motor/include/bldc_motor.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/bldc_motor/include/bldc_motor.hpp">components/bldc_motor/include/bldc_motor.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">
@@ -568,13 +568,13 @@ <h4>Example Usage<a class="headerlink" href="#classespp_1_1_bldc_motor_1bldc_mot
 <section id="id1">
 <h3>Header File<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/bldc_motor/include/bldc_types.hpp">components/bldc_motor/include/bldc_types.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/bldc_motor/include/bldc_types.hpp">components/bldc_motor/include/bldc_types.hpp</a></p></li>
 </ul>
 </section>
 <section id="id2">
 <h3>Header File<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/bldc_motor/include/sensor_direction.hpp">components/bldc_motor/include/sensor_direction.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/bldc_motor/include/sensor_direction.hpp">components/bldc_motor/include/sensor_direction.hpp</a></p></li>
 </ul>
 </section>
 </section>

docs/bldc/index.html

@@ -134,7 +134,7 @@
       <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
       <li>BLDC APIs</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/bldc/index.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/bldc/index.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>

docs/button.html

@@ -137,7 +137,7 @@
       <li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
       <li>Button APIs</li>
       <li class="wy-breadcrumbs-aside">
-              <a href="https://github.com/esp-cpp/espp/blob/28308cc/docs/en/button.rst" class="fa fa-github"> Edit on GitHub</a>
+              <a href="https://github.com/esp-cpp/espp/blob/83311f9/docs/en/button.rst" class="fa fa-github"> Edit on GitHub</a>
       </li>
   </ul>
   <hr/>
@@ -163,7 +163,7 @@ <h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to
 <section id="header-file">
 <h3>Header File<a class="headerlink" href="#header-file" title="Permalink to this headline"></a></h3>
 <ul class="simple">
-<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/28308cc/components/button/include/button.hpp">components/button/include/button.hpp</a></p></li>
+<li><p><a class="reference external" href="https://github.com/esp-cpp/espp/blob/83311f9/components/button/include/button.hpp">components/button/include/button.hpp</a></p></li>
 </ul>
 </section>
 <section id="classes">