hmbdc
simplify-high-performance-messaging-programming
 All Classes Namespaces Functions Variables Friends Pages
Public Member Functions | Private Member Functions | Friends | List of all members
hmbdc::app::udpcast::NetContext Class Reference

a singleton that holding udpcast resources More...

#include <NetContext.hpp>

Inheritance diagram for hmbdc::app::udpcast::NetContext:
hmbdc::pattern::GuardedSingleton< NetContext > hmbdc::app::utils::NetContextUtil

Public Member Functions

SendTransportEnginecreateSendTransportEngine (Config const &cfgIn, size_t maxMessageSize)
 construct a send transport engine (and remember it within the class) More...
 
SendTransportEnginecreateSendTransportEngineTuply (Config const &cfg, size_t maxMessageSize, std::tuple<> args)
 same as above but provide a unified interface - not preferred More...
 
template<typename Buffer , typename MsgArbitrator = RecvTransport::NoOpArb>
auto createRecvTransportEngine (Config const &cfgIn, Buffer &buffer, MsgArbitrator &&arb=RecvTransport::NoOpArb())
 construct a recv transport and remember it More...
 
template<typename Buffer , typename ArgsTuple >
auto createRecvTransportEngineTuply (Config const &cfg, Buffer &buffer, ArgsTuple &&args)
 same as above but to provide a unified interface - not preferred More...
 
SendergetSender (Topic const &t=Topic("_"))
 get (or create for the first time) a Sender - whose function is to send messages on its associated Topic More...
 
void listenTo (Topic const &t)
 This process is interested in a Topic. More...
 
void stopListenTo (Topic const &t)
 undo the subscription More...
 

Private Member Functions

template<typename CcContext >
 NetContext (CcContext &ctx, Config::Base cfgIn=Config::Base{}, char const *sendSec=nullptr, char const *recvSec=nullptr, size_t maxMessageSize=0, uint8_t runningUsingThreadIndex=0, char const *listenToTopic="_")
 this ctor is to create some commonly used basic engine setup to start with. This is private and only meant to be used through SingletonGuardian, see in example chat.cpp

Config config; //other config values are default
config.put("ifaceAddr", ifaceAddr);//which interface to use for communication
config.put("loopback", true); //could be chatting on the same machine
Context<sizeof(ChatMessage)> ctx; //large enough to hold ChatMessage's
//create NetContext with initial tx/rx capabilities, and listen to the default topic "_"
//received network messages goes to ctx. this launches a thread to power the above engines
SingletonGuardian<tcpcast::NetContext> g(ctx, config); //RAII for tcpcast::NetContext resources
More...
 
 NetContext ()
 this is for users that want finer control of engine creation - from a blank NetContext. More...
 

Friends

struct hmbdc::pattern::SingletonGuardian< NetContext >
 

Detailed Description

a singleton that holding udpcast resources

it manages transport engines

Examples:
server-cluster.cpp.

Constructor & Destructor Documentation

template<typename CcContext >
hmbdc::app::udpcast::NetContext::NetContext ( CcContext &  ctx,
Config::Base  cfgIn = Config::Base{},
char const *  sendSec = nullptr,
char const *  recvSec = nullptr,
size_t  maxMessageSize = 0,
uint8_t  runningUsingThreadIndex = 0,
char const *  listenToTopic = "_" 
)
inlineprivate

this ctor is to create some commonly used basic engine setup to start with. This is private and only meant to be used through SingletonGuardian, see in example chat.cpp

Config config; //other config values are default
config.put("ifaceAddr", ifaceAddr);//which interface to use for communication
config.put("loopback", true); //could be chatting on the same machine
Context<sizeof(ChatMessage)> ctx; //large enough to hold ChatMessage's
//create NetContext with initial tx/rx capabilities, and listen to the default topic "_"
//received network messages goes to ctx. this launches a thread to power the above engines
SingletonGuardian<tcpcast::NetContext> g(ctx, config); //RAII for tcpcast::NetContext resources

It creates one send transport engine and/or one recv transport engine based on cfgIn. and run them using a single OS thread indicated by runningUsingThreadIndex If recv engine is created, this method also automaticallly makes the NetContext listen to a default topic (listenToTopic).

Parameters
ctxa Context that manages the send / recv transport engines, and hold the received messages
cfgInoptional Config for the send AND recv transport engines
sendSecthe section name for send transport engine in above cfgIn, special values: nullptr - create send engine using no section config values "" - do not create send engine
recvSecthe section name for recv transport engine in above cfgIn nullptr - create recv engine using no section config values "" - do not create recv engine
maxMessageSizemax message size in bytes to be sent, if 0, uses ctx's maxMessageSize()
runningUsingThreadIndexsee details above
Template Parameters
CcContextctx Context type
hmbdc::app::udpcast::NetContext::NetContext ( )
inlineprivate

this is for users that want finer control of engine creation - from a blank NetContext.

it does not do anything that the previous ctor does

Member Function Documentation

template<typename Buffer , typename MsgArbitrator = RecvTransport::NoOpArb>
auto hmbdc::app::udpcast::NetContext::createRecvTransportEngine ( Config const &  cfgIn,
Buffer &  buffer,
MsgArbitrator &&  arb = RecvTransport::NoOpArb() 
)
inline

construct a recv transport and remember it

After this, user is responsible to get it started within a hmbdc Context, or rotated continously.

Parameters
cfgInjason specifing the transport - see hmbdc/app/udpcast/DefaultUserConfig.hpp
bufferbuffer that recv messages go, normally the one returned by app::Context::buffer()
arboptonally an arbitrator to decide which messages to keep and drop if arb is an rvalue, it is passed in value, if an lvalue, passed in as reference; it supports either udp packet (BEFORE topic filtering) or hmbdc message (AFTER topic filtering) level arbitration depending on which one of int operator()(void* bytes, size_t len) and int operator()(TransportMessageHeader const* header) presents in the arb passed in trasnport engines, see ctor of RecvTransportEngineImpl for details see in example use in udpcast-sniff.cpp
auto eng = udpcast::NetContext::instance().createRecvTransportEngine(config
, ctx.buffer()
//the lambda below provides the 'filter' before the packet gets to hmbdc processing
, [](void* packet, size_t len) {
auto buf = (uint8_t*)(packet);
size_t l = 0;
cout << "packet size=" << len;
while (l != len) {
cout << ' ' << boost::format("%02x") % (uint16_t)buf[l++];
}
cout << endl;
return -1; //-1 - drops the packet
//1 - keep
//0 - cannot decide, ask me later
//we already dumped it out - drop it now, no further processing
}
);
see in example use in server-cluster.cpp
auto rengine = net.createRecvTransportEngine(requestConfig
, ctx.buffer() //put the incoming messsage into server context's buffer
//a receive engine can optionally decide what messages to drop/keep by
//the following
, [](TransportMessageHeader const* h) { //only keep messages in my range
if (h->typeTag() == Request::typeTag) {
auto& m = h->wrapped<Request>();
uint8_t c = (uint8_t) m.word[0];
//basically covers everything ascii here
//to scale the server to multiple hosts, each host could handle a range partition
//so they collectively cover the whole range
if (c >= 0 && c <= 127) {
return 1; //good
}
}
return -1; //ignore
}
);
Returns
a pointer to the Engine
template<typename Buffer , typename ArgsTuple >
auto hmbdc::app::udpcast::NetContext::createRecvTransportEngineTuply ( Config const &  cfg,
Buffer &  buffer,
ArgsTuple &&  args 
)
inline

same as above but to provide a unified interface - not preferred

use forward_as_tuple to make the tuple passed in

Returns
a pointer to the Engine
SendTransportEngine* hmbdc::app::udpcast::NetContext::createSendTransportEngine ( Config const &  cfgIn,
size_t  maxMessageSize 
)
inline

construct a send transport engine (and remember it within the class)

After this, user is responsible to get it started within a hmbdc Context, or rotated continously. Don't create the same thing twice

Parameters
cfgInconfig specifing the transport - hmbdc/app/udpcast/DefaultUserConfig.hpp
maxMessageSizemax messafe size in bytes to be sent trasnport engines, see ctor of SendTransportEngine for details
Returns
a pointer to the Engine - don't delete it
SendTransportEngine* hmbdc::app::udpcast::NetContext::createSendTransportEngineTuply ( Config const &  cfg,
size_t  maxMessageSize,
std::tuple<>  args 
)
inline

same as above but provide a unified interface - not preferred

Returns
a pointer to the Engine - don't delete it
Sender* hmbdc::app::udpcast::NetContext::getSender ( Topic const &  t = Topic("_"))
inline

get (or create for the first time) a Sender - whose function is to send messages on its associated Topic

this operation typically might be slow, so caching the return value is recommended.

Parameters
t- the Topic that the Sender is for - default to be "_"
void hmbdc::app::udpcast::NetContext::listenTo ( Topic const &  t)
inline

This process is interested in a Topic.

Normally the receiving transport covering this topic needs to be created - not necessarily running - before calling this

Parameters
tTopic interested
void hmbdc::app::udpcast::NetContext::stopListenTo ( Topic const &  t)
inline

undo the subscription

Parameters
tTopic

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