hmbdc
simplify-high-performance-messaging-programming
Classes | Public Member Functions | List of all members
hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator > Struct Template Reference

Messages published on a TIPS pub/sub domain reach all the Nodes within that domain based on their subscriptions. This class represents a TIPS domain's handle / interface / fascade in its process. Typically - by recommendation - there is just a single Domain object for a specific TIPS domain within a process. More...

#include <Domain.hpp>

Classes

struct  InBandMemoryAttachmentProcessor
 
struct  OneBuffer
 
class  PumpInIpcPortal
 
class  PumpInThreadCtx
 

Public Member Functions

 Domain (app::Config const &cfg)
 Construct a new Domain object. More...
 
template<typename... Args>
bool runOnce (size_t pumpIndex, Args &&...args)
 manually drive the domain's pumps More...
 
template<typename CcNode >
void addPubSubFor (CcNode const &node)
 configure the subscriptions and advertisement for a Node More...
 
template<typename SendMessageTuple >
void addPub ()
 configure the advertisement with message types directly This is when you do not want to involve a Node for publish, otherwise use addPubSubFor More...
 
template<typename Node >
void start (Node &node, size_t capacity=1024, time::Duration maxBlockingTime=time::Duration::seconds(1), uint64_t cpuAffinity=0)
 start a Node within this Domain as a thread - handles its subscribing here too More...
 
void startDelayedPumping ()
 if pumpRunMode is set to be delayed this function start all the pumps
 
template<typename LoadSharingNodePtrIt >
void startPool (LoadSharingNodePtrIt begin, LoadSharingNodePtrIt end, size_t capacity=1024, time::Duration maxBlockingTime=time::Duration::seconds(1), uint64_t cpuAffinity=0)
 start a group of Nodes as a thread pool within the Domain that collectively processing messages in a load sharing manner. Each Node is powered by a single OS thread. More...
 
size_t ipcPartyDetectedCount () const
 how many IPC parties (processes) have been detected by this context More...
 
size_t netSendingPartyDetectedCount () const
 how many network parties (processes) are ready to send messages to this Domain More...
 
size_t netRecvingPartyDetectedCount () const
 how many network parties (processes) are ready to receive messages from this Domain More...
 
size_t ipcSubscribingPartyCount (uint16_t tag) const
 how many nodes on local machine have the message tag marked as subscribed excluding Nodes managed by this Domain instance More...
 
size_t netSubscribingPartyCount (uint16_t tag) const
 how many processes connecting thru network have the message tag marked as subscribed More...
 
template<MessageC Message>
void publish (Message &&m)
 publish a message through this Domain, all the Nodes in the TIPS domain could get it if it subscribed to the Message type More...
 
void publishJustBytes (uint16_t tag, void const *bytes, size_t len, app::hasMemoryAttachment *att)
 publish a message using byte format on this Domain - not recommended More...
 
template<MessageForwardIterC ForwardIt>
void publish (ForwardIt begin, size_t n)
 publish a sequence of message of the same type through this Domain, all the Nodes in the TIPS domain could get it if it subscribed to the Message type More...
 
template<MessageC Message, typename T , typename ... Args>
void allocateInShmFor0cpy (hasSharedPtrAttachment< Message, T > &att, size_t actualSize, Args &&...args)
 allocate in shm for a hasSharedPtrAttachment to be publioshed later The release of it is auto handled in TIPS More...
 
bool ownIpcTransport () const
 if the Domain object owns the IPC transport More...
 
void stop ()
 stop the Domain and its Message delivery functions More...
 
void join ()
 wait for all the Node threads to stop
 

Detailed Description

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
struct hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >

Messages published on a TIPS pub/sub domain reach all the Nodes within that domain based on their subscriptions. This class represents a TIPS domain's handle / interface / fascade in its process. Typically - by recommendation - there is just a single Domain object for a specific TIPS domain within a process.

A Domain object also manages a group of Nodes on their communication across the TIPS domain that this Domain object maps to. The TIPS domain is determined by the network configurations such as which NIC interface and multicast addresses configured. see getTipsDomainName for network transport protocol

A Node can only be managed (be started) within a single Domain. A Domain instance can only be configured to map to a single TIPS domain Multiple Domain objects could be mapped to a single TIPS domain - in one (not recommended) or multiple processes on the same or different networked hosts.

Template Parameters
RecvMessageTupleIna std tuple that lists all the receiving message types Any inbound messages (to the Domain) that are not within this list are dropped without being deliverred to the Nodes in this Domain
IpcPropIPC preoperty - see ipc_property template
NetPropNetwork communication properties - see net_property template
NodeContextthe template that manages the nodes and accepts the inter thread messages
AttachmentAllocatorthe memory allocation policy for attachment - see DefaultAttachmentAllocator
Examples:
hello-world.cpp.

Constructor & Destructor Documentation

◆ Domain()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::Domain ( app::Config const &  cfg)
inline

Construct a new Domain object.

Parameters
cfgThe Jason configuration to specify the IPC and network transport details See the DefaultUserConfiguration.hpp files for each transport type

Member Function Documentation

◆ addPub()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<typename SendMessageTuple >
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::addPub ( )
inline

configure the advertisement with message types directly This is when you do not want to involve a Node for publish, otherwise use addPubSubFor

Template Parameters
SendMessageTuple

◆ addPubSubFor()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<typename CcNode >
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::addPubSubFor ( CcNode const &  node)
inline

configure the subscriptions and advertisement for a Node

typically this is automatically done when the Node is started unless the Node wants to do this step at an earlier or later stage, this could be manually called at that time. Threadsafe call.

Template Parameters
CcNodethe Node type
Parameters
nodethe Node

◆ allocateInShmFor0cpy()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<MessageC Message, typename T , typename ... Args>
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::allocateInShmFor0cpy ( hasSharedPtrAttachment< Message, T > &  att,
size_t  actualSize,
Args &&...  args 
)
inline

allocate in shm for a hasSharedPtrAttachment to be publioshed later The release of it is auto handled in TIPS

Template Parameters
MessagehasSharedPtrAttachment tparam
ThasSharedPtrAttachment tparam - it needs to contain "size_t hmbdc0cpyShmRefCount" as the first data member - won't compile otherwise
Argsargs for T's ctor
Parameters
attthe message holds the shared memory
actualSizeT's actual size in bytes - could be > sizeof(T) for open ended struct
argsargs for T's ctor

sender

◆ ipcPartyDetectedCount()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
size_t hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::ipcPartyDetectedCount ( ) const
inline

how many IPC parties (processes) have been detected by this context

Returns
size_t

◆ ipcSubscribingPartyCount()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
size_t hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::ipcSubscribingPartyCount ( uint16_t  tag) const
inline

how many nodes on local machine have the message tag marked as subscribed excluding Nodes managed by this Domain instance

Parameters
tag
Returns
size_t

◆ netRecvingPartyDetectedCount()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
size_t hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::netRecvingPartyDetectedCount ( ) const
inline

how many network parties (processes) are ready to receive messages from this Domain

Returns
size_t

◆ netSendingPartyDetectedCount()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
size_t hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::netSendingPartyDetectedCount ( ) const
inline

how many network parties (processes) are ready to send messages to this Domain

Returns
size_t

◆ netSubscribingPartyCount()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
size_t hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::netSubscribingPartyCount ( uint16_t  tag) const
inline

how many processes connecting thru network have the message tag marked as subscribed

Parameters
tag
Returns
size_t

◆ ownIpcTransport()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
bool hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::ownIpcTransport ( ) const
inline

if the Domain object owns the IPC transport

Returns
true if yes
false if no

◆ publish() [1/2]

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<MessageC Message>
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::publish ( Message &&  m)
inline

publish a message through this Domain, all the Nodes in the TIPS domain could get it if it subscribed to the Message type

Messages that are not trivially destructable are not deliverred outside of this process (No IPC and network paths). They are tried to be deliverred amoung the Nodes within local process only. enum of DisableSendMask could also be used to disable local, IPC or network paths.

Template Parameters
MessageThe type that need to fit into the max_message_size specified by the ipc_property and net_property. Its copy ctor is used to push it to the outgoing buffer. With that in mind, the user can do partial copy using the copy ctor to implement just publish the starting N bytes
Parameters
m

◆ publish() [2/2]

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<MessageForwardIterC ForwardIt>
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::publish ( ForwardIt  begin,
size_t  n 
)
inline

publish a sequence of message of the same type through this Domain, all the Nodes in the TIPS domain could get it if it subscribed to the Message type

It is recommended to use this method if publishing an array of Messages (particularly to a Node pool - see startPool() above) for performance Messages that are not trivially destructable are not deliverred outside of this process (No IPC and network paths). They are tried to be deliverred amoung the Nodes within local process though

Template Parameters
Message
Parameters
m

◆ publishJustBytes()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::publishJustBytes ( uint16_t  tag,
void const *  bytes,
size_t  len,
app::hasMemoryAttachment att 
)
inline

publish a message using byte format on this Domain - not recommended

Messages MUST be trivially destructable - no type based delivery features such as DisableSendMask are supported. It is not recommended to publish with att while the tag is also subscribed locally due to the complexity of att->release() will be called for each local recipient and 1 additonal time in Domain. publish via hasSharedPtrAttachment is always prefered

Parameters
tag- type tag
bytes- bytes of the message contents - must match the message already constructed binary wise (hasMemoryAttachment, inTagRange must be considered
  • user needs to add those leading bytes to match binary wise)
len- len of the above buffer
att- if the message type is derived from hasMemoryAttachment, explictly provides the ptr here, otherwise must be nullptr it is user's responsibility to make sure att->afterConsumedCleanupFunc works even multiple att->release() is called

◆ runOnce()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<typename... Args>
bool hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::runOnce ( size_t  pumpIndex,
Args &&...  args 
)
inline

manually drive the domain's pumps

Template Parameters
Argsthe arguments used for pump
Parameters
pumpIndexwhich pump - see pumpCount configure
argsthe arguments used for pump
Returns
true if pump runs fine
false either Domain stopped or exception thrown

◆ start()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<typename Node >
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::start ( Node node,
size_t  capacity = 1024,
time::Duration  maxBlockingTime = time::Duration::seconds(1),
uint64_t  cpuAffinity = 0 
)
inline

start a Node within this Domain as a thread - handles its subscribing here too

Template Parameters
Nodea concrete Node type that send and/or recv Messages
Parameters
nodethe instance of the node - the Domain does not manage the object lifespan
capacitythe inbound message buffer depth - if the buffer is full the delivery mechanism is blocked until the buffer becomes available
maxBlockingTimeThe node wakes up periodically even there is no messages for it so its thread can respond to Domain status change - like stopping
cpuAffinityThe CPU mask that he Node thread assigned to

◆ startPool()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
template<typename LoadSharingNodePtrIt >
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::startPool ( LoadSharingNodePtrIt  begin,
LoadSharingNodePtrIt  end,
size_t  capacity = 1024,
time::Duration  maxBlockingTime = time::Duration::seconds(1),
uint64_t  cpuAffinity = 0 
)
inline

start a group of Nodes as a thread pool within the Domain that collectively processing messages in a load sharing manner. Each Node is powered by a single OS thread.

Template Parameters
LoadSharingNodePtrItiterator to a Node pointer
Parameters
beginan iterator, **begin should produce a Node& for the first Node
endan end iterator, [begin, end) is the range for Nodes
capacitythe maximum messages this Node can buffer
cpuAffinitycpu affinity mask for this Node's thread
maxBlockingTimeit is recommended to limit the duration a Node blocks due to no messages to handle, so it can respond to things like Domain is stopped, or generate heartbeats if applicable.

◆ stop()

template<MessageTupleC RecvMessageTupleIn, typename IpcProp = NoIpc, typename NetProp = NoNet, template< class... > class NodeContext = app::BlockingContext, typename AttachmentAllocator = DefaultAttachmentAllocator>
void hmbdc::tips::Domain< RecvMessageTupleIn, IpcProp, NetProp, NodeContext, AttachmentAllocator >::stop ( )
inline

stop the Domain and its Message delivery functions

a Async operation - expected to use the join to see the effects


The documentation for this struct was generated from the following file: