Files

468 lines
16 KiB
C++

/**
* @file include/ActivMiddleware/ActivFramework/IEndPoint.h
*
* @brief Header file for abstract endpoint class.
*/
#if (!defined ACTIV_FRAMEWORK_IEND_POINT_H)
#define ACTIV_FRAMEWORK_IEND_POINT_H
#include "ActivMiddleware/ActivFramework/External.h"
#include "ActivMiddleware/ActivBase/ThreadUtils.h"
#include "ActivMiddleware/CxxYZ/atomic.h"
//! Activ namespace.
namespace Activ
{
class ISystem;
class HeapMessage;
// ---------------------------------------------------------------------------------------------------------------------------------
//! Endpoint data notification types.
#define ACTIV_IENDPOINT_NOTIFICATION_TYPE_LIST(d) \
d(NOTIFICATION_TYPE_NONE, "none") \
d(NOTIFICATION_TYPE_SEMAPHORE, "semaphore") \
d(NOTIFICATION_TYPE_EVENT, "event") \
d(NOTIFICATION_TYPE_SOCKET, "socket") \
d(NOTIFICATION_TYPE_ACCURATE_WAIT_EVENT, "accurate wait event") \
d(NOTIFICATION_TYPE_COMPLETION_PORT, "completion port")
// ---------------------------------------------------------------------------------------------------------------------------------
//! Endpoint states.
#define ACTIV_IENDPOINT_STATE_LIST(d) \
d(STATE_ALLOWING_MESSAGES, "accepting") \
d(STATE_PROCESSING_MESSAGES, "processing") \
d(STATE_IGNORING_MESSAGES, "ignoring")
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Abstract endpoint interface class.
*/
class IEndPoint : private Boost::noncopyable
{
public:
//! Endpoint data notification types.
enum NotificationType
{
ACTIV_IENDPOINT_NOTIFICATION_TYPE_LIST(ACTIV_DECLARE_ELEMENT_1_WITH_COMMA)
NOTIFICATION_TYPE_DEFAULT = -1,
#if (defined ACTIV_PLATFORM_WINDOWS)
NOTIFICATION_TYPE_MULTIPLEX = NOTIFICATION_TYPE_EVENT
#elif (defined ACTIV_PLATFORM_POSIX)
NOTIFICATION_TYPE_MULTIPLEX = NOTIFICATION_TYPE_SOCKET
#else
#error Configure
#endif
};
//! Settings for endpoint creation.
class Settings
{
public:
//! Default constructor.
ACTIV_FRAMEWORK_API Settings();
bool m_hasMutex; ///< Default: false.
NotificationType m_notificationType; ///< Default: NOTIFICATION_TYPE_NONE.
//! For NOTIFICATION_TYPE_COMPLETION_PORT only. Default: 0 (a completion port is created).
HANDLE m_completionPort;
};
//! Endpoint states.
enum State
{
ACTIV_IENDPOINT_STATE_LIST(ACTIV_DECLARE_ELEMENT_1_WITH_COMMA)
NUM_STATES
};
//! Stats for an endpoint.
class Stats
{
public:
NotificationType m_notificationType; ///< Message notification type.
bool m_hasMutex; ///< Does the endpoint have a mutex?
size_t m_mutexContentionCount; ///< Approx. contentions on the endpoint's mutex.
State m_state;
size_t m_messageCount; ///< Current number of messages on endpoint.
size_t m_messageCountHigh; ///< All-time high number of messages on endpoint.
size_t m_messageCountDailyHigh; ///< Daily high number of messages on endpoint.
size_t m_messageCountLastHigh; ///< High number of messages on endpoint in last stats interval.
size_t m_byteCount; ///< Current number of bytes on endpoint.
size_t m_byteCountHigh; ///< All-time high number of bytes on endpoint.
size_t m_byteCountDailyHigh; ///< Daily high number of bytes on endpoint.
size_t m_byteCountLastHigh; ///< High number of bytes on endpoint in last stats interval.
};
// Loop count type.
typedef uint32_t LoopCount;
// Peak loop time. -1 means not set.
typedef int64_t PeakLoopTime;
//! Destructor.
virtual ~IEndPoint() = 0;
/**
* @brief Add a message to the tail of the endpoint.
*
* @param heapMessage the message to add.
*
* @retval STATUS_CODE_SUCCESS @a heapMessage added to this endpoint.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages. @a heapMessage returned to its heap.
* @retval STATUS_CODE_FULL the endpoint maximum byte count has been reached. @a heapMessage returned to its heap.
* @retval STATUS_CODE_ACCESS_DENIED this does not support private messages and @a heapMessage is a private message.
*/
virtual StatusCode PostMessage(HeapMessage &heapMessage) = 0;
/**
* @brief Add a chain of messages to the tail of this endpoint.
*
* @param pEndPoint the chain of messages to add.
*
* @retval STATUS_CODE_SUCCESS messages on @a pEndPoint added to this endpoint.
* @retval STATUS_CODE_DISABLED this is not accepting messages. All messages returned to their heap(s).
* @retval STATUS_CODE_FULL this endpoint's maximum byte count has been reached. All messages returned to their heap(s).
* @retval STATUS_CODE_ACCESS_DENIED this does not support private messages and @a pEndPoint endpoint does.
*/
virtual StatusCode PostMessages(IEndPoint * const pEndPoint) = 0;
/**
* @brief Try to add a chain of messages to the tail of this endpoint.
*
* @param pEndPoint the chain of messages to add. This must be a non-mutexed, non-notification endpoint.
*
* @retval STATUS_CODE_SUCCESS @a heapMessage added to the endpoint.
* @retval STATUS_CODE_FAILURE unable to acquire the mutex on this or @a pEndPoint. If this, messages dequeued from
* @a pEndPoint have been returned to their heap(s).
* @retval STATUS_CODE_DISABLED this is not accepting messages. All messages returned to their heap(s).
* @retval STATUS_CODE_FULL this endpoint's maximum byte count has been reached. All messages returned to their heap(s).
* @retval STATUS_CODE_ACCESS_DENIED this does not support private messages and @a pEndPoint endpoint does.
*/
virtual StatusCode TryPostMessages(IEndPoint * const pEndPoint) = 0;
/**
* @brief Get a message from the head of the endpoint.
*
* @param heapMessage reference to a HeapMessage object to receive the head message.
* @param timeout how long to wait for a message on the endpoint, in ms.
* Will be ignored if the object was not created with a data notification mechanism.
*
* @retval STATUS_CODE_SUCCESS.
* @retval STATUS_CODE_TIMEOUT no messages on this endpoint in the timeout period, @a heapMessage unaffected. Note this
* return value is possible even with @a timeout set to ACTIV_WAIT_INFINITE. @a heapMessage will only contain
* a retrieved message if the return value is STATUS_CODE_SUCCESS.
*/
virtual StatusCode GetMessage(HeapMessage &heapMessage, const TimeoutPeriod timeout = ACTIV_WAIT_INFINITE) = 0;
/**
* @brief Get multiple messages from this endpoint and add to the tail of a second endpoint.
*
* @param pEndPoint the endpoint to add messages to.
* @param timeout how long to wait for a message on this endpoint, in ms.
* Will be ignored if the object was not created with a data notification mechanism.
*
* @retval STATUS_CODE_SUCCESS.
* @retval STATUS_CODE_TIMEOUT no messages on this endpoint in the timeout period, @a pEndPoint unaffected.
* @retval STATUS_CODE_DISABLED @a pEndPoint is not accepting messages, all returned to their heap(s).
* @retval STATUS_CODE_FULL @a pEndPoint's maximum byte count has been reached. All messages returned to their heap(s).
* @retval STATUS_CODE_ACCESS_DENIED @a pEndPoint does not support private messages and this endpoint does.
*/
virtual StatusCode GetMessages(IEndPoint * const pEndPoint, const TimeoutPeriod timeout = ACTIV_WAIT_INFINITE) = 0;
/**
* @brief Try to get multiple messages from this endpoint and add to the tail of a second endpoint.
*
* @param pEndPoint the endpoint to add messages to.
*
* @retval STATUS_CODE_SUCCESS.
* @retval STATUS_CODE_FAILURE unable to acquire the mutex on this or @a pEndPoint. If pEndPoint, messages dequeued from
* this have been returned to their heap(s).
* @retval STATUS_CODE_DISABLED @a pEndPoint is not accepting messages, all returned to their heap(s).
* @retval STATUS_CODE_FULL @a pEndPoint's maximum byte count has been reached. All messages returned to their heap(s).
* @retval STATUS_CODE_ACCESS_DENIED @a pEndPoint does not support private messages and this endpoint does.
*/
virtual StatusCode TryGetMessages(IEndPoint * const pEndPoint) = 0;
/**
* @brief Get the loop count.
*
* Incremented on each message loop.
*
* @return reference to atomic loop count.
*/
virtual CxxYZ::atomic<LoopCount> &GetLoopCount() = 0;
/**
* @brief Get the peak message loop time.
*
* Holds the peak duration of a single message loop since the value was last cleared by MonitorService.
*
* @return reference to atomic peak loop time.
*/
virtual CxxYZ::atomic<PeakLoopTime> &GetPeakLoopTime() = 0;
/**
* @brief Remove all messages from the endpoint and return them to their heaps. Any queued requests are replied to with a
* status of STATUS_CODE_FAILURE.
*/
virtual void Clear() = 0;
/**
* @brief Set the state of the endpoint.
*
* Setting the endpoint state to STATE_IGNORING_MESSAGES implicitly clears the endpoint of any queued messages, and
* replies to any queued requests with STATUS_CODE_FAILURE.
*
* @param state the state to set the endpoint to.
*/
virtual void SetState(const State state) = 0;
//! Get the current state of the endpoint.
virtual State GetState() const = 0;
/**
* @brief Set the id of the thread processing the endpoint.
*
* @param threadId os id of the thread processing the endpoint.
*/
virtual void SetProcessingThreadId(const ThreadUtils::OsId threadId) = 0;
/**
* @brief Get the id of the thread processing the endpoint.
*
* @param threadId reference to receive the os thread id.
*
* @return whether the processing thread id has been set.
*/
virtual bool GetProcessingThreadId(ThreadUtils::OsId &threadId) = 0;
/**
* @brief Set whether the thread processing the endpoint is polling.
*
* @param isPolling whether the thread processing the endpoint is polling.
*/
virtual void SetIsPolling(const bool isPolling) = 0;
//! Is the thread processing the endpoint polling?
virtual bool IsPolling() const = 0;
//! Increment the busy cpu reset count.
virtual void IncrementBusyCpuResetCount() = 0;
//! Get the current busy reset count.
virtual size_t GetBusyCpuResetCount() const = 0;
//! Get the system that created the endpoint.
virtual ISystem *GetSystem() const = 0;
/**
* @brief Get endpoint stats.
*
* @param stats reference to a Stats object.
*/
virtual void GetStats(Stats &stats) const = 0;
//! Clear all high message and byte counts.
virtual void ClearAllHighCounts() = 0;
//! Clear daily high message and byte counts.
virtual void ClearDailyHighCounts() = 0;
//! Clear last high message and byte counts.
virtual void ClearLastHighCounts() = 0;
/**
* @brief Set the maximum bytes allowed on the endpoint.
*
* By default there is no limit, but if set to a non 0 value, posting a message to an endpoint which takes
* the number of bytes on the endpoint to over maxByteCount, the call will return STATUS_CODE_FULL.
*
* @param maxByteCount max bytes to allow on the endpoint, or 0 for no limit.
*/
virtual void SetMaxByteCount(const size_t maxByteCount) = 0;
//! Get maximum bytes allowed on the endpoint (0 is unlimited).
virtual size_t GetMaxByteCount() const = 0;
//! Get the underlying message notification type.
virtual NotificationType GetNotificationType() const = 0;
/**
* @brief Get the underlying message notification handle, if available.
*
* @param handle reference to receive the handle.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_SUPPORTED the notification type for this endpoint does not support an exportable handle.
*/
virtual StatusCode GetNotificationHandle(HANDLE &handle) const = 0;
/**
* @brief Return an endpoint notification type in string form.
*
* @param notificationType to convert.
*
* @return Notification type as a string.
*/
ACTIV_FRAMEWORK_API
static String NotificationTypeToString(const NotificationType notificationType);
/**
* @brief Return all endpoint notification types in pretty-printed string form.
*
* @return Notification types as a string.
*/
ACTIV_FRAMEWORK_API
static String NotificationTypesToString();
/**
* @brief Convert string to notification type.
*
* @param str the string to convert.
* @param notificationType to receive the notification type value.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_FOUND
*/
ACTIV_FRAMEWORK_API
static StatusCode StringToNotificationType(const String &str, NotificationType &notificationType);
/**
* @brief Return an endpoint state in string form.
*
* @param state to convert.
*
* @return Endpoint state as a string.
*/
ACTIV_FRAMEWORK_API
static String StateToString(const State state);
};
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
//! Endpoint types.
#define ACTIV_IADDRESSABLE_ENDPOINT_TYPE_LIST(d) \
d(TYPE_UNMANAGED, "unmanaged") \
d(TYPE_SYNCHRONOUS, "synchronous") \
d(TYPE_MANAGED, "managed") \
d(TYPE_EVENT_MANAGED, "event managed") \
d(TYPE_EVENT_MANAGED_PARENT, "event managed parent") \
d(TYPE_EVENT_MANAGED_CHILD, "event managed child")
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Endpoint interface for an endpoint that is addressable.
*/
class IAddressableEndPoint : public IEndPoint
{
public:
//! Endpoint types.
enum Type
{
ACTIV_IADDRESSABLE_ENDPOINT_TYPE_LIST(ACTIV_DECLARE_ELEMENT_1_WITH_COMMA)
NUMBER_OF_TYPES
};
class Settings : public IEndPoint::Settings
{
public:
/**
* @brief Default constructor.
*
* m_hasMutex is set to true.
* m_notificationType is set to NOTIFICATION_TYPE_DEFAULT.
*/
ACTIV_FRAMEWORK_API
Settings();
String m_name; ///< The name of the endpoint. If empty, the endpoint is given a name based on a unique id.
Type m_type; ///< Default: TYPE_UNMANAGED.
ObjectScope m_objectScope; ///< Default: OBJECT_SCOPE_SYSTEM.
};
//! Stats for an addressable endpoint.
class Stats : public IEndPoint::Stats
{
public:
String m_name; ///< Name of the endpoint.
EndPointId m_id; ///< System-wide id of the endpoint.
EndPointId m_parentId; ///< If a child endpoint, the id of the parent.
EndPointId m_processScopeId; ///< The id of the endpoint's process-scope only pair.
ProcessId m_creatorProcessId; ///< Pid of the process that created the endpoint.
Type m_type; ///< Endpoint type.
ObjectScope m_objectScope; ///< Visibility within the system.
};
//! Get the unique system wide name of the endpoint.
virtual String GetName() const = 0;
//! Get the unique system-wide id of the endpoint.
virtual EndPointId GetId() const = 0;
//! If this is a child endpoint, get the id of the parent otherwise INVALID_ENDPOINT_ID.
virtual EndPointId GetParentId() const = 0;
//! Get the process-scope pair of this endpoint, or INVALID_ENDPOINT_ID if not available.
virtual EndPointId GetProcessScopeId() const = 0;
//! Get the process id of the creator of the endpoint.
virtual ProcessId GetCreatorProcessId() const = 0;
//! Get the endpoint's type.
virtual Type GetType() const = 0;
//! Get the endpoint's ObjectScope.
virtual ObjectScope GetObjectScope() const = 0;
/**
* @brief Get endpoint stats.
*
* @param stats reference to a Stats object.
*/
virtual void GetStats(Stats &stats) const = 0;
// Keep the base GetStats() visible and rely on ADL to pick up the appropriate function.
using IEndPoint::GetStats;
//! Return an endpoint type in string form.
ACTIV_FRAMEWORK_API
static String TypeToString(const Type type);
//! Return all endpoint types in pretty-printed string form.
ACTIV_FRAMEWORK_API
static String TypesToString();
/**
* @brief Convert string to endpoint type.
*
* @param str the string to convert.
* @param type to receive the type value.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_FOUND
*/
ACTIV_FRAMEWORK_API
static StatusCode StringToType(const String &str, Type &type);
};
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline IEndPoint::~IEndPoint()
{
}
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_IEND_POINT_H)