Add Chrono support to Ticker et al

Author: kjbracey

drivers/Ticker.h

@@ -17,14 +17,17 @@
 #ifndef MBED_TICKER_H
 #define MBED_TICKER_H
 
+#include <chrono>
 #include <mstd_utility>
+#include "drivers/TickerClock.h"
 #include "drivers/TimerEvent.h"
 #include "platform/Callback.h"
 #include "platform/mbed_toolchain.h"
 #include "platform/NonCopyable.h"
 #include "hal/lp_ticker_api.h"
 
 namespace mbed {
+
 /**
  * \defgroup drivers_Ticker Ticker class
  * \ingroup drivers-public-api-ticker
@@ -42,6 +45,7 @@ namespace mbed {
  * // Toggle the blinking LED after 5 seconds
  *
  * #include "mbed.h"
+ * using namespace std::chrono;
  *
  * Ticker timer;
  * DigitalOut led1(LED1);
@@ -54,14 +58,14 @@ namespace mbed {
  * }
  *
  * int main() {
- *     timer.attach(&attime, 5);
+ *     timer.attach(&attime, 5us);
  *     while(1) {
  *         if(flip == 0) {
  *             led1 = !led1;
  *         } else {
  *             led2 = !led2;
  *         }
- *         wait(0.2);
+ *         ThisThread::sleep_for(200ms);
  *     }
  * }
  * @endcode
@@ -82,15 +86,19 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
      *  possible given attach_us() expects an integer value for the callback interval.
      *  @param func pointer to the function to be called
      *  @param t the time between calls in seconds
+     *  @deprecated Pass a chrono duration, not a float second count. For example use `10ms` rather than `0.01f`.
      */
 #if defined(__ICCARM__)
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not a float second count. For example use `10ms` rather than `0.01f`.")
     MBED_FORCEINLINE template <typename F>
 #else
     template <typename F> MBED_FORCEINLINE
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not a float second count. For example use `10ms` rather than `0.01f`.")
 #endif
     void attach(F &&func, float t)
     {
-        attach_us(std::forward<F>(func), t * 1000000.0f);
+        auto float_interval = std::chrono::duration<float>(t);
+        attach(std::forward<F>(func), std::chrono::duration_cast<std::chrono::microseconds>(float_interval));
     }
 
     /** Attach a member function to be called by the Ticker, specifying the interval in seconds
@@ -119,10 +127,24 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
      *  @note setting @a t to a value shorter than it takes to process the ticker callback
      *  causes the system to hang. Ticker callback is called constantly with no time
      *  for threads scheduling.
+     *  @deprecated Pass a chrono duration, not an integer microsecond count. For example use `10ms` rather than `10000`.
      *
      */
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer microsecond count. For example use `10ms` rather than `10000`.")
     void attach_us(Callback<void()> func, us_timestamp_t t);
 
+    /** Attach a function to be called by the Ticker, specifying the interval in microseconds
+     *
+     *  @param func pointer to the function to be called
+     *  @param t the time between calls in micro-seconds
+     *
+     *  @note setting @a t to a value shorter than it takes to process the ticker callback
+     *  causes the system to hang. Ticker callback is called constantly with no time
+     *  for threads scheduling.
+     *
+     */
+    void attach(Callback<void()> func, TickerClock::duration t);
+
     /** Attach a member function to be called by the Ticker, specifying the interval in microseconds
      *
      *  @param obj pointer to the object to call the member function on
@@ -152,11 +174,10 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
 
 #if !defined(DOXYGEN_ONLY)
 protected:
-    void setup(us_timestamp_t t);
+    void setup(TickerClock::duration t);
     virtual void handler();
 
-protected:
-    us_timestamp_t         _delay;  /**< Time delay (in microseconds) for resetting the multishot callback. */
+    TickerClock::duration  _delay;  /**< Time delay (in microseconds) for resetting the multishot callback. */
     Callback<void()>    _function;  /**< Callback. */
     bool          _lock_deepsleep;  /**< Flag which indicates if deep sleep should be disabled. */
 #endif

drivers/TickerClock.h

@@ -0,0 +1,87 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2019 ARM Limited
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#ifndef MBED_TICKERCLOCK_H
+#define MBED_TICKERCLOCK_H
+
+#include <chrono>
+#include "hal/ticker_api.h"
+
+namespace mbed {
+/**
+ * \defgroup drivers_TickerClock TickerClock class
+ * \ingroup drivers-public-api-ticker
+ * @{
+ */
+
+/**
+ * A partial implementation of a C++11 Clock representing a HAL ticker.
+ *
+ * This class allows us to create chrono time_points for objects like Timer,
+ * with the limitation that the tickers are not singletons. This means:
+ *
+ * * the now() function is not static - this will limit
+ *   use with some algorithms,
+ * * there is no distinction between time_points for different
+ *   tickers
+ *
+ * This "pseudo-Clock" approach has been endorsed by Howard Hinnant
+ * (designer of Chrono) here:
+ * https://stackoverflow.com/questions/56400313/why-does-the-c-standard-require-the-clocknow-function-to-be-static
+ *
+ * TickerClock::time_point values should only be used with mbed APIs specifically taking
+ * them, not passed to generic templated chrono algorithms, and it is up to the user to use them
+ * in conjunction with the correct TickerClock.
+ *
+ * operators for `->` and conversion to `ticker_data_t *` are provided allowing
+ * TickerClock to be easily substituted in place of a `ticker_data_t *`.
+ */
+struct TickerClock {
+    /** Construct a TickerClock referring to a ticker_data_t */
+    constexpr TickerClock(const ticker_data_t *ticker) : _ticker(ticker)
+    {
+    }
+    /* duration is C++11 standard microseconds, so representation will be 64-bit signed integer */
+    using duration = std::chrono::microseconds;
+    using rep = duration::rep;
+    using period = duration::period;
+    using time_point = std::chrono::time_point<TickerClock>;
+    static const bool is_steady = false;
+    time_point now() const
+    {
+        return time_point(duration(ticker_read_us(_ticker)));
+    }
+    constexpr const ticker_data_t *operator->() const
+    {
+        return _ticker;
+    }
+    constexpr operator const ticker_data_t *() const
+    {
+        return _ticker;
+    }
+private:
+    const ticker_data_t *_ticker;
+};
+
+inline TickerClock::time_point get_time_point(const ticker_event_t &event)
+{
+    return TickerClock::time_point(TickerClock::duration(event.timestamp));
+}
+
+/** @}*/
+
+}
+#endif /* MBED_TICKERCLOCK_H */

drivers/Timer.h

@@ -18,7 +18,7 @@
 #define MBED_TIMER_H
 
 #include "platform/platform.h"
-#include "hal/ticker_api.h"
+#include "drivers/TickerClock.h"
 #include "platform/NonCopyable.h"
 
 namespace mbed {
@@ -58,6 +58,10 @@ class Timer : private NonCopyable<Timer> {
     Timer(const ticker_data_t *data);
     ~Timer();
 
+    using period = TickerClock::period;
+    using duration = TickerClock::duration;
+    using rep = TickerClock::rep;
+
     /** Start the timer
      */
     void start();
@@ -76,6 +80,7 @@ class Timer : private NonCopyable<Timer> {
      *
      *  @returns    Time passed in seconds
      */
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Floating point operators should normally be avoided for code size. If really needed, you can use `duration<float>(read_duration()).count()`")
     float read();
 
     /** Get the time passed in milliseconds
@@ -92,21 +97,27 @@ class Timer : private NonCopyable<Timer> {
 
     /** An operator shorthand for read()
      */
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Floating point operators should normally be avoided for code size. If really needed, you can use `duration<float>(read_duration()).count()`")
     operator float();
 
     /** Get in a high resolution type the time passed in microseconds.
      *  Returns a 64 bit integer.
      */
     us_timestamp_t read_high_resolution_us();
 
+    /** Get in a high resolution type the time passed in microseconds.
+     *  Returns a 64 bit integer chrono duration.
+     */
+    duration read_duration();
+
 #if !defined(DOXYGEN_ONLY)
 protected:
-    us_timestamp_t slicetime();
-    int _running;            // whether the timer is running
-    us_timestamp_t _start;   // the start time of the latest slice
-    us_timestamp_t _time;    // any accumulated time from previous slices
-    const ticker_data_t *_ticker_data;
+    duration slicetime();
+    TickerClock::time_point _start;   // the start time of the latest slice
+    duration _time;    // any accumulated time from previous slices
+    TickerClock _ticker_data;
     bool _lock_deepsleep;    // flag that indicates if deep sleep should be disabled
+    bool _running = false;   // whether the timer is running
 };
 #endif
 

drivers/TimerEvent.h

@@ -19,8 +19,10 @@
 
 #include "hal/ticker_api.h"
 #include "platform/NonCopyable.h"
+#include "drivers/TickerClock.h"
 
 namespace mbed {
+
 /**
  * \defgroup drivers_TimerEvent TimerEvent class
  * \ingroup drivers-public-api-ticker
@@ -62,25 +64,57 @@ class TimerEvent : private NonCopyable<TimerEvent> {
      * Ticker's present timestamp is used for reference. For timestamps
      * from the past the event is scheduled after ticker's overflow.
      * For reference @see convert_timestamp
+     *
+     * @deprecated use `insert(TickerClock::duration timestamp)`
      */
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer microsecond count. For example use `5ms` rather than `5000`.")
     void insert(timestamp_t timestamp);
 
+    /** Set relative timestamp of the internal event.
+     * @param   timestamp   event's us timestamp
+     *
+     * @warning
+     * Do not insert more than one timestamp.
+     * The same @a event object is used for every @a insert/insert_absolute call.
+     *
+     * @warning
+     * Ticker's present timestamp is used for reference. For timestamps
+     * from the past the event is scheduled after ticker's overflow.
+     * For reference @see convert_timestamp
+     */
+    void insert(TickerClock::duration timestamp);
+
     /** Set absolute timestamp of the internal event.
      * @param   timestamp   event's us timestamp
      *
      * @warning
      * Do not insert more than one timestamp.
      * The same @a event object is used for every @a insert/insert_absolute call.
+     *
+     * @deprecated use `insert_absolute(TickerClock::time_point timestamp)`
      */
+    MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer microsecond count. For example use `_ticker_data.now() + 5ms` rather than `ticker_read_us(_ticker_data) + 5000`.")
     void insert_absolute(us_timestamp_t timestamp);
 
+    /** Set absolute timestamp of the internal event.
+     * @param   timestamp   event's us timestamp
+     *
+     * @note despite being an absolute time, this API has to use a chrono duration
+     * rather than a chrono time_point
+     *
+     * @warning
+     * Do not insert more than one timestamp.
+     * The same @a event object is used for every @a insert/insert_absolute call.
+     */
+    void insert_absolute(TickerClock::time_point timestamp);
+
     /** Remove timestamp.
      */
     void remove();
 
     ticker_event_t event;
 
-    const ticker_data_t *_ticker_data;
+    TickerClock _ticker_data;
 #endif
 };