DDS  ver. 3.4
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
dds::tools_api::CSession Class Reference

The main class of the Tools API. It represets a DDS session. More...

#include <Tools.h>

Classes

struct  SImpl
 

Public Types

enum  EAgentState { EAgentState::active = 0, EAgentState::idle, EAgentState::executing }
 

Public Member Functions

 CSession ()
 Constructor of a DDS Session class. More...
 
 ~CSession ()
 A destructor. More...
 
boost::uuids::uuid create ()
 Creates a new DDS session. More...
 
void attach (const std::string &_sid)
 Attaches to an existing DDS session. More...
 
void attach (const boost::uuids::uuid &_sid)
 Attaches to an existing DDS session. More...
 
void shutdown ()
 Shutdown currently attached DDS session. More...
 
void detach ()
 Detach from the session without shutting it down. More...
 
bool IsRunning () const
 Check if DDS session is running. More...
 
boost::uuids::uuid getSessionID () const
 Returns DDS session ID. More...
 
void blockCurrentThread ()
 blockCurrentThread Blocks current thread. More...
 
void unblockCurrentThread ()
 Stop DDS session. More...
 
template<class T >
void sendRequest (typename T::ptr_t _request)
 Sends the async request to DDS commander. More...
 
template<class Request_t >
void syncSendRequest (const typename Request_t::request_t &_requestData, const std::chrono::seconds &_timeout=std::chrono::seconds(0), std::ostream *_out=nullptr)
 Sends the sync request to DDS commander. More...
 
template<class Request_t >
void syncSendRequest (const typename Request_t::request_t &_requestData, typename Request_t::response_t &_responseData, const std::chrono::seconds &_timeout=std::chrono::seconds(0), std::ostream *_out=nullptr)
 Sends the sync request to DDS commander. More...
 
template<class Request_t >
void syncSendRequest (const typename Request_t::request_t &_requestData, typename Request_t::responseVector_t &_responseDataVector, const std::chrono::seconds &_timeout=std::chrono::seconds(0), std::ostream *_out=nullptr)
 Sends the sync request to DDS commander. More...
 
template<CSession::EAgentState _state>
void waitForNumAgents (size_t _numAgents, const std::chrono::seconds &_timeout=std::chrono::seconds(0), const std::chrono::milliseconds &_requestInterval=std::chrono::milliseconds(500), std::ostream *_out=nullptr)
 Wait for the required number of agents with a certain state. More...
 
template<CSession::EAgentState _state>
void waitForNumAgents (size_t _numAgents, const std::chrono::seconds &_timeout, const std::chrono::milliseconds &_requestInterval, ostream *_out)
 

Static Public Member Functions

static std::string getDefaultSessionIDString ()
 Returns the default DDS session ID as a string. More...
 
static boost::uuids::uuid getDefaultSessionID ()
 Returns the default DDS session ID. More...
 

Detailed Description

The main class of the Tools API. It represets a DDS session.

It can be used to create new DDS sessions or attach to existing ones. Also, this class can be used to send and recieve Tools commands. Currently the following commands are ToolsProtocol.h

Please note, when you send a requests, server will respond with a corresponding reply with a following Done event. But the server can also send an error message. Once you receive either Done or an error, don't expect the server to send anything else in the regards of the request. So, you can then stop the API or send another request.

Example1: Create a new DDS session, spawn 10 localhost agents
CSession session;
// Create a DDS session
boost::uuids::uuid sessionID = session.create();
// Create submit request to spawn agents
submitInfo.m_config = "";
submitInfo.m_rms = "localhost";
submitInfo.m_instances = "10";
submitInfo.m_pluginPath = "";
SSubmitRequest::ptr_t submitRequestPtr = SSubmitRequest::makeRequest(submitInfo);
// Subscribe on text messages from DDS server
submitRequestPtr->setMessageCallback([&session](const SMessageResponseData& _message) {
cout << "Server reports: " << _message.m_msg << endl;
});
// Subscribe on Done evens.
// Server will send Done when there it has finsihed proccessing a corresponding request.
submitRequestPtr->setDoneCallback([&session, &start]() {
auto end = chrono::high_resolution_clock::now();
chrono::duration<double, std::milli> elapsed = end - start;
cout << "Submission took: " << elapsed.count() << " ms\n";
session.unblockCurrentThread();
});
// Send request to commander
session.sendRequest<SSubmitRequest>(submitRequestPtr);
// Start API processor and block.
// Blocking is optional, if you have your own internal loop in the app to keep the session object alive
session.blockCurrentThread();
Example2: Attach to an existing DDS session and request the number of running agent
CSession session;
// Attach to a DDS sesion with sessionID = 446b4183-1313-4648-99aa-4f8fae81311c
session.attach("446b4183-1313-4648-99aa-4f8fae81311c");
SAgentInfoRequest::ptr_t agentInfoRequestPtr = SAgentInfoRequest::makeRequest();
// Subscribe on text messages from DDS server
agentInfoRequestPtr->setMessageCallback([&session](const SMessageResponseData& _message) {
cout << "Server reports: " << _message.m_msg << endl;
});
// Subscribe on Done event.
// Server sends Done when it has finsihed proccessing the request.
agentInfoRequestPtr->setDoneCallback([&session]() {
session.unblockCurrentThread();
});
// Subscribe on AgentInfo events
agentInfoRequestPtr->setResponseCallback([&session](const SAgentInfoRequest::response_t& _info) {
cout << _info.m_activeAgentsCount << endl;
});
// Send request to commander
session.sendRequest<SAgentInfoRequest>(agentInfoRequestPtr);
session.blockCurrentThread();
Example3: Sync Tools API example
const string topoFile("property_test.xml");
const std::chrono::seconds timeout(20);
const std::chrono::milliseconds requestInterval(500);
CSession session;
boost::uuids::uuid sid = session.create();
CTopology topo(topoFile);
size_t numAgents = topo.getRequiredNofAgents();
submitInfo.m_rms = "localhost";
submitInfo.m_instances = numAgents;
session.syncSendRequest<SSubmitRequest>(submitInfo, timeout, &std::cout);
session.waitForNumAgents<CSession::EAgentState::idle>(numAgents, timeout, requestInterval, &std::cout);
topoInfo.m_topologyFile = topoFile;
topoInfo.m_updateType = STopologyRequest::request_t::EUpdateType::ACTIVATE;
session.syncSendRequest<STopologyRequest>(topoInfo, timeout, &std::cout);
session.waitForNumAgents<CSession::EAgentState::idle>(numAgents, timeout, requestInterval, maxRequests,
&std::cout);
session.shutdown();

Member Enumeration Documentation

◆ EAgentState

Enumerator
active 
idle 
executing 

Constructor & Destructor Documentation

◆ CSession()

CSession::CSession ( )

Constructor of a DDS Session class.

◆ ~CSession()

CSession::~CSession ( )

A destructor.

Member Function Documentation

◆ attach() [1/2]

void CSession::attach ( const std::string &  _sid)

Attaches to an existing DDS session.

Parameters
[in]_sidA destination DDS session ID

◆ attach() [2/2]

void CSession::attach ( const boost::uuids::uuid &  _sid)

Attaches to an existing DDS session.

Parameters
[in]_sidA destination DDS session ID

◆ blockCurrentThread()

void CSession::blockCurrentThread ( )

blockCurrentThread Blocks current thread.

The function stops the thread and waits until one of the conditions is applied:

  1. 10 minutes timeout;
  2. Failed connection to DDS commander or disconnection from DDS commander;
  3. Explicit call of stop() function.
Note
If there are no subscribers function doesn't wait.

◆ create()

boost::uuids::uuid CSession::create ( )

Creates a new DDS session.

◆ detach()

void CSession::detach ( )

Detach from the session without shutting it down.

◆ getDefaultSessionID()

boost::uuids::uuid CSession::getDefaultSessionID ( )
static

Returns the default DDS session ID.

Returns
DDS session ID or nil_uuid if no default session is yet set

◆ getDefaultSessionIDString()

string CSession::getDefaultSessionIDString ( )
static

Returns the default DDS session ID as a string.

Returns
DDS session ID or an empty if no default session is yet set

◆ getSessionID()

boost::uuids::uuid CSession::getSessionID ( ) const

Returns DDS session ID.

Returns
DDS session ID

◆ IsRunning()

bool CSession::IsRunning ( ) const

Check if DDS session is running.

◆ sendRequest()

template<class T >
template void CSession::sendRequest< SAgentCountRequest > ( typename T::ptr_t  _request)

Sends the async request to DDS commander.

Parameters
[in]_requestRequest object. If _request is nullptr than throws std::runtime_error

◆ shutdown()

void CSession::shutdown ( )

Shutdown currently attached DDS session.

◆ syncSendRequest() [1/3]

template<class Request_t >
void CSession::syncSendRequest ( const typename Request_t::request_t &  _requestData,
const std::chrono::seconds &  _timeout = std::chrono::seconds(0),
std::ostream *  _out = nullptr 
)

Sends the sync request to DDS commander.

Parameters
[in]_requestDataRequest data object.
[in]_timeoutTimeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]_outPointer to output stream. nullptr means no output to stream (default).
Exceptions
std::runtime_error

◆ syncSendRequest() [2/3]

template<class Request_t >
void CSession::syncSendRequest ( const typename Request_t::request_t &  _requestData,
typename Request_t::response_t &  _responseData,
const std::chrono::seconds &  _timeout = std::chrono::seconds(0),
std::ostream *  _out = nullptr 
)

Sends the sync request to DDS commander.

Parameters
[in]_requestDataRequest data object.
[out]_responseDataResponse data object.
[in]_timeoutTimeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]_outPointer to output stream. nullptr means no output to stream (default).
Exceptions
std::runtime_error

◆ syncSendRequest() [3/3]

template<class Request_t >
void CSession::syncSendRequest ( const typename Request_t::request_t &  _requestData,
typename Request_t::responseVector_t &  _responseDataVector,
const std::chrono::seconds &  _timeout = std::chrono::seconds(0),
std::ostream *  _out = nullptr 
)

Sends the sync request to DDS commander.

Parameters
[in]_requestDataRequest data object.
[out]_responseDataVectorVector of response data object.
[in]_timeoutTimeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]_outPointer to output stream. nullptr means no output to stream (default).
Exceptions
std::runtime_error

◆ unblockCurrentThread()

void CSession::unblockCurrentThread ( )

Stop DDS session.

◆ waitForNumAgents() [1/2]

template<CSession::EAgentState _state>
void dds::tools_api::CSession::waitForNumAgents ( size_t  _numAgents,
const std::chrono::seconds &  _timeout = std::chrono::seconds(0),
const std::chrono::milliseconds &  _requestInterval = std::chrono::milliseconds(500),
std::ostream *  _out = nullptr 
)

Wait for the required number of agents with a certain state.

Parameters
[in]_numAgentsRequired number of agents. Must be > 0.
[in]_timeoutTimeout per each request and total timeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]_requestIntervalInterval between SAgentCountRequest requests in milliseconds.
[in]_outPointer to output stream. nullptr means no output to stream (default).
Exceptions
std::runtime_error

◆ waitForNumAgents() [2/2]

template<CSession::EAgentState _state>
void dds::tools_api::CSession::waitForNumAgents ( size_t  _numAgents,
const std::chrono::seconds &  _timeout,
const std::chrono::milliseconds &  _requestInterval,
ostream *  _out 
)

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