Files

1686 lines
66 KiB
C++

/**
* @file include/ActivMiddleware/ActivFramework/Component.h
*
* @brief Header file for component class.
*/
#if (!defined ACTIV_FRAMEWORK_COMPONENT_H)
#define ACTIV_FRAMEWORK_COMPONENT_H
#include "ActivMiddleware/ActivFramework/External.h"
#include "ActivMiddleware/ActivFramework/Address.h"
#include "ActivMiddleware/ActivFramework/IHeap.h"
#include "ActivMiddleware/ActivFramework/HeapMessage.h"
#include "ActivMiddleware/ActivFramework/ScopedAddress.h"
#include "ActivMiddleware/ActivFramework/SyncRequestId.h"
#include "ActivMiddleware/ActivFramework/TimerServiceApi.h"
#include "ActivMiddleware/ActivBase/Uuid.h"
#include "ActivMiddleware/CxxYZ/atomic.h"
#include "ActivMiddleware/CxxYZ/functional.h"
#include "ActivMiddleware/CxxYZ/memory.h"
#include ACTIV_BOOST_INCLUDE(array.hpp)
#include ACTIV_BOOST_INCLUDE(functional/value_factory.hpp)
#include ACTIV_BOOST_INCLUDE(parameter/parameters.hpp)
#include ACTIV_BOOST_INCLUDE(parameter/preprocessor.hpp)
#include ACTIV_BOOST_INCLUDE(parameter/name.hpp)
//! Activ namespace.
namespace Activ
{
class DefaultComponent;
class Application;
class ManagedEndPoint;
class ManagedEndPointImpl;
class RequestId;
class SocketEventManagee;
class SystemImpl;
namespace ComponentSettingsKeywords
{
// Component::Settings fields.
ACTIV_BOOST_PARAMETER_NAME(name)
ACTIV_BOOST_PARAMETER_NAME(portId)
ACTIV_BOOST_PARAMETER_NAME(heap)
ACTIV_BOOST_PARAMETER_NAME(licenseId)
ACTIV_BOOST_PARAMETER_NAME(callbackInfoList)
} // namespace ComponentSettingsKeywords
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Component class.
*/
class Component : private Boost::noncopyable
{
public:
static const TimeoutPeriod defaultTimeout = COMPONENT_DEFAULT_TIMEOUT; ///< Default timeout for assorted synchronous calls.
ACTIV_FRAMEWORK_API
static const String anonymousName; ///< Use this if you don't want to name a component.
ACTIV_FRAMEWORK_API
static const String defaultComponentId; ///< The default component id.
//! Types of callback.
enum CallbackType
{
CALLBACK_TYPE_MESSAGE, ///< One-way asynchronous message (classically, the OnMessage() callback).
CALLBACK_TYPE_REQUEST, ///< Request (classically, the OnRequest() callback).
CALLBACK_TYPE_RESPONSE, ///< Response (classically, the OnResponse() callback).
NUMBER_OF_CALLBACK_TYPES
};
/**
* @brief Type for a callback function. It must take a single parameter of type "HeapMessage &".
* Return type and const-ness are unspecified.
*/
typedef CxxYZ::function<void (HeapMessage &)> CallbackFunction;
//! Callback info for any CallbackType.
class CallbackInfo
{
public:
CallbackInfo(const CallbackType callbackType, const MessageType messageType, const CallbackFunction &callbackFunction);
CallbackType m_callbackType;
MessageType m_messageType;
CallbackFunction m_callbackFunction;
};
//! Callback info for asynchronous messages.
class MessageCallbackInfo : public CallbackInfo
{
public:
/**
* @brief Constructor.
*
* @param messageType the message type to invoke the callback for.
* @param callbackFunction
*/
MessageCallbackInfo(const MessageType messageType, const CallbackFunction &callbackFunction);
};
//! Callback info for requests.
class RequestCallbackInfo : public CallbackInfo
{
public:
/**
* @brief Constructor.
*
* @param messageType the request type to invoke the callback for.
* @param callbackFunction
*/
RequestCallbackInfo(const MessageType messageType, const CallbackFunction &callbackFunction);
};
//! Callback info for responses.
class ResponseCallbackInfo : public CallbackInfo
{
public:
/**
* @brief Constructor.
*
* @param messageType the response type to invoke the callback for.
* @param callbackFunction
*/
ResponseCallbackInfo(const MessageType messageType, const CallbackFunction &callbackFunction);
};
//! List of CallbackInfo objects.
typedef std::vector<CallbackInfo> CallbackInfoList;
/**
* @brief Helper to build a CallbackInfoList on the fly.
*
* For example:
*
* RegisterCallbacks(CallbackInfoListHelper() %
* MessageCallbackInfo(MY_TYPE, CxxYZ::bind(&MyComponent::ProcessMyTypeMessage, this, CxxYZ::_1)) %
* RequestCallbackInfo(MY_REQUEST, CxxYZ::bind(&MyComponent::ProcessMyRequest, this, CxxYZ::_1)));
*/
class CallbackInfoListHelper
{
public:
//! operator% to append a CallbackInfo.
CallbackInfoListHelper &operator%(const CallbackInfo &callbackInfo);
//! operator% to append a CallbackInfoList.
CallbackInfoListHelper &operator%(const CallbackInfoList &callbackInfoList);
//! Conversion to CallbackInfoList operator.
operator const CallbackInfoList &() const;
private:
CallbackInfoList m_callbackInfoList;
};
//! Scoped request helper.
class Request : private Boost::noncopyable
{
public:
typedef CxxYZ::function<StatusCode (const RequestId &)> PostRequestFunction;
/**
* @brief Constructor.
*
* @param component
* @param callbackFunction function to be invoked when the response arrives, or the request times out.
* @param postRequestFunction function to be invoked to actually post a request.
* @param timeoutPeriod
*
* @throw Exception
* @throw std::exception
*/
ACTIV_FRAMEWORK_API
Request(Component &component, const CallbackFunction &callbackFunction, const PostRequestFunction &postRequestFunction,
const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Constructor.
*
* @param component Component to post the request.
* @param callbackFunction function to be invoked when the response arrives, or the request times out.
* @param destinationAddress the target address.
* @param requestType the request type.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
* @param timeoutPeriod
*
* @throw Exception
* @throw std::exception
*/
ACTIV_FRAMEWORK_API
Request(Component &component, const CallbackFunction &callbackFunction, const Address &destinationAddress,
const MessageType requestType, const MessageBuilder &messageBuilder,
const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Constructor.
*
* @param component Component to post the request.
* @param callbackFunction function to be invoked when the response arrives, or the request times out.
* @param destinationAddress the target address.
* @param requestType the request type.
* @param pRequest the request message buffer.
* @param requestLength the length of the request message buffer.
* @param timeoutPeriod
*
* @throw Exception
* @throw std::exception
*/
ACTIV_FRAMEWORK_API
Request(Component &component, const CallbackFunction &callbackFunction, const Address &destinationAddress,
const MessageType requestType, const void *pRequest = 0, const size_t requestLength = 0,
const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Constructor.
*
* @param component Component to post the request.
* @param callbackFunction function to be invoked when the response arrives, or the request times out.
* @param destinationAddress the target address.
* @param requestType the request type.
* @param request the HeapMessage containing the request body.
* @param timeoutPeriod
*
* @throw Exception
* @throw std::exception
*/
ACTIV_FRAMEWORK_API
Request(Component &component, const CallbackFunction &callbackFunction, const Address &destinationAddress,
const MessageType requestType, HeapMessage &request, const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
//! Destructor. Cancels pending request; no callback will be invoked.
ACTIV_FRAMEWORK_API
~Request();
private:
enum State
{
STATE_INIT,
STATE_PENDING,
STATE_TIMEOUT,
STATE_COMPLETE
};
void InvokeCallback(HeapMessage &heapMessage);
void Timeout();
Component & m_component;
CallbackFunction m_callbackFunction;
State m_state;
const uint32_t m_requestId;
friend class DefaultComponent;
};
//! Helper that wraps up creation of a timer, storage of its address and registration of a callback when it fires.
class Timer : private Boost::noncopyable
{
public:
/**
* @brief Type for a callback function. It can take a single parameter of type "const DateTime &".
* Return type and const-ness are unspecified.
*/
typedef CxxYZ::function<void (const DateTime &)> CallbackFunction;
//! Callback type for asynchronous timer creation failure.
typedef CxxYZ::function<void (StatusCode)> AsyncErrorFunction;
/**
* @brief Proxy for TimerServiceApi Parameter classes.
*
* @tparam T the timer type; e.g. TimerServiceApi::Countdown, TimerServiceApi::TickChime::Second, etc.
*/
template<typename T>
class Parameters : public T::Parameters
{
public:
template<typename A1>
Parameters(const A1 &a1);
template<typename A1, typename A2>
Parameters(const A1 &a1, const A2 &a2);
template<typename A1, typename A2, typename A3>
Parameters(const A1 &a1, const A2 &a2, const A3 &a3);
template<typename A1, typename A2, typename A3, typename A4>
Parameters(const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4);
template<typename A1, typename A2, typename A3, typename A4, typename A5>
Parameters(const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4, const A5 &a5);
};
/**
* @brief Constructor.
*
* @tparam T the timer type; e.g. TimerServiceApi::Countdown, TimerServiceApi::TickChime::Second, etc.
*
* @param component the Component creating the timer.
* @param timerParameters
* @param callbackFunction function to be invoked when the timer fires.
* @param asyncErrorFunction if not provided, create the timer synchronously. Otherwise, the callback
* to invoke if asynchronous timer creation fails.
*
* @throw Exception
* @throw std::exception
*/
template<typename T>
Timer(Component &component, const Parameters<T> &timerParameters, const CallbackFunction &callbackFunction,
const AsyncErrorFunction &asyncErrorFunction = AsyncErrorFunction());
//! Destructor. Cancels the timer and removes the callback.
~Timer();
//! Cancel the timer.
void Cancel();
private:
ACTIV_FRAMEWORK_API
void ProcessResponse(HeapMessage &response);
Component & m_component;
const CallbackFunction m_callbackFunction;
const AsyncErrorFunction m_asyncErrorFunction;
Boost::scoped_ptr<Request> m_pRequest;
ScopedAddress m_timerAddress;
};
//! Helper class to enable & disable a Component.
class Enabler : private Boost::noncopyable
{
public:
/**
* @brief Constructor. Will enable the component.
*
* @param component reference to the component to enable.
*/
Enabler(Component &component);
//! Destructor. Will disable the component.
~Enabler();
private:
Component &m_component;
};
class SettingsImpl
{
public:
//! Copy constructor.
SettingsImpl(const SettingsImpl &settings);
//! Boost parameter constructor.
template<typename ARGS>
SettingsImpl(const ARGS &args);
String m_name;
PortId m_portId;
IHeap * m_pHeap;
String m_componentLicenseId;
CallbackInfoList m_callbackInfoList;
ACTIV_DECLARE_PARAMETER_ACCESSOR(ComponentSettingsKeywords, name)
ACTIV_DECLARE_PARAMETER_ACCESSOR(ComponentSettingsKeywords, portId)
ACTIV_DECLARE_PARAMETER_ACCESSOR(ComponentSettingsKeywords, heap)
ACTIV_DECLARE_PARAMETER_ACCESSOR(ComponentSettingsKeywords, licenseId)
ACTIV_DECLARE_PARAMETER_ACCESSOR(ComponentSettingsKeywords, callbackInfoList)
};
/**
* @brief Optional settings for a Component.
*
* name name of the component, local to the endpoint.
* portId the port id to attach to, or INVALID_PORT_ID (the default) to attach to the next available slot.
* pHeap heap to use for messaging, or 0 (the default) for the calling application's heap.
* licenseId the component's license id.
*
* This uses Boost's parameter library and can be used as follows:
*
* Component::Settings settings(Component::Settings::name() = "Test", Component::Settings::heap() = pMyHeap);
*/
class Settings : public SettingsImpl
{
public:
//! Boost parameter constructor.
ACTIV_BOOST_PARAMETER_CONSTRUCTOR(
Settings, (SettingsImpl), ComponentSettingsKeywords::tag,
(optional
(name, *)
(portId, *)
(heap, *)
(licenseId, *)
(callbackInfoList, *)
)
)
};
/**
* @brief Constructor.
*
* Attaches this object to a managed endpoint.
*
* @param managedEndPoint reference to a ManagedEndPoint object to which this component is to be attached.
* @param settings
*
* @throw Exception.
*/
ACTIV_FRAMEWORK_API
Component(ManagedEndPoint &managedEndPoint, const SettingsImpl &settings);
/**
* @brief Constructor.
*
* Attaches this object to the Application's default managed endpoint at the next available slot.
*
* @param application reference to an Application object to which this component is to be attached.
* @param name name of the component, local to the endpoint.
* @param pHeap heap to use for messaging, or 0 for the calling application's heap.
* @param componentLicenseId the component's license id.
*
* @throw Exception.
*/
ACTIV_FRAMEWORK_API
explicit Component(Application &application, const String &name = anonymousName, IHeap * const pHeap = 0,
const String &componentLicenseId = defaultComponentId);
/**
* @brief Constructor.
*
* Attaches this object to a managed endpoint at the next available slot.
*
* @param managedEndPoint reference to a ManagedEndPoint object to which this component is to be attached.
* @param name name of the component, local to the endpoint.
* @param pHeap heap to use for messaging, or 0 for the calling application's heap.
* @param componentLicenseId the component's license id.
*
* @throw Exception.
*/
ACTIV_FRAMEWORK_API
explicit Component(ManagedEndPoint &managedEndPoint, const String &name = anonymousName, IHeap * const pHeap = 0,
const String &componentLicenseId = defaultComponentId);
/**
* @brief Destructor.
*
* The destructor will assert if Disable() has not been called for this component if Enable() had previously been called.
* See Disable() for more information.
*/
ACTIV_FRAMEWORK_API
virtual ~Component();
/**
* @brief Enable a component.
*
* Enabling a component means that it can start to receive messages. This should be done only after the class derived from
* Component has been fully constructed, so that messages won't be received by the Component before construction is complete.
*
* If you have a derived Component class that will never be derived from, then it is safe to put Enable() in the
* constructor for that class.
*
* Note that since a Component cannot receive messages until Enable() has been called, no calls should be made before
* an Enable() that may cause messages to arrive that you cannot miss. For instance, tcp connections should not
* be initiated since a connect notification may be missed.
*
* A Component can only be Enable()d once.
*/
ACTIV_FRAMEWORK_API
virtual void Enable();
/**
* @brief Disable a component.
*
* Disabling a component stops it from receiving any more messages and detaches it from its ManagedEndPoint.
* This should be done before any destruction of a derived Component class starts.
*
* If you have a derived Component class that will never be derived from, then it is safe to put Disable() in the
* destructor for that class.
*/
ACTIV_FRAMEWORK_API
virtual void Disable();
/**
* @brief Register a list of callbacks.
*
* @param callbackInfoList
*/
ACTIV_FRAMEWORK_API
void RegisterCallbacks(const CallbackInfoList &callbackInfoList);
//! Get a reference to the application object.
Application &GetApplication() const;
//! Get the managed endpoint this component is attached to.
ACTIV_FRAMEWORK_API
ManagedEndPoint &GetManagedEndPoint() const;
//! Get the name of the component.
ACTIV_FRAMEWORK_API
const String &GetName() const;
//! Get the address of this component.
const Address &GetAddress() const;
//! Get the heap used for messaging.
IHeap *GetHeap() const;
//! Get the uuid assigned to this component.
const Uuid &GetUuid() const;
/**
* @brief Set the heap used for messaging.
*
* @param pHeap new heap to use for messaging.
*/
ACTIV_FRAMEWORK_API
void SetHeap(IHeap * const pHeap);
/**
* @brief Find an endpoint & component by name.
*
* @param endPointName the name of the endpoint.
* @param componentName the name of the component.
* @param componentAddress referece to an Address object to receive the address of the discovered component.
* @param timeout how long to wait for the endpoint, in ms.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_FOUND
* @retval STATUS_CODE_MISMATCH component found at the registered address that does not have the given name.
* @retval STATUS_CODE_TIMEOUT component not found in timeout period.
* @retval STATUS_CODE_HEAP_EMPTY
*/
ACTIV_FRAMEWORK_API
StatusCode FindComponent(const String &endPointName, const String &componentName, Address &componentAddress,
const TimeoutPeriod timeout = defaultTimeout);
//! Is the calling thread processing the ManagedEndPoint this Component is attached to?
ACTIV_FRAMEWORK_API
bool IsCallbackThread() const;
/**
* @brief Post an asynchronous request.
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostRequest(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const MessageBuilder &messageBuilder) const;
/**
* @brief Post an asynchronous request.
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param pRequest the request message buffer.
* @param requestLength the length of the request message buffer.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostRequest(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const void *pRequest = 0, const size_t requestLength = 0) const;
/**
* @brief Post an asynchronous request.
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param request the HeapMessage containing the request body.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostRequest(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
HeapMessage &request) const;
/**
* @brief Send a synchronous request and wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the value of response.GetStatusCode()
* will contain the actual return status of the request (the return value from SendRequest() just
* determines whether the actual message transmission was successful).
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
* @param response HeapMessage to receive the response.
* @param timeout in milliseconds.
*
* @retval STATUS_CODE_SUCCESS a response has been received.
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
* @retval STATUS_CODE_TIMEOUT no response received in the timeout period.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, const MessageBuilder &messageBuilder,
HeapMessage &response, const TimeoutPeriod timeout = defaultTimeout) const;
/**
* @brief Send a synchronous request and wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the value of response.GetStatusCode()
* will contain the actual return status of the request (the return value from SendRequest() just
* determines whether the actual message transmission was successful).
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param pRequest the request message buffer.
* @param requestLength the length of the request message buffer.
* @param response HeapMessage to receive the response.
* @param timeout in milliseconds.
*
* @retval STATUS_CODE_SUCCESS a response has been received.
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
* @retval STATUS_CODE_TIMEOUT no response received in the timeout period.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, const void *pRequest,
const size_t requestLength, HeapMessage &response, const TimeoutPeriod timeout = defaultTimeout) const;
/**
* @brief Send a synchronous request and wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the value of request.GetStatusCode()
* will contain the actual return status of the request (the return value from SendRequest() just
* determines whether the actual message transmission was successful).
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param request the request message and container for the response. If request is an empty HeapMessage, a
* request will be sent with no message body.
* @param timeout in milliseconds.
*
* @retval STATUS_CODE_SUCCESS a response has been received.
* @retval STATUS_CODE_HEAP_EMPTY if request was empty and no message could be allocated for the outgoing request.
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
* @retval STATUS_CODE_TIMEOUT no response received in the timeout period.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, HeapMessage &request,
const TimeoutPeriod timeout = defaultTimeout) const;
/**
* @brief Send a synchronous request but do not wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the response can be obtained by calling syncRequestId.GetResponse().
* The actual return status of the request can then be obtained by GetStatusCode() on the message returned from
* syncRequestId.GetResponse().
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param syncRequestId reference to a SyncRequestId object that can be used later to wait (or poll) for the response.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
*
* @retval STATUS_CODE_SUCCESS the request was sent successfully.
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, SyncRequestId &syncRequestId,
const MessageBuilder &messageBuilder) const;
/**
* @brief Send a synchronous request but do not wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the response can be obtained by calling syncRequestId.GetResponse().
* The actual return status of the request can then be obtained by GetStatusCode() on the message returned from
* syncRequestId.GetResponse().
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param syncRequestId reference to a SyncRequestId object that can be used later to wait (or poll) for the response.
* @param pRequest the request message buffer.
* @param requestLength the length of the request message buffer.
*
* @retval STATUS_CODE_SUCCESS the request was sent successfully.
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, SyncRequestId &syncRequestId,
const void *pRequest, const size_t requestLength) const;
/**
* @brief Send a synchronous request but do not wait for the response.
*
* If this returns STATUS_CODE_SUCCESS, the response can be obtained by calling syncRequestId.GetResponse().
* The actual return status of the request can then be obtained by GetStatusCode() on the message returned from
* syncRequestId.GetResponse().
*
* @param destinationAddress the target address.
* @param requestType the request type.
* @param syncRequestId reference to a SyncRequestId object that can be used later to wait (or poll) for the response.
* @param request the request message. If request is an empty HeapMessage, a
* request will be sent with no message body.
*
* @retval STATUS_CODE_SUCCESS the request was sent successfully.
* @retval STATUS_CODE_HEAP_EMPTY if request was empty and no message could be allocated for the outgoing request.
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode SendRequest(const Address &destinationAddress, const MessageType requestType, SyncRequestId &syncRequestId,
HeapMessage &request) const;
/**
* @brief Post a response to a request.
*
* @param destinationAddress the target address (the source address of the request).
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param responseStatus the response status.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const StatusCode responseStatus, const MessageBuilder &messageBuilder) const;
/**
* @brief Post a response to a request.
*
* @param destinationAddress the target address (the source address of the request).
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param responseStatus the response status.
* @param pResponse the response message buffer.
* @param responseLength the length of the response message buffer.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const StatusCode responseStatus, const void *pResponse = 0, const size_t responseLength = 0) const;
/**
* @brief Post a response to a request. Use this call when the response message is a newly allocated
* HeapMessage and is not the original request.
*
* @param destinationAddress the target address (the source address of the request).
* @param requestType the request type.
* @param requestId the message identification (to match up the response).
* @param responseStatus the response status.
* @param response the response message.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const StatusCode responseStatus, HeapMessage &response) const;
/**
* @brief Post a response to a request where the request HeapMessage still has the original request id
* and message type of the request. The contents of the request HeapMessage are overridden with
* the provided MessageBuilder contents.
*
* @param responseStatus the response status.
* @param request the original request.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const StatusCode responseStatus, HeapMessage &request, const MessageBuilder &messageBuilder) const;
/**
* @brief Post a response to a request where the request HeapMessage still has the original request id
* and message type of the request. The contents of the request HeapMessage are overridden with
* the provided buffer.
*
* @param responseStatus the response status.
* @param request the original request.
* @param pResponse the response message buffer.
* @param responseLength the length of the response message buffer.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const StatusCode responseStatus, HeapMessage &request, const void *pResponse,
const size_t responseLength) const;
/**
* @brief Post a response to a request where the request HeapMessage still has the original request id
* and message type of the request. The provided response HeapMessage contains the response body.
*
* @param responseStatus the response status.
* @param request the original request.
* @param response a second HeapMessage containing the response body.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const StatusCode responseStatus, HeapMessage &request, HeapMessage &response) const;
/**
* @brief Post a response to a request where the original request message has been filled in with the response.
* All other members of the response message must be as received (request id, type, addresses).
*
* @param responseStatus the response status.
* @param request the original request message filled in with the response data.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostResponse(const StatusCode responseStatus, HeapMessage &request) const;
/**
* @brief Post an empty response to a request. The response will be sent to the source address of the request.
*
* If replying to a request and the contents of the response are unimportant, it is preferable to use PostEmptyResponse()
* as if the request was made remotely, there will be no serializing of message body over the network.
*
* @param responseStatus the response status.
* @param request the original request message. Any data in the message is truncated.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostEmptyResponse(const StatusCode responseStatus, HeapMessage &request) const;
/**
* @brief Post an empty response to a request. Use this call when the response message is a newly allocated
* HeapMessage and is not the original request.
*
* If replying to a request and the contents of the response are unimportant, it is preferable to use PostEmptyResponse()
* as if the request was made remotely, there will be no serializing of message body over the network.
*
* @param destinationAddress the target address (the source address of the original request).
* @param requestType the request type of the original request.
* @param requestId the message identification (to match up the response).
* @param responseStatus the response status.
* @param response the response message. Data will be truncated.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostEmptyResponse(const Address &destinationAddress, const MessageType requestType, const RequestId &requestId,
const StatusCode responseStatus, HeapMessage &response) const;
/**
* @brief Post a message.
*
* @param destinationAddress the target address.
* @param messageType the message type.
* @param messageBuilder reference to a MessageBuilder containing the message body to post.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostMessage(const Address &destinationAddress, const MessageType messageType,
const MessageBuilder &messageBuilder) const;
/**
* @brief Post a message.
*
* @param destinationAddress the target address.
* @param messageType the message type.
* @param pMessage the message buffer.
* @param messageLength the length of the message buffer.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_HEAP_EMPTY
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostMessage(const Address &destinationAddress, const MessageType messageType, const void *pMessage = 0,
const size_t messageLength = 0) const;
/**
* @brief Post a message.
*
* @param destinationAddress the target address.
* @param messageType the message type.
* @param message the message.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostMessage(const Address &destinationAddress, const MessageType messageType, HeapMessage &message) const;
/**
* @brief Forward a message to another address without changing the source address.
*
* @param destinationAddress the target address.
* @param message the message.
* @param newType the new message type, or INVALID_MESSAGE_TYPE (the default) to keep the message type unchanged.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode ForwardMessage(const Address &destinationAddress, HeapMessage &message,
const MessageType newType = INVALID_MESSAGE_TYPE) const;
/**
* @brief Post a task for execution on the thread processing a managed endpoint.
*
* @param managedEndPoint the managed endpoint to post the task on to.
* @param task the task.
* @param heapMessage the heap message to post the task in.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
StatusCode PostTask(const ManagedEndPoint &managedEndPoint, const CxxYZ::function<void (HeapMessage &)> &task,
ACTIV_BOOST_RV_REF(HeapMessage) heapMessage = HeapMessage());
#if (!defined ACTIV_BOOST_NO_CXX11_RVALUE_REFERENCES)
/**
* @brief Post a task for execution on the thread processing a managed endpoint.
*
* Only available for c++11 onwards.
*
* @param managedEndPoint the managed endpoint to post the task on to.
* @param task the task.
* @param heapMessage the heap message to post the task in.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
StatusCode PostTask(const ManagedEndPoint &managedEndPoint, CxxYZ::function<void (HeapMessage &)> &&task,
HeapMessage &&heapMessage = HeapMessage());
#endif
protected:
/**
* @brief Request callback.
*
* If you override this method, please call the base class method for any unrecognized
* request types. Note the request is automatically replied to with the returned status value
* if the status is other than STATUS_CODE_SUCCESS or STATUS_CODE_EXIT.
*
* If an overridden OnRequest() throws an exception out of OnRequest(), the request is automatically replied to
* if \a request still has an attached message.
*
* If the exception is of type StatusCodeException, the status of the response is the exception error code,
* otherwise STATUS_CODE_UNHANDLED_EXCEPTION.
*
* If this is not required behaviour, for example if the request has been replied to before an exception is
* thrown, ensure the exception is not allowed out of the scope of the OnRequest() override, or that \a request
* no longer has a message attached at the point the exception is thrown.
*
* @param request the request message.
*
* @retval STATUS_CODE_SUCCESS the message was recognized.
* @retval STATUS_CODE_UNRECOGNIZED the message was not recognized.
* @retval STATUS_CODE_EXIT received a thread-die message.
* @retval ...
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnRequest(HeapMessage &request);
/**
* @brief Response callback.
*
* If you override this method, please call the base class method for any unrecognized
* request types.
*
* @param response the response message.
*
* @retval STATUS_CODE_SUCCESS the message was recognized.
* @retval STATUS_CODE_UNRECOGNIZED the message was not recognized.
* @retval STATUS_CODE_EXIT received a thread-die message.
* @retval ...
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnResponse(HeapMessage &response);
/**
* @brief Message callback.
*
* If you override this method, please call the base class method for any unrecognized
* message types.
*
* @param message the message.
*
* @retval STATUS_CODE_SUCCESS the message was recognized.
* @retval STATUS_CODE_UNRECOGNIZED the message was not recognized.
* @retval STATUS_CODE_EXIT received a thread-die message.
* @retval ...
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnMessage(HeapMessage &message);
/**
* @brief Timer callback.
*
* When overriding, please call the base class version for any unrecognized timer.
*
* @param timerAddress the timer address.
* @param dateTime the date/time of the timer.
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnTimer(const Address &timerAddress, const DateTime &dateTime);
/**
* @brief A circuit has been established.
*
* This callback will only be called if the newer OnConnect() overload taking a local ip address returns
* STATUS_CODE_UNRECOGNIZED.
*
* When overriding, please call the base class version for any unrecognized circuit.
*
* This is called for a successful asynchronous connection. connectMessage.GetSourceAddress() is the circuit
* that has established.
*
* The message may contain response data from an user data that was sent in the circuit establishment, if
* the underlying protocol supports it.
*
* For example, if this is the result of an asynchronous OpenService() call, ValidateOpenServiceResponse()
* should be called.
*
* @param connectMessage
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnConnect(HeapMessage &connectMessage);
/**
* @brief A circuit has been established.
*
* When overriding, please call the base class version for any unrecognized circuit.
*
* This is called for a successful asynchronous connection. connectMessage.GetSourceAddress() is the circuit
* that has established.
*
* The message may contain response data from an user data that was sent in the circuit establishment, if
* the underlying protocol supports it.
*
* For example, if this is the result of an asynchronous OpenService() call, ValidateOpenServiceResponse()
* should be called.
*
* @param connectMessage
* @param localIpAddress the local IP address of the connection.
*
* @retval STATUS_CODE_UNRECOGNIZED the OnConnect() callback will be invoked without localIpAddress.
* @retval ... all other values are ignored.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnConnect(HeapMessage &connectMessage, const IpAddress &localIpAddress);
/**
* @brief A circuit has failed to connect.
*
* When overriding, please call the base class version for any unrecognized circuit.
*
* The callback is for informational purposes only. If an asynchronous connection attempts fails, the
* OnConnectFailed() callback will be invoked but the router service will automatically attempt to connect again
* on a lazy basis until the circuit is Disconnect()ed. No OnConnectFailed() is called for a synchronous connect
* (the connect call will just timeout after the specified period with an error status code).
*
* @param connectFailMessage the circuit that has failed to connect is connectFailMessage.GetSourceAddress(), a reason
* for the failed connect is connectFailMessage.GetStatusCode().
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnConnectFailed(HeapMessage &connectFailMessage);
/**
* @brief A client is attempting to connect.
*
* This callback will only be called if the newer OnAccept() overload taking a local ip address returns
* STATUS_CODE_UNRECOGNIZED.
*
* The source address of \a acceptMessage contains the address of the circuit that is attempting to connect.
* This address should be used to communicate with the client.
*
* The ip address embedded in acceptMessage (accessible with acceptMessage.GetIpAddress()) contains the ip address
* of the client attempting to connect.
*
* The acceptMessage must be replied to, using PostResponse(statusCode, acceptMessage). Passing
* STATUS_CODE_SUCCESS allows the client access, any other value refuses the client.
*
* The acceptMessage itself can be forwarded to another component instead of being replied to immediately.
* That component will then have OnAccept() called, from which it can PostResponse(). The established circuit
* will then be to that component and not the original receiver of the OnAccept().
*
* If acceptMessage is set to another HeapMessage from a different heap, the router will use the new heap
* for received messages on the connection, rather than the original heap. NB the contents of acceptMessage
* must be copied to the new HeapMessage.
*
* The default Component::OnAccept() behaviour is to call PostResponse(STATUS_CODE_SUCCESS, acceptMessage) to
* accept the client.
*
* @param acceptMessage
*
* @return The return value is not used by the framework and is provided as a helper for overriding.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnAccept(HeapMessage &acceptMessage);
/**
* @brief A client is attempting to connect.
*
* If the acceptMessage is not handled, the old OnAccept callback is invoked.
*
* The source address of \a acceptMessage contains the address of the circuit that is attempting to connect.
* This address should be used to communicate with the client.
*
* The ip address embedded in acceptMessage (accessible with acceptMessage.GetIpAddress()) contains the ip address
* of the client attempting to connect.
*
* The acceptMessage must be replied to, using PostResponse(statusCode, acceptMessage). Passing
* STATUS_CODE_SUCCESS allows the client access, any other value refuses the client.
*
* The acceptMessage itself can be forwarded to another component instead of being replied to immediately.
* That component will then have OnAccept() called, from which it can PostResponse(). The established circuit
* will then be to that component and not the original receiver of the OnAccept().
*
* If acceptMessage is set to another HeapMessage from a different heap, the router will use the new heap
* for received messages on the connection, rather than the original heap. NB the contents of acceptMessage
* must be copied to the new HeapMessage.
*
* @param acceptMessage
* @param localIpAddress
*
* @retval STATUS_CODE_UNRECOGNIZED the OnAccept() callback will be invoked without localIpAddress.
* @retval ... all other values are ignored.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnAccept(HeapMessage &acceptMessage, const IpAddress &localIpAddress);
/**
* @brief A circuit has broken under our feet.
*
* When overriding, please call the base class version for any unrecognized circuit.
*
* @param breakMessage the address of the circuit that is now not connected is breakMessage.GetSourceAddress().
* A reason for the break can be found in breakMessage.GetStatusCode().
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnBreak(HeapMessage &breakMessage);
/**
* @brief A circuit has been closed after an asynchronous Disconnect() call.
*
* When overriding, please call the base class version for any unrecognized circuit.
*
* This is called for a successful asynchronous disconnect completion.
* disconnectMessage.GetSourceAddress() is the circuit that has been established.
*
* The message may contain response data from any user data that was sent in the disconnect, if
* the underlying protocol supports it.
*
* @param disconnectMessage
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnDisconnect(HeapMessage &disconnectMessage);
/**
* @brief Raw data received.
*
* When overriding, please call the base class version if the data is from an unknown address.
*
* @param heapMessage heap message containing the received data.
*
* @return The return value is not used by the framework, but may be used by an application to pass values between
* parent and sub class versions of this function. Returns STATUS_CODE_UNRECOGNIZED by default.
*/
ACTIV_FRAMEWORK_API
virtual StatusCode OnData(HeapMessage &heapMessage);
/**
* @brief A thread processing the ManagedEndPoint this Component is attached to is starting.
*
* This function is invoked from the context of the ManagedEndPoint thread. This callback is not invoked by
* threads already processing a ManagedEndPoint when a new Component is attached.
*/
ACTIV_FRAMEWORK_API
virtual void OnThreadStart();
/**
* @brief A thread processing the ManagedEndPoint this Component is attached to is exiting.
*
* This function is invoked from the context of the ManagedEndPoint thread. For a Component attached to a
* multithreaded endpoint, this doesn't necessarily mean the Component will no longer receive messages.
*/
ACTIV_FRAMEWORK_API
virtual void OnThreadExit();
/**
* @brief Component has been Enable()d.
*
* This callback is invoked from the context of a thread processing the ManagedEndPoint this Component is attached to.
* This may or may not be the thread calling Enable().
*/
ACTIV_FRAMEWORK_API
virtual void OnEnable();
private:
typedef std::vector<CallbackFunction> CallbackFunctionList; ///< Indexed by sub-type.
typedef std::vector<CallbackFunctionList> CallbackFunctionMatrix; ///< Indexed by class.
typedef Boost::array<CallbackFunctionMatrix, NUMBER_OF_CALLBACK_TYPES>
CallbackFunctionMatrixList; ///< Indexed by callback type.
//! Enable this component.
void InternalEnable();
/**
* @brief Open and post a response message to an endpoint.
*
* @param response
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
*/
StatusCode PostResponse(HeapMessage &response) const;
/**
* @brief Open and post a message to an endpoint.
*
* @param message
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_DISABLED destination endpoint not accepting messages.
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
*/
StatusCode Post(HeapMessage &message) const;
/**
* @brief Post a task for execution on the thread processing a managed endpoint.
*
* The endpoint id specified must be part of the same process as the thread posting the task.
*
* @param managedEndPoint the managed endpoint to post the task on to.
* @param pTask pointer to the task.
* @param heapMessage the heap message to post the task in.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_INVALID_ENDPOINT the destination endpoint does not exist.
* @retval STATUS_CODE_DISABLED the endpoint is not accepting messages.
*/
ACTIV_FRAMEWORK_API
StatusCode PostTask(const ManagedEndPoint &managedEndPoint,
CxxYZ::unique_ptr<CxxYZ::function<void (HeapMessage &heapMessage)> > &pTask, ACTIV_BOOST_RV_REF(HeapMessage) heapMessage);
/**
* @brief Open and send a message to an endpoint and get response.
*
* @param message message to send and container for response.
* @param sourceAddress
* @param destinationAddress
* @param timeout
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_DISABLED destination endpoint not accepting messages.
* @retval STATUS_CODE_INVALID_ENDPOINT the target endpoint does not exist.
* @retval STATUS_CODE_TIMEOUT no response received in the timeout period.
*/
StatusCode Send(HeapMessage &message, const Address &sourceAddress, const Address &destinationAddress,
const TimeoutPeriod timeout) const;
/**
* @brief Send a message to an endpoint without waiting for the response.
*
* @param message message to send and container for response.
* @param sourceAddress
* @param destinationAddress
* @param syncRequestId reference to a SyncRequestId object that can be used later to wait (or poll) for the response.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_DISABLED destination endpoint not accepting messages.
* @retval STATUS_CODE_INVALID_ENDPOINT the target endpoint does not exist.
*/
StatusCode Send(HeapMessage &message, const Address &sourceAddress, const Address &destinationAddress,
SyncRequestId &syncRequestId) const;
/**
* @brief Send a message to an endpoint without waiting for the response.
*
* @param message message to send and container for response.
* @param sourceAddress
* @param destinationAddress
* @param syncRequestId reference to a SyncRequestId object that can be used later to wait (or poll) for the response.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_DISABLED destination endpoint not accepting messages.
* @retval STATUS_CODE_INVALID_ENDPOINT the target endpoint does not exist.
*/
StatusCode InternalSend(HeapMessage &message, const Address &sourceAddress, const Address &destinationAddress,
SyncRequestId &syncRequestId) const;
//! Update callback lists whilst no threads are processing this component's endpoint.
void RegisterCallbacksWhilstQuiescent(const CallbackInfoList &callbackInfoList);
/**
* @brief Invoke a callback.
*
* @param heapMessage
* @param callbackFunctionMatrix callbacks for messages/requests/responses.
*
* @retval STATUS_CODE_SUCCESS the message was recognized.
* @retval STATUS_CODE_UNRECOGNIZED the message was not recognized.
* @retval STATUS_CODE_EXIT received a thread-die message.
* @retval ...
*/
StatusCode InvokeCallback(HeapMessage &heapMessage, const CallbackFunctionMatrix &callbackFunctionMatrix);
//! Add a timer callback. May pause callback threads.
ACTIV_FRAMEWORK_API
void RegisterTimerCallback(const Address &timerAddress, const Timer::CallbackFunction &timerCallbackFunction);
//! Add a timer callback when no thread can receive a timer.
void RegisterTimerCallbackWhilstQuiescent(const Address &timerAddress, const Timer::CallbackFunction &timerCallbackFunction);
//! Remove a timer callback. May pause callback threads.
ACTIV_FRAMEWORK_API
void DeregisterTimerCallback(const Address &timerAddress);
//! Remove a timer callback when no thread can receive a timer.
void DeregisterTimerCallbackWhilstQuiescent(const Address &timerAddress);
//! Process a find component request.
void ProcessSystemRequestFindComponent(HeapMessage &request) const;
//! Process a ping request.
void ProcessSystemRequestPingComponent(HeapMessage &request) const;
//! Process a token.
void ProcessSystemRequestToken(HeapMessage &request) const;
//! Process a get component info list request.
void ProcessSystemRequestGetComponentInfoList(HeapMessage &request) const;
//! Process an endpoint startup request.
void ProcessSystemRequestEndPointStartup(HeapMessage &request) const;
//! Process component enable message.
void ProcessEnableComponentMessage(HeapMessage &message);
//! Process a timer message.
void ProcessOnTimerMessage(HeapMessage &message);
//! Process a ping message.
void ProcessSystemMessagePing(HeapMessage &message) const;
//! Process a set heap fast path thread message.
void ProcessSystemMessageSetHeapFastPathThread(HeapMessage &message) const;
typedef std::vector<Timer::CallbackFunction> TimerCallbackFunctionList;
//! Component states.
enum State
{
STATE_INIT, ///< Initial state. No address allocated.
STATE_ATTACHED, ///< Address allocated and component attached to ManagedEndPoint.
STATE_ENABLED, ///< Component is fully constructed and able to receive messages.
STATE_DETACHED ///< Component is removed from ManagedEndPoint.
};
Application & m_application; ///< Application object this component is using.
ManagedEndPointImpl & m_managedEndPointImpl; ///< ManagedEndPoint this component is attached to.
SystemImpl & m_systemImpl;
const Uuid m_uuid; ///< Uuid for the component.
const String m_name; ///< Name of the component.
CxxYZ::atomic<IHeap *> m_pHeap; ///< Heap to use for messaging.
volatile State m_state; ///< State of the component.
// Must be before m_address.
CallbackFunctionMatrixList m_callbackFunctionMatrixList;
TimerCallbackFunctionList m_timerCallbackFunctionList; ///< Timer callbacks.
const Address m_address; ///< Unique address of this component.
friend class DefaultComponent;
friend class ManagedEndPointImpl;
friend class ScopedAddress;
friend class SocketEventManagee;
};
// ---------------------------------------------------------------------------------------------------------------------------------
inline Application &Component::GetApplication() const
{
return m_application;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline const Address &Component::GetAddress() const
{
return m_address;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline IHeap *Component::GetHeap() const
{
return m_pHeap.load();
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline const Uuid &Component::GetUuid() const
{
return m_uuid;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline StatusCode Component::PostTask(const ManagedEndPoint &managedEndPoint, const CxxYZ::function<void (HeapMessage &)> &task,
ACTIV_BOOST_RV_REF(HeapMessage) heapMessage)
{
CxxYZ::unique_ptr<CxxYZ::function<void (HeapMessage &heapMessage)> >
pTask(new CxxYZ::function<void (HeapMessage &heapMessage)>(task));
return PostTask(managedEndPoint, pTask, CxxYZ::move(heapMessage));
}
// ---------------------------------------------------------------------------------------------------------------------------------
#if (!defined ACTIV_BOOST_NO_CXX11_RVALUE_REFERENCES)
inline StatusCode Component::PostTask(const ManagedEndPoint &managedEndPoint,
CxxYZ::function<void (HeapMessage &)> &&task, HeapMessage &&heapMessage)
{
CxxYZ::unique_ptr<CxxYZ::function<void (HeapMessage &heapMessage)> >
pTask(new CxxYZ::function<void (HeapMessage &heapMessage)>(CxxYZ::move(task)));
return PostTask(managedEndPoint, pTask, CxxYZ::move(heapMessage));
}
#endif
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::CallbackInfo::CallbackInfo(const CallbackType callbackType, const MessageType messageType,
const CallbackFunction &callbackFunction) :
m_callbackType(callbackType),
m_messageType(messageType),
m_callbackFunction(callbackFunction)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::MessageCallbackInfo::MessageCallbackInfo(const MessageType messageType,
const CallbackFunction &callbackFunction) :
CallbackInfo(CALLBACK_TYPE_MESSAGE, messageType, callbackFunction)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::RequestCallbackInfo::RequestCallbackInfo(const MessageType messageType,
const CallbackFunction &callbackFunction) :
CallbackInfo(CALLBACK_TYPE_REQUEST, messageType, callbackFunction)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::ResponseCallbackInfo::ResponseCallbackInfo(const MessageType messageType,
const CallbackFunction &callbackFunction) :
CallbackInfo(CALLBACK_TYPE_RESPONSE, messageType, callbackFunction)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::CallbackInfoListHelper &Component::CallbackInfoListHelper::operator%(const CallbackInfo &callbackInfo)
{
m_callbackInfoList.push_back(callbackInfo);
return *this;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::CallbackInfoListHelper &Component::CallbackInfoListHelper::operator%(const CallbackInfoList &callbackInfoList)
{
m_callbackInfoList.insert(m_callbackInfoList.end(), callbackInfoList.begin(), callbackInfoList.end());
return *this;
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::CallbackInfoListHelper::operator const Component::CallbackInfoList &() const
{
return m_callbackInfoList;
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::Enabler::Enabler(Component &component) :
m_component(component)
{
m_component.Enable();
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::Enabler::~Enabler()
{
m_component.Disable();
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::SettingsImpl::SettingsImpl(const SettingsImpl &settings) :
m_name(settings.m_name),
m_portId(settings.m_portId),
m_pHeap(settings.m_pHeap),
m_componentLicenseId(settings.m_componentLicenseId),
m_callbackInfoList(settings.m_callbackInfoList)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename ARGS>
inline Component::SettingsImpl::SettingsImpl(const ARGS &args) :
m_name(args[ComponentSettingsKeywords::_name | Component::anonymousName]),
m_portId(args[ComponentSettingsKeywords::_portId | INVALID_PORT_ID]),
m_pHeap(args[ComponentSettingsKeywords::_heap | static_cast<IHeap *>(ACTIV_NULLPTR)]),
m_componentLicenseId(args[ComponentSettingsKeywords::_licenseId | Component::defaultComponentId]),
m_callbackInfoList(args[ComponentSettingsKeywords::_callbackInfoList || Boost::value_factory<CallbackInfoList>()])
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>
inline Component::Timer::Timer(Component &component, const Parameters<T> &timerParameters,
const CallbackFunction &callbackFunction, const AsyncErrorFunction &asyncErrorFunction) :
m_component(component),
m_callbackFunction(callbackFunction),
m_asyncErrorFunction(asyncErrorFunction),
m_pRequest(asyncErrorFunction ? new Request(component, CxxYZ::bind(&Timer::ProcessResponse, this, CxxYZ::_1),
CxxYZ::bind(&T::PostRequest, CxxYZ::cref(component), CxxYZ::cref(timerParameters), CxxYZ::_1)) : ACTIV_NULLPTR),
m_timerAddress(component)
{
if (!asyncErrorFunction)
{
ACTIV_THROW_RESULT_IF(STATUS_CODE_SUCCESS, !=, T::Create(m_component, timerParameters, m_timerAddress));
component.RegisterTimerCallback(m_timerAddress, callbackFunction);
}
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline Component::Timer::~Timer()
{
Cancel();
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline void Component::Timer::Cancel()
{
if (m_timerAddress.IsValid())
{
m_component.DeregisterTimerCallback(m_timerAddress);
m_timerAddress.Clear();
}
}
// ---------------------------------------------------------------------------------------------------------------------------------
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>
template<typename A1>
inline Component::Timer::Parameters<T>::Parameters(const A1 &a1) :
T::Parameters(a1)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>
template<typename A1, typename A2>
inline Component::Timer::Parameters<T>::Parameters(const A1 &a1, const A2 &a2) :
T::Parameters(a1, a2)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>
template<typename A1, typename A2, typename A3>
inline Component::Timer::Parameters<T>::Parameters(const A1 &a1, const A2 &a2, const A3 &a3) :
T::Parameters(a1, a2, a3)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>template<typename A1, typename A2, typename A3, typename A4>
inline Component::Timer::Parameters<T>::Parameters(const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4) :
T::Parameters(a1, a2, a3, a4)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
template<typename T>
template<typename A1, typename A2, typename A3, typename A4, typename A5>
inline Component::Timer::Parameters<T>::Parameters(const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4, const A5 &a5) :
T::Parameters(a1, a2, a3, a4, a5)
{
}
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_COMPONENT_H)