336 lines
12 KiB
C++
336 lines
12 KiB
C++
/**
|
|
* @file include/ActivMiddleware/ActivFramework/PubSubServiceApi.h
|
|
*
|
|
* @brief Header file for the pubsub service api.
|
|
*/
|
|
|
|
#if (!defined ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H)
|
|
#define ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H
|
|
|
|
#include "ActivMiddleware/ActivFramework/External.h"
|
|
|
|
#include "ActivMiddleware/ActivBase/FieldTypes/UInt.h"
|
|
#include "ActivMiddleware/ActivBase/ProcessorAffinity.h"
|
|
#include "ActivMiddleware/ActivFramework/Subject.h"
|
|
|
|
#include <map>
|
|
#include <set>
|
|
#include <vector>
|
|
|
|
//! Activ namespace.
|
|
namespace Activ
|
|
{
|
|
|
|
class Address;
|
|
class Component;
|
|
class HeapMessage;
|
|
class MessageBuilder;
|
|
class PostMessageHelper;
|
|
class Subject;
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Api to the agent's pubsub service.
|
|
*/
|
|
class PubSubServiceApi
|
|
{
|
|
public:
|
|
typedef std::set<Address> AddressSet; ///< address set type
|
|
typedef std::vector<AddressSet> AddressSetList; ///< address set list. Index is AgentScope
|
|
typedef std::map<Subject, AddressSetList> SubscriptionMap; ///< subscription map
|
|
|
|
/**
|
|
* @brief Multicast settings.
|
|
*
|
|
* This describes an instance of a multicast input/output.
|
|
*/
|
|
class Multicast
|
|
{
|
|
public:
|
|
//! Compression types.
|
|
enum CompressionType
|
|
{
|
|
COMPRESSION_TYPE_NONE,
|
|
COMPRESSION_TYPE_NULL,
|
|
COMPRESSION_TYPE_RDC,
|
|
COMPRESSION_TYPE_ZLIB,
|
|
NUM_COMPRESSION_TYPES ///< Number of compression types.
|
|
};
|
|
|
|
//! Default constructor.
|
|
ACTIV_FRAMEWORK_API Multicast();
|
|
|
|
String m_url; ///< Of the form: apd://multicast-group:port.
|
|
String m_interfaceAddress; ///< Local interface to bind to.
|
|
UInt m_socketTxBufferSize; ///< Default undefined; leave as OS default.
|
|
UInt m_socketRxBufferSize; ///< Default 1MB.
|
|
uint16_t m_flushByteThreshold; ///< Default: 1472. Flush tx buffer when >= this; set to the MTU if 0.
|
|
TimeoutPeriod m_blockingTimeout; ///< Default 50ms.
|
|
bool m_shouldTransmit; ///< Transmit on this group? Default true.
|
|
bool m_shouldListen; ///< Receive on this group? Default false.
|
|
size_t m_ttl; ///< Ttl for transmission. Default is 4.
|
|
CompressionType m_txCompressionType; ///< Default COMPRESSION_TYPE_NONE.
|
|
ProcessorAffinity m_threadProcessorAffinity; ///< Default: do not adjust.
|
|
};
|
|
|
|
/**
|
|
* @brief Subscribe to a subject.
|
|
*
|
|
* Note subscriptions from a component are not cumulative at the same scope level. However, subscribing to the
|
|
* same subject at more than one scope requires unsubscribing at each scope.
|
|
*
|
|
* @param component the component wishing to subscribe.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only receive messages published within this agent space,
|
|
* AGENT_SCOPE_GLOBAL receive both local and messages published onto the network, AGENT_SCOPE_REMOTE only receive
|
|
* messages published remotely.
|
|
* @param subject subject to subscribe to.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Subscribe(const Component &component, const AgentScope agentScope,
|
|
const Subject &subject);
|
|
|
|
/**
|
|
* @brief Unsubscribe from a subject.
|
|
*
|
|
* @param component the component wishing to unsubscribe.
|
|
* @param agentScope the scope from which to unsubscribe.
|
|
* @param subject the subject to unsubscribe from.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Unsubscribe(const Component &component, const AgentScope agentScope,
|
|
const Subject &subject);
|
|
|
|
/**
|
|
* @brief Publish a message.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param messageBuilder reference to a MessageBuilder containing the message body to publish.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject,
|
|
const MessageType type, const MessageBuilder &messageBuilder);
|
|
|
|
/**
|
|
* @brief Publish a message.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param pData pointer to message body.
|
|
* @param dataLength length of message body.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject,
|
|
const MessageType type, const void *pData = 0, const size_t dataLength = 0);
|
|
|
|
/**
|
|
* @brief Publish a message.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param heapMessage HeapMessage containing message body to publish.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS. heapMessage will no longer have a message attached.
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, const AgentScope agentScope, const Subject &subject,
|
|
const MessageType type, HeapMessage &heapMessage);
|
|
|
|
/**
|
|
* @brief Publish a message via a PostMessageHelper object.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here
|
|
* and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will
|
|
* need to be called at some point in order to push any queued messages to the PubSubService.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param messageBuilder reference to a MessageBuilder containing the message body to publish.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval STATUS_CODE_HEAP_EMTPY
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, PostMessageHelper &postMessageHelper,
|
|
const AgentScope agentScope, const Subject &subject, const MessageType type, const MessageBuilder &messageBuilder);
|
|
|
|
/**
|
|
* @brief Publish a message via a PostMessageHelper object.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here
|
|
* and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will
|
|
* need to be called at some point in order to push any queued messages to the PubSubService.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param pData pointer to message body.
|
|
* @param dataLength length of message body.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval STATUS_CODE_HEAP_EMTPY
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode Publish(const Component &component, PostMessageHelper &postMessageHelper,
|
|
const AgentScope agentScope, const Subject &subject, const MessageType type, const void *pData = 0,
|
|
const size_t dataLength = 0);
|
|
|
|
/**
|
|
* @brief Publish a message via a PostMessageHelper object.
|
|
*
|
|
* @param component the component wishing to publish.
|
|
* @param postMessageHelper reference to a PostMessageHelper. The published message will be queued here
|
|
* and not immediately sent to the PubSubService for distribution. postMessageHelper.Flush() will
|
|
* need to be called at some point in order to push any queued messages to the PubSubService.
|
|
* @param agentScope AGENT_SCOPE_LOCAL only publish locally within this agent space, AGENT_SCOPE_REMOTE
|
|
* only publish onto the network, AGENT_SCOPE_GLOBAL publish locally & remotely.
|
|
* @param subject subject of published message.
|
|
* @param type type of published message.
|
|
* @param heapMessage HeapMessage containing message body to publish.
|
|
*/
|
|
ACTIV_FRAMEWORK_API static void Publish(const Component &component, PostMessageHelper &postMessageHelper,
|
|
const AgentScope agentScope, const Subject &subject, const MessageType type, HeapMessage &heapMessage);
|
|
|
|
/**
|
|
* @brief Get subscriptions.
|
|
*
|
|
* @param component the component requesting subscriptions.
|
|
* @param subject the subject to get the subscriptions for.
|
|
* @param shouldRecurseTree whether to get subscriptions for entire subject tree.
|
|
* @param subscriptionMap reference to the subscription map to receive subscriptions.
|
|
* @param timeout timeout in ms.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode GetSubscriptions(const Component &component, const Subject &subject,
|
|
const bool shouldRecurseTree, SubscriptionMap &subscriptionMap, const TimeoutPeriod timeout = COMPONENT_DEFAULT_TIMEOUT);
|
|
|
|
/**
|
|
* @brief Add a multicast input/output.
|
|
*
|
|
* If the provided name is already configured as a multicast output, an error is returned.
|
|
*
|
|
* @param component
|
|
* @param name a name for the multicast.
|
|
* @param multicast describing the group, port, interface, etc.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode AddMulticast(const Component &component, const String &name,
|
|
const Multicast &multicast);
|
|
|
|
/**
|
|
* @brief Republish a Subject on a given named multicast output.
|
|
*
|
|
* @param component
|
|
* @param subject the Subject to publish output on the multicast @a multicastName.
|
|
* @param multicastName as passed to AddMulticast() or from static configuration of the PubSubService.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API static StatusCode AddSubjectToMulticast(const Component &component, const Subject &subject,
|
|
const String &multicastName);
|
|
|
|
/**
|
|
* @brief Append a trailing Subject::SEPARATOR_CHAR to a subject if required.
|
|
*
|
|
* @param subject subject string to modify in-place.
|
|
*
|
|
* @return false if the subject is invalid.
|
|
*/
|
|
ACTIV_FRAMEWORK_API static bool BuildFullyQualifiedSubject(String &subject);
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Scoped subscription helper.
|
|
*/
|
|
class ScopedSubscription : private Boost::noncopyable
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param component
|
|
*/
|
|
ACTIV_FRAMEWORK_API ScopedSubscription(const Component &component);
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* Subscribes the component to the given subject at the given scope.
|
|
*
|
|
* @param component
|
|
* @param agentScope
|
|
* @param subject
|
|
*
|
|
* @throw Exception if unable to subscribe.
|
|
*/
|
|
ACTIV_FRAMEWORK_API ScopedSubscription(const Component &component, const AgentScope agentScope, const Subject &subject);
|
|
|
|
/**
|
|
* @brief Destructor.
|
|
*
|
|
* Unsubscribes if the subscription is still in place.
|
|
*/
|
|
ACTIV_FRAMEWORK_API ~ScopedSubscription();
|
|
|
|
/**
|
|
* @brief Subscribes. Will unsubscribe if already subscribed.
|
|
*
|
|
* @return STATUS_CODE_SUCCESS or reason for failed subscription.
|
|
*/
|
|
ACTIV_FRAMEWORK_API StatusCode Subscribe(const AgentScope agentScope, const Subject &subject);
|
|
|
|
/**
|
|
* @brief Unsubscribes.
|
|
*
|
|
* @return STATUS_CODE_SUCCESS or reason for failed unsubscription.
|
|
*/
|
|
ACTIV_FRAMEWORK_API StatusCode Unsubscribe();
|
|
|
|
//! Is subscribed.
|
|
bool IsSubscribed() const;
|
|
|
|
private:
|
|
const Component & m_component;
|
|
AgentScope m_agentScope;
|
|
Subject m_subject;
|
|
bool m_isSubscribed;
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline bool ScopedSubscription::IsSubscribed() const
|
|
{
|
|
return m_isSubscribed;
|
|
}
|
|
|
|
} // namespace Activ
|
|
|
|
#endif // (!defined ACTIV_FRAMEWORK_PUB_SUB_SERVICE_API_H)
|