/** * @file include/ActivMiddleware/ActivBase/MessageRateThrottler.h * * @brief Header file for the message rate throttler class. */ #if (!defined ACTIV_BASE_MESSAGE_RATE_THROTTLER_H) #define ACTIV_BASE_MESSAGE_RATE_THROTTLER_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/CompartmentalizedMessageRateThrottler.h" #include ACTIV_BOOST_INCLUDE(scoped_ptr.hpp) //! Activ namespace. namespace Activ { class IMutex; // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Message rate throttler class. * * This class should be used when wishing to throttle a message rate, and only sleep when it is not presently possible to send. */ class MessageRateThrottler { public: /** * @brief Constructor. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param shouldCreateMutex indicates whether a mutex should be created. */ ACTIV_BASE_API MessageRateThrottler(const size_t messagesPerSecond = 0, const bool shouldCreateMutex = false); /** * @brief Constructor. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLength the period length (in milliseconds) to throttle over. Must be a factor of 1000. * @param shouldCreateMutex indicates whether a mutex should be created. * * @throw StatusCodeException */ ACTIV_BASE_API MessageRateThrottler(const size_t messagesPerSecond, const size_t periodLength, const bool shouldCreateMutex = false); /** * @brief Destructor. */ ACTIV_BASE_API ~MessageRateThrottler(); /** * @brief Initialize. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * * @retval STATUS_CODE_SUCCESS */ ACTIV_BASE_API StatusCode Initialize(const size_t messagesPerSecond); /** * @brief Initialize. * * @param messagesPerSecond the message rate per second, or 0 for no throttle. * @param periodLength the period length (in milliseconds) to throttle over. Must be a factor of 1000. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_INVALID_PARAMETER */ ACTIV_BASE_API StatusCode Initialize(const size_t messagesPerSecond, const size_t periodLength); /** * @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 size_t GetPeriodLength() const; /** * @brief Reset. */ ACTIV_BASE_API void Reset(); /** * @brief Run the throttler. * * May suspend the calling thread for a period of time in order to throttle. */ ACTIV_BASE_API void Suspend(); private: Boost::scoped_ptr m_pMutex; CompartmentalizedMessageRateThrottler m_compartmentalizedMessageRateThrottler; }; } // namespace Activ #endif // (!defined ACTIV_BASE_MESSAGE_RATE_THROTTLER_H)