Files
externals/linux/include/ActivMiddleware/ActivBase/CompartmentalizedMessageRateThrottler.h

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)