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
@@ -90,7 +93,8 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
 #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
@@ -121,8 +125,21 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
      *  for threads scheduling.
      *
      */
+    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 +169,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
 };
 

drivers/source/Ticker.cpp

@@ -18,60 +18,69 @@
 
 #include "drivers/TimerEvent.h"
 #include "hal/ticker_api.h"
+#include "platform/CriticalSectionLock.h"
 #include "platform/mbed_critical.h"
 #include "platform/mbed_power_mgmt.h"
 
 namespace mbed {
 
-Ticker::Ticker() : TimerEvent(), _delay(0), _lock_deepsleep(true)
+Ticker::Ticker() : TimerEvent(), _lock_deepsleep(true)
 {
 }
 
 // When low power ticker is in use, then do not disable deep sleep.
-Ticker::Ticker(const ticker_data_t *data) : TimerEvent(data), _delay(0), _lock_deepsleep(!data->interface->runs_in_deep_sleep)
+Ticker::Ticker(const ticker_data_t *data) : TimerEvent(data),  _lock_deepsleep(!data->interface->runs_in_deep_sleep)
 {
 }
 
 void Ticker::detach()
 {
-    core_util_critical_section_enter();
+    CriticalSectionLock lock;
     remove();
     // unlocked only if we were attached (we locked it) and this is not low power ticker
     if (_function && _lock_deepsleep) {
         sleep_manager_unlock_deep_sleep();
     }
 
     _function = 0;
-    core_util_critical_section_exit();
 }
 
-void Ticker::setup(us_timestamp_t t)
+void Ticker::setup(TickerClock::duration t)
 {
-    core_util_critical_section_enter();
+    CriticalSectionLock lock;
     remove();
     _delay = t;
-    insert_absolute(_delay + ticker_read_us(_ticker_data));
-    core_util_critical_section_exit();
+    insert_absolute(_ticker_data.now() + _delay);
 }
 
 void Ticker::handler()
 {
-    insert_absolute(event.timestamp + _delay);
+    insert_absolute(get_time_point(event) + _delay);
     if (_function) {
         _function();
     }
 }
 
-void Ticker::attach_us(Callback<void()> func, us_timestamp_t t)
+void Ticker::attach(Callback<void()> func, TickerClock::duration t)
 {
-    core_util_critical_section_enter();
+    CriticalSectionLock lock;
     // lock only for the initial callback setup and this is not low power ticker
     if (!_function && _lock_deepsleep) {
         sleep_manager_lock_deep_sleep();
     }
     _function = func;
     setup(t);
-    core_util_critical_section_exit();
+}
+
+void Ticker::attach_us(Callback<void()> func, us_timestamp_t t)
+{
+    CriticalSectionLock lock;
+    // lock only for the initial callback setup and this is not low power ticker
+    if (!_function && _lock_deepsleep) {
+        sleep_manager_lock_deep_sleep();
+    }
+    _function = func;
+    setup(TickerClock::duration(t));
 }
 
 } // namespace mbed