/** * @file include/ActivMiddleware/ActivBase/CompartmentalizedMessageRateThrottler.h * * @brief Header file for the message rate throttler class. */ #if (!defined ACTIV_BASE_COMPARTMENTALIZED_MESSAGE_RATE_THROTTLER_H) #define ACTIV_BASE_COMPARTMENTALIZED_MESSAGE_RATE_THROTTLER_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/IntervalTimer.h" #include "ActivMiddleware/CxxYZ/chrono.h" //! Activ namespace. namespace Activ { /** * @brief Compartmentalized message rate throttler class. * * This class should be used when wishing to throttle a message rate, but do other work than sleep when it is not * presently possible to send. * * For example: * * CompartmentalizedMessageRateThrottler m_compartmentalizedMessageRateThrottler; * ... * while (true) * { * if (0 == m_compartmentalizedMessageRateThrottler.GetInactivityPeriod()) * { * // Send a message. * MyPostMessage(); * m_compartmentalizedMessageRateThrottler.Complete(); * } * else * { * // Do some other work for a while. * ... * } * } */ class CompartmentalizedMessageRateThrottler { public: //! Period length type. typedef CxxYZ::chrono::microseconds PeriodLength; /** * @brief Constructor. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. */ ACTIV_BASE_API CompartmentalizedMessageRateThrottler(const size_t messagesPerSecond); /** * @brief Constructor. * * Deprecated, use the constructor taking a @a PeriodLength instead. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLengthInMs the period length (in milliseconds) to throttle over. * * @throw StatusCodeException */ ACTIV_BASE_API CompartmentalizedMessageRateThrottler(const size_t messagesPerSecond, const size_t periodLengthInMs); /** * @brief Constructor. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLength the period length to throttle over. * @param totalThrottleLength the total throttle length over all periods, must be between 1 and 100 times @a periodLength. * * @throw StatusCodeException */ ACTIV_BASE_API CompartmentalizedMessageRateThrottler(const size_t messagesPerSecond, const PeriodLength periodLength, const PeriodLength totalThrottleLength); /** * @brief Initialize. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * * @retval STATUS_CODE_SUCCESS */ ACTIV_BASE_API const StatusCode Initialize(const size_t messagesPerSecond); /** * @brief Initialize. * * Deprecated, use the method taking a @a PeriodLength instead. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLengthInMs the period length (in milliseconds) to throttle over. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_INVALID_PARAMETER */ ACTIV_BASE_API const StatusCode Initialize(const size_t messagesPerSecond, const size_t periodLengthInMs); /** * @brief Initialize. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLength the period length to throttle over. * @param totalThrottleLength the total throttle length over all periods, must be between 1 and 100 times @a periodLength. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_INVALID_PARAMETER */ ACTIV_BASE_API const StatusCode Initialize(const size_t messagesPerSecond, const PeriodLength periodLength, const PeriodLength totalThrottleLength); /** * @brief Get the message rate. * * @return The message rate in messages per second. */ ACTIV_BASE_API const size_t GetMessageRate() const; /** * @brief Get the period length. * * @return The period length. */ ACTIV_BASE_API const PeriodLength GetPeriodLength() const; /** * @brief Reset. */ ACTIV_BASE_API void Reset(); /** * @brief Can we send a message right now? * * @return 0 if we can send a message right now, else a value representing the time that we can't send a message for. * Can be passed to the Sleep() method if we wish to sleep, rather than doing some other work. */ ACTIV_BASE_API const uint64_t GetInactivityPeriod(); /** * @brief Sleep for some time period. * * @param period as returned by GetInactivityPeriod(), for instance. */ #if (!defined ACTIV_LITE_FRAMEWORK) ACTIV_BASE_API void Sleep(const uint64_t period) const; #endif /** * @brief After getting a 0 return value from GetInactivityPeriod(), and sending a message, * this should be called to update internal state. */ ACTIV_BASE_API void Complete(); /** * @brief Convert a period (in system dependent units) to milliseconds. * * The period will be rounded by to the nearest millisecond. * * @param period as returned by GetInactivityPeriod(). * * @return @a period in milliseconds, rounded up to the nearest millisecond. */ ACTIV_BASE_API const size_t ConvertPeriodToMilliseconds(const uint64_t period) const; private: class PeriodInfo { public: size_t m_idealNumberOfMessages; size_t m_currentNumberOfMessages; size_t m_maxNumberOfMessages; }; typedef std::vector PeriodInfoList; /** * @brief Set current period. * * @param period * @param timeStamp * @param allowedOverrunThisPeriod messages to allow in addition to the ideal in this period. */ void SetPeriod(const size_t period, const uint64_t timeStamp, const size_t allowedOverrunThisPeriod); /** * @brief Move to the next period. */ void SetNextPeriod(); /** * @brief Get the next period given a period index. * * @return New period index. */ size_t GetNextPeriod(const size_t period); static const size_t MILLISECONDS_PER_SECOND = 1000; ///< The number of milliseconds in a second. static const size_t MICROSECONDS_PER_SECOND = 1000000; ///< The number of microseconds in a second. const uint64_t m_intervalTimerFrequency; ///< The IntervalTimer frequency. size_t m_messagesPerSecond; ///< The message rate. uint64_t m_periodTimeStamp; ///< The throttle period in IntervalTimer timestamp units. size_t m_numberOfPeriods; ///< The number of periods. PeriodInfoList m_periodInfoList; size_t m_currentPeriod; ///< Index into m_periodInfoList of current period. size_t m_lastResetPeriod; ///< The last period we reset to after a period of inactivity. uint64_t m_currentPeriodStartTimeStamp; uint64_t m_nextPeriodStartTimeStamp; uint64_t m_nextNextPeriodStartTimeStamp; }; } // namespace Activ #endif // (!defined ACTIV_BASE_COMPARTMENTALIZED_MESSAGE_RATE_THROTTLER_H)