Metronome.h

Go to the documentation of this file.

#pragma once
 
 
#include <ArmarXCore/core/time/Clock.h>
#include <ArmarXCore/core/time/DateTime.h>
#include <ArmarXCore/core/time/Duration.h>
#include <ArmarXCore/core/time/Frequency.h>
 
namespace armarx::core::time
{
 
    /**
     * @brief Simple rate limiter for use in loops to maintain a certain frequency given a clock.
     *
     * In most cases, it is enough sufficient to construct a rate limiter with a given target
     * duration (or target period). This will then use virtual time. In cases where a specific
     * clock is required, a constructor taking a clock or clock type can be used.
     *
     * Code example:
     *
     * @code
     * using namespace armarx;
     *
     * Metronome m{Frequeny::hertz(100)}; // For a 100Hz loop.
     * while (condition)
     * {
     *     operation();
     *
     *     const Duration waitingTime = m.waitForNextTick();
     *     ARMARX_INFO << "We now waited " << waitingTime << ".";
     * }
     * @endcode
     *
     * Another example with a do-while loop where the metronome must be placed at the top of a loop
     * because of continue etc.:
     *
     * @code
     * using namespace armarx;
     *
     * Metronome m{Frequeny::hertz(100), ClockType::Virtual, Metronome::NextTickMode::tick_immediately}; // For a 100Hz loop.
     * do
     * {
     *     const Duration waitingTime = m.waitForNextTick();  // This will not wait in the first loop iteration.
     *     ARMARX_INFO << "We now waited " << waitingTime << ".";
     *
     *     if (some_continue_condition)
     *     {
     *         continue;
     *     }
     *
     *     operation();
     * }
     * while (condition);
     * @endcode
     */
    class Metronome
    {
 
    public:
        /**
         * @brief Modes that influence how the reset method should function for the next
         * waitForNextTick() method call.
         */
        enum class NextTickMode
        {
            /**
             * If waitForNextTicK() is called shortly after reset() (or any constructor), the
             * metronome will wait for the length of a period.
             */
            wait_for_next_tick,
 
            /**
             * If waitForNextTicK() is called shortly after reset() (or any constructor), the
             * metronome will not wait and continue immediately.  This is useful, if the
             * waitForNextTick() method must be called at the top of the scope of a loop and it is
             * not desired for the metronome to block the first loop iteration.
             */
            tick_immediately
        };
 
        Metronome(const Frequency& targetFrequency,
                  ClockType clockType = ClockType::Virtual,
                  NextTickMode mode = NextTickMode::wait_for_next_tick);
 
        /**
         * @brief Constructs a new rate limiter with given target period and clock type.
         * @param targetPeriod Period to target for in loops etc.
         * @param clockType Type of clock to use to assess time.
         */
        Metronome(const Duration& targetPeriod, ClockType clockType = ClockType::Virtual);
 
        /**
         * @brief Constructs a new rate limiter with given target period and clock.
         * @param targetPeriod Period to target for in loops etc.
         * @param clock Clock to use to assess time.
         */
        Metronome(const Duration& targetPeriod, const Clock& clock);
 
        /**
         * @brief Wait and block until the target period is met.
         * @return The duration the rate limiter waited for. Can be negative if the next deadline
         *         was missed.
         */
        Duration waitForNextTick() const;
 
        /**
         * @brief Resets the rate limiter so that the next targetted time point will be in the
         *        current time plus the target period.
         */
        void reset(NextTickMode mode = NextTickMode::wait_for_next_tick) const;
 
    private:
        /**
         * @brief Clock to use to assess time.
         */
        Clock _clock;
 
        /**
         * @brief Next date/time to target in the next call to wait().
         */
        mutable DateTime _nextCheckpoint;
 
        /**
         * @brief Period to target.
         */
        const Duration _targetPeriod;
    };
 
} // namespace armarx::core::time
 
namespace armarx
{
    using core::time::Metronome;
}