Files

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)