PolledTimer.h

Go to the documentation of this file.

/****
 * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
 * Created 2015 by Skurydin Alexey
 * http://github.com/SmingHub/Sming
 * All files of the Sming Core are provided under the LGPL v3 license.
 *
 * PolledTimer.h - template class to assist with measurement of elapsed time periods
 *
 * @author mikee47 <mike@sillyhouse.net>
 *
 * Developed from the excellent esp8266 Arduino project's PolledTimer.h
 *  Copyright (c) 2018 Daniel Salazar. All rights reserved.
 *  https://github.com/esp8266/Arduino/blob/master/cores/esp8266/PolledTimeout.h
 *
 * Generally Sming uses timer callbacks but for some applications a polled timer
 * is more appropriate, especially if timer intervals are less than few hundred
 * microseconds, or even in nanoseconds.
 *
 * Here we have the `PolledTimer` template class. See `Platform/Timers.h` for implementations.
 *
 ****/

#pragma once

#include <cstdint>
#include <esp_attr.h>
#include <sming_attr.h>
#include <Platform/Clocks.h>

#ifndef POLLED_TIMER_MARGIN_US
#define POLLED_TIMER_MARGIN_US 250000
#endif

namespace PolledTimer
{
template <class Clock, NanoTime::Unit unit_, bool IsPeriodic, typename TimeType>
class Timer : public NanoTime::TimeSource<Clock, unit_, TimeType>
{
public:
    static_assert(std::is_unsigned<TimeType>::value == true, "TimeType must be unsigned");

    using TickType = typename Clock::TickType;
    using Clock::ticks;
    using Margin = NanoTime::TimeConst<Clock, NanoTime::Microseconds, POLLED_TIMER_MARGIN_US>;

    static constexpr NanoTime::Unit unit()
    {
        return unit_;
    }

    static constexpr TickType maxInterval()
    {
        return Clock::maxTicks() - Margin::ticks();
    }

    static constexpr Margin margin()
    {
        return Margin();
    }

    IRAM_ATTR Timer(const TimeType& timeInterval = 0)
    {
        reset(timeInterval);
    }

    __forceinline void IRAM_ATTR start()
    {
        startTicks = ticks();
        if(!IsPeriodic) {
            // One-shot timers require manual reset
            hasExpired = false;
        }
    }

    template <uint64_t timeInterval> __forceinline void IRAM_ATTR reset()
    {
        auto ticks = checkTime<timeInterval>();
        resetTicks(ticks);
    }

    template <uint64_t timeInterval> constexpr uint32_t checkTime()
    {
        auto time = this->template timeConst<timeInterval>();
        time.check();
        constexpr auto ticks = time.ticks();
        static_assert(ticks < maxInterval(), "Polled time interval too long");
        return ticks;
    }

    __forceinline bool IRAM_ATTR reset(const TimeType& timeInterval)
    {
        return resetTicks(this->template timeToTicks(timeInterval));
    }

    __forceinline bool IRAM_ATTR resetTicks(const TimeType& interval)
    {
        start();
        this->interval = interval;
        neverExpires = (interval > maxInterval());
        return !neverExpires;
    }

    __forceinline void IRAM_ATTR cancel()
    {
        interval = 1; // Ensure canWait() returns true
        neverExpires = true;
        if(!IsPeriodic) {
            hasExpired = true;
        }
    }

    __forceinline TickType elapsedTicks() const
    {
        return ticks() - startTicks;
    }

    __forceinline NanoTime::Time<TimeType> elapsedTime() const
    {
        return this->template ticksToTime(elapsedTicks());
    }

    __forceinline bool canExpire() const
    {
        return !neverExpires;
    }

    __forceinline bool canWait() const
    {
        return interval != 0;
    }

    __forceinline bool expired()
    {
        return IsPeriodic ? expiredRetrigger() : expiredOneShot();
    }

private:
    bool IRAM_ATTR checkExpired(const TickType& ticks) const
    {
        // canWait() is not checked here
        // returns "can expire" and "time expired"
        return !neverExpires && (TickType(ticks - startTicks) >= interval);
    }

    bool IRAM_ATTR expiredRetrigger()
    {
        if(!canWait()) {
            return true;
        }

        bool result = false;
        TickType current = ticks();
        while(checkExpired(current)) {
            result = true;
            startTicks += interval;
        }

        return result;
    }

    bool IRAM_ATTR expiredOneShot()
    {
        // Remain triggered until manually reset or cancelled
        if(!canWait() || hasExpired) {
            return true;
        }
        hasExpired = checkExpired(ticks());
        return hasExpired;
    }

    TickType startTicks;
    TickType interval;
    bool neverExpires; 
    bool hasExpired;   
};

// Standard timer types
template <typename Clock, NanoTime::Unit unit> using OneShot = Timer<Clock, unit, false, uint32_t>;
template <typename Clock, NanoTime::Unit unit> using Periodic = Timer<Clock, unit, true, uint32_t>;

} // namespace PolledTimer