513 lines
17 KiB
C++
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 §ionIterator);
|
|
|
|
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)
|