219 lines
6.5 KiB
C++
219 lines
6.5 KiB
C++
/**
|
|
* @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<PeriodInfo> 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)
|