Files

110 lines
2.9 KiB
C++

/**
* @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<IMutex> m_pMutex;
CompartmentalizedMessageRateThrottler m_compartmentalizedMessageRateThrottler;
};
} // namespace Activ
#endif // (!defined ACTIV_BASE_MESSAGE_RATE_THROTTLER_H)