Files

513 lines
17 KiB
C++

/**
* @file include/ActivMiddleware/ActivFramework/IHeap.h
*
* @brief Header file for abstract heap class.
*/
#if (!defined ACTIV_FRAMEWORK_IHEAP_H)
#define ACTIV_FRAMEWORK_IHEAP_H
#include "ActivMiddleware/ActivFramework/External.h"
#include "ActivMiddleware/ActivBase/IniFileParser.h"
#include "ActivMiddleware/ActivBase/FieldTypes/DateTime.h"
#include "ActivMiddleware/ActivBase/MessageBuilder.h"
#include <vector>
//! Activ namespace.
namespace Activ
{
class ISystem;
class HeapMessage;
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Abstract heap interface class.
*/
class IHeap : private Boost::noncopyable
{
public:
/**
* @brief Heap bucket size information.
*/
class BucketInfo
{
public:
size_t m_messageSize; ///< Size of message body in each message in this bucket.
size_t m_numberOfMessages; ///< Number of messages in this bucket.
};
typedef std::vector<BucketInfo> BucketInfoVector; ///< Bucket info vector type.
/**
* @brief Heap settings.
*/
class Settings
{
public:
/**
* @brief Inter-message padding size.
*/
enum InterMessagePadding
{
INTER_MESSAGE_PADDING_WORD_SIZE, ///< Pad messages in heap by processor word size.
INTER_MESSAGE_PADDING_CACHE_SIZE ///< Pad messages in heap by processor cache line size.
};
//! Default constructor.
ACTIV_FRAMEWORK_API
Settings();
/**
* @brief Constructor.
*
* @param bucketInfoVector
*/
ACTIV_FRAMEWORK_API
Settings(const BucketInfoVector &bucketInfoVector);
/**
* @brief Read setting from an ini-file.
*
* @param sectionIterator
*
* @throw Exception
*/
ACTIV_FRAMEWORK_API
void Read(const IniFileParser::ConstSectionIterator &sectionIterator);
ObjectScope m_objectScope; ///< Default: OBJECT_SCOPE_SYSTEM. System-wide or process-local heap?
/**
* @brief Padding between messages in a heap. Default: INTER_MESSAGE_PADDING_WORD_SIZE.
*/
InterMessagePadding m_interMessagePadding;
/**
* @brief Should memory lock the heap. Default: false. Posix and OBJECT_SCOPE_SYSTEM only.
*/
bool m_shouldMemoryLock;
/**
* @brief Description of buckets to use.
*/
BucketInfoVector m_bucketInfoVector;
/**
* @brief OBJECT_SCOPE_PROCESS only: how much of the heap to pre-allocate, as a percentage of the bucket definitions.
* Default: 0%.
*/
size_t m_preallocationPercent;
/**
* @brief Scale the number of messages in m_bucketInfoVector for thread local buckets, if m_isFastPathGetEnabled is true
* or for the shared buckets if m_isFastPathGetEnabled is false.
* Default: 100%.
*/
size_t m_bucketsScalePercent;
/**
* @brief Enable single-threaded optimization of the GetMessage() methods? In this case, the heap will create
* two sets of buckets. One set of buckets will be of the size defined in m_bucketInfoVector, and will be
* assigned to whichever thread is chosen as the fast-path get thread using the thresholds below. The second
* set of buckets will have the number of messages in them scaled by m_fastPathSharedBucketsScalePercent
* and will be available to satisfy any other thread making a GetMessage() call. Default: false.
*/
bool m_isFastPathGetEnabled;
/**
* @brief Enable single-threaded optimization of the return path? Default: true.
*/
bool m_isFastPathReturnEnabled;
/**
* @brief Scale the number of messages in m_bucketInfoVector for shared buckets, if m_isFastPathGetEnabled is true.
* Default: 15%.
*/
size_t m_fastPathSharedBucketsScalePercent;
/**
* @brief Don't create a scaled bucket smaller than this number of messages (when m_isFastPathGetEnabled is true).
* Default: 10.
*/
size_t m_fastPathMinimumScaledBucketSize;
/**
* @brief Number of get/return operations that must be done before the Heap will attempt to chose the single-threaded
* optimized fast-path thread. If no thread has done m_fastPathThresholdPercent % of the gets/returns after
* 2*m_fastPathThreshold gets/returns, no thread is chosen and all threads will continue to use the slow-path.
* Default: 50000.
*/
size_t m_fastPathThreshold;
/**
* @brief A thread must do this % of the total gets or returns before it will be chosen as the single-threaded
* optimized fast-path thread. Default 90%.
*/
size_t m_fastPathThresholdPercent;
/**
* @brief How empty a thread-local get free-list must be before it replenishes itself from the shared free-lists.
* Default: 60%.
*/
size_t m_fastPathGetMoveFreeListPercent;
/**
* @brief How full a thread-local return free-list must be before it is pushed back to the shared free-lists.
* Default: 10%.
*/
size_t m_fastPathReturnMoveFreeListPercent;
/**
* @brief Whether to enable distribution logging. Default: false (release build), true (debug build). Note will have
* noticeable performance impact.
*/
bool m_isRequestDistributionLoggingEnabled;
/**
* @brief Whether to alert on heap failures. Default: true.
*/
bool m_isAlertingEnabled;
};
/**
* @brief Heap stats.
*/
class Stats
{
public:
/**
* @brief Request distribution stats.
*/
class RequestDistributionStats
{
public:
size_t m_minSize; ///< Minimum size of request.
size_t m_maxSize; ///< Maximum size of request.
size_t m_count; ///< Number of requests >= m_minSize and <= m_maxSize.
};
typedef std::vector<RequestDistributionStats> DistributionVector;
/**
* @brief Individual Bucket stats.
*/
class BucketStats
{
public:
/**
* @brief Default constructor.
*/
ACTIV_FRAMEWORK_API
BucketStats();
BucketInfo m_bucketInfo;
size_t m_numberOfFreeMessages; ///< Number of free messages.
size_t m_lowFreeMessagesInInterval; ///< Lowest number of free messages in log interval.
size_t m_lowFreeMessages; ///< Lowest number of free messages since daily reset.
size_t m_firstRunFails; ///< Number of fails when most ideal sized bucket.
size_t m_secondRunFails; ///< Number of fails when > ideal sized bucket.
};
typedef std::vector<BucketStats> BucketStatsVector;
/**
* @brief List of bucket stats.
*/
class BucketListStats
{
public:
/**
* @brief Default constructor.
*/
ACTIV_FRAMEWORK_API
BucketListStats();
/**
* @brief Get the current free % across all buckets in this list.
*
* @return Current free percentage, or 100 if no messages in this bucket list.
*/
size_t GetCurrentFreePercent() const;
/**
* @brief Get the low free % across all buckets in this list.
*
* @return Low free percentage, or 100 if no messages in this bucket list.
*/
size_t GetLowFreePercent() const;
/**
* @brief Get the low free % across all buckets in this list during the last logging interval.
*
* @return Interval low free percentage, or 100 if no messages in this bucket list.
*/
size_t GetIntervalLowFreePercent() const;
size_t m_numberOfFails; ///< Number of GetMessage() calls failed using this set of buckets.
size_t m_totalNumberOfMessages; ///< Number of messages in total in this set of buckets.
size_t m_totalCurrentFreeMessages; ///< Current free messages across all buckets in this set.
size_t m_totalLowFreeMessagesInInterval; ///< Low of free messages across all buckets in this set in log interval.
size_t m_totalLowFreeMessages; ///< Low of free messages across all buckets in this set since daily reset.
BucketStatsVector m_bucketStatsVector; ///< Individual bucket stats.
};
ACTIV_FRAMEWORK_API
Stats();
/**
* @brief Get the current free % across all buckets.
*
* If the heap has fast-path gets active, the lowest of the shared and fast-path buckets is returned.
*
* @return Current free percentage.
*/
size_t GetCurrentFreePercent() const;
/**
* @brief Get the low free % across all buckets.
*
* If the heap has fast-path gets active, the lowest of the shared and fast-path buckets is returned.
*
* @return Low free percentage.
*/
size_t GetLowFreePercent() const;
/**
* @brief Get the low free % across all buckets during the last logging interval.
*
* If the heap has fast-path gets active, the lowest of the shared and fast-path buckets is returned.
*
* @return Interval low free percentage.
*/
size_t GetIntervalLowFreePercent() const;
// Heap-wide constants.
HeapId m_id;
ProcessId m_creatorProcessId;
String m_name;
size_t m_memoryUsage; ///< Approximate memory usage of this heap.
ObjectScope m_objectScope; ///< Visibility within the system.
// Heap-wide stats.
size_t m_numberOfIdealBucketFails; ///< Number of requests for a message larger than largest bucket size.
size_t m_numberOfTotalFails; ///< Number of GetMessage() requests that have failed in total.
DateTime m_firstFailLocalDateTime; ///< Local date/time of first fail.
DateTime m_lastFailLocalDateTime; ///< Local date/time of last fail.
size_t m_mutexContentionCount; ///< Approx. contentions on the heap's mutex.
// Shared bucket stats.
BucketListStats m_sharedBucketListStats; ///< Shared bucket list stats.
// Fast-path stats.
bool m_isFastPathGetEnabled; ///< Was heap created with m_isFastPathGetEnabled set in Settings?
bool m_isFastPathGetActive; ///< Has a thread been allocated to fast-path gets?
bool m_isFastPathReturnEnabled; ///< Was heap created with m_isFastPathReturnEnabled set in Settings?
bool m_isFastPathReturnActive; ///< Has a thread been allocated to fast-path returns?
String m_fastPathGetThreadName; ///< If active, the thread with fast path gets enabled.
String m_fastPathReturnThreadName; ///< If active, the thread with fast path returns enabled.
BucketListStats m_fastPathBucketListStats; ///< Only relevant if m_isFastPathGetEnabled.
// IHeap::SetRequestDistributionLogging(true) needs to be called for the following to be populated:
size_t m_maxRequestSize; ///< Size of max request.
DistributionVector m_distributionVector; ///< Request stats distribution.
};
/**
* @brief Destructor.
*/
virtual ~IHeap() = 0;
/**
* @brief Get a message or chain of messages from the heap.
*
* @param size the number of bytes the message needs to hold.
* @param heapMessage to receive the allocated message. If message allocation fails, @a heapMessage will not have an
* attached message (i.e. !heapMessage will be true).
*/
virtual void GetMessage(const size_t size, HeapMessage &heapMessage) = 0;
/**
* @brief Get a message or chain of messages from the heap and copy data in.
*
* @param pData pointer to data to copy into the message. Can be null.
* @param dataLength the number of bytes the messages needs to hold and the number of bytes from @a pData copied in.
* @param heapMessage to receive the allocated message. If message allocation or data copy fails, @a heapMessage will not
* have an attached message (i.e. !heapMessage will be true).
*/
void GetMessage(const void *pData, const size_t dataLength, HeapMessage &heapMessage);
/**
* @brief Get a message or chain of messages from the heap and block if the heap is empty.
*
* @param pData pointer to data to copy into the message.
* @param dataLength the number of bytes the messages needs to hold and the number of bytes from @a pData copied in.
* @param timeoutPeriod maximum time to wait for a message allocation to succeed if the heap is empty.
* @param heapMessage to receive the allocated message. If message allocation or data copy fails, @a heapMessage will not
* have an attached message (i.e. !heapMessage will be true).
*/
virtual void GetMessage(const void *pData, const size_t dataLength, const TimeoutPeriod timeoutPeriod,
HeapMessage &heapMessage) = 0;
/**
* @brief Get a message or chain of messages from the heap and copy data in.
*
* @param messageBuilder containing the data to copy in to the message.
* @param heapMessage to receive the allocated message. If message allocation or data copy fails, @a heapMessage will not
* have an attached message (i.e. !heapMessage will be true).
*/
void GetMessage(const MessageBuilder &messageBuilder, HeapMessage &heapMessage);
/**
* @brief Get the name of the heap.
*
* @return A string object containing the name of the heap.
*/
virtual String GetName() const = 0;
/**
* @brief Get the unique system wide heap id.
*
* @return The heap id.
*/
virtual HeapId GetId() const = 0;
/**
* @brief Get the system that created the heap.
*
* @return An ISystem interface.
*/
virtual ISystem *GetSystem() const = 0;
/**
* @brief Get heap stats.
*
* @param returnStats reference to a stats object.
*/
virtual void GetStats(Stats &returnStats) const = 0;
/**
* @brief Get previous heap stats.
*
* @param returnStats reference to a stats object.
*/
virtual void GetPreviousStats(Stats &returnStats) const = 0;
/**
* @brief Reset heap stats.
*/
virtual void ResetStats() = 0;
/**
* @brief Reset daily heap stats.
*/
virtual void ResetDailyStats() = 0;
/**
* @brief Get request distribution logging state.
*
* @return true if request distribution loggin is enabled.
*/
virtual bool GetRequestDistributionLogging() const = 0;
/**
* @brief Enable or disable request distribution logging.
*
* @param shouldEnable true to enable.
*/
virtual void SetRequestDistributionLogging(const bool shouldEnable) = 0;
/**
* @brief Is alerting on failures enabled?
*
* @return Boolean.
*/
virtual bool IsAlertingEnabled() const = 0;
/**
* @brief Get a message or chain of messages from a list of heaps.
*
* @param heapMessage to receive the message.
* @param size the maximum number of bytes the message will hold.
* @param ... a 0 terminated list of IHeap pointers.
*
* GetMessage() will be called on each heap until a successful allocation.
*/
ACTIV_FRAMEWORK_API
static void GetMessageFromList(HeapMessage &heapMessage, const size_t size, ...);
};
// ---------------------------------------------------------------------------------------------------------------------------------
inline IHeap::~IHeap()
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void IHeap::GetMessage(const MessageBuilder &messageBuilder, HeapMessage &heapMessage)
{
return GetMessage(messageBuilder.GetMessage(), messageBuilder.GetLength(), heapMessage);
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::GetCurrentFreePercent() const
{
if (!m_isFastPathGetEnabled)
return m_sharedBucketListStats.GetCurrentFreePercent();
return GetMinimum<size_t>(m_sharedBucketListStats.GetCurrentFreePercent(), m_fastPathBucketListStats.GetCurrentFreePercent());
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::GetLowFreePercent() const
{
if (!m_isFastPathGetEnabled)
return m_sharedBucketListStats.GetLowFreePercent();
return GetMinimum<size_t>(m_sharedBucketListStats.GetLowFreePercent(), m_fastPathBucketListStats.GetLowFreePercent());
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::GetIntervalLowFreePercent() const
{
if (!m_isFastPathGetEnabled)
return m_sharedBucketListStats.GetIntervalLowFreePercent();
return GetMinimum<size_t>(m_sharedBucketListStats.GetIntervalLowFreePercent(),
m_fastPathBucketListStats.GetIntervalLowFreePercent());
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::BucketListStats::GetCurrentFreePercent() const
{
return (m_totalNumberOfMessages != 0) ? ((m_totalCurrentFreeMessages * 100) / m_totalNumberOfMessages) : 100;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::BucketListStats::GetLowFreePercent() const
{
return (m_totalNumberOfMessages != 0) ? ((m_totalLowFreeMessages * 100) / m_totalNumberOfMessages) : 100;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline size_t IHeap::Stats::BucketListStats::GetIntervalLowFreePercent() const
{
return (m_totalNumberOfMessages != 0) ? ((m_totalLowFreeMessagesInInterval * 100) / m_totalNumberOfMessages) : 100;
}
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_IHEAP_H)