ahoy/src/utils/timemonitor.h

//-----------------------------------------------------------
// You69Man, 2023
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// version 2 as published by the Free Software Foundation.
//-----------------------------------------------------------

/**
 * @file timemonitor.h
 *
 * Class declaration for TimeMonitor
 */

#ifndef __TIMEMONITOR_H__
#define __TIMEMONITOR_H__

#include <Arduino.h>

class TimeMonitor {
    public:
        /**
         * A constructor for creating a TimeMonitor object
         */
        TimeMonitor() {}

        /**
         * A constructor for initializing a TimeMonitor object
         * @param timeout timeout in ms
         * @param start   (optional) if true, start TimeMonitor immediately
         */
        explicit TimeMonitor(uint32_t timeout, bool start = false) {
            if (start)
                startTimeMonitor(timeout);
            else
                configureTimeMonitor(timeout);
        }

        /**
         * Start the TimeMonitor with new timeout configuration
         * @param timeout timout in ms
         */
        void startTimeMonitor(uint32_t timeout) {
            mStartTime = millis();
            mTimeout = timeout;
            mStarted = true;
        }

        /**
         * Restart the TimeMonitor with already set timeout configuration
         * @note a timeout has to be set before, no need to call
         *       'startTimeMonitor' before
         */
        void reStartTimeMonitor(void) {
            mStartTime = millis();
            mStarted = true;
        }

        /**
         * Configure the TimeMonitor to new timeout configuration
         * @param timeout timeout in ms
         * @note This doesn't restart an already running TimeMonitor.
         *       If timer is already running and new timeout is longer that current timeout runtime of the running timer is expanded
         *       If timer is already running and new timeout is shorter that current timeout this can immediately lead to a timeout
         */
        void configureTimeMonitor(uint32_t timeout) {
            mTimeout = timeout;
        }

        /**
         * Stop the TimeMonitor
         */
        void stopTimeMonitor(void) {
            mStarted = false;
        }

        /**
         * Get timeout status of the TimeMonitor
         * @return bool
         *         true:  TimeMonitor already timed out
         *         false: TimeMonitor still in time or TimeMonitor was stopped
         */
        bool isTimeout(void) const {
            if ((mStarted) && ((millis() - mStartTime) >= mTimeout))
                return true;
            else
                return false;
        }

        /**
         * Get timeout configuration of the TimeMonitor
         * @return uint32_t timeout value in ms
         */
        uint32_t getTimeout(void) const {
            return mTimeout;
        }

        /**
         * Get residual time of the TimeMonitor until timeout
         * @return uint32_t residual time until timeout in ms
         * @note   in case of a stopped TimeMonitor residual time is always 0xFFFFFFFFUL
         *         in case of a timed out TimeMonitor residual time is always 0UL (zero)
         */
        uint32_t getResidualTime(void) const {
            uint32_t delayed =  millis() - mStartTime;
            return(mStarted ? (delayed < mTimeout ? (mTimeout - delayed) : 0UL) : 0xFFFFFFFFUL);
        }

        /**
         * Get overall run time of the TimeMonitor
         * @return uint32_t residual time until timeout in ms
         * @note   in case of a stopped TimeMonitor residual time is always 0xFFFFFFFFUL
         *         in case of a timed out TimeMonitor residual time is always 0UL (zero)
         */
        uint32_t getRunTime(void) const {
            return(mStarted ? millis() - mStartTime : 0UL);
        }

    private:
        uint32_t mStartTime = 0UL;   // start time of the TimeMonitor
        uint32_t mTimeout   = 0UL;   // timeout configuration of the TimeMonitor
        bool     mStarted   = false; // start/stop state of the TimeMonitor
};

#endif