468 lines
16 KiB
C++
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 ¬ificationType);
|
|
|
|
/**
|
|
* @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)
|