DDS  ver. 3.5.3.8.g5fe284b
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...
 
std::string userDefaultsGetValueForKey (const std::string &_key) const noexcept
 This method returns a configuration value for a given configuration key. It uses the DDS configuration of the current session. 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();
Example4: DDS User defaults. Retrieving DDS log directory on the commander server within an active
session.
CSession session;
boost::uuids::uuid sid = session.create();
cout << session.userDefaultsGetValueForKey("server.log_dir") << endl;
output> $HOME/.DDS/log/sessions/b383d852-19a7-4ac5-9cbe-dc00d686d36f
Example5: DDS User defaults. Retrieving DDS log directory without attaching to a session.
CSession session;
cout << session.userDefaultsGetValueForKey("server.log_dir") << endl;
output> $HOME/.DDS/log

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.

◆ userDefaultsGetValueForKey()

std::string CSession::userDefaultsGetValueForKey ( const std::string &  _key) const
noexcept

This method returns a configuration value for a given configuration key. It uses the DDS configuration of the current session.

Note
Please note, if the session is not created/attached then keys, which depend on sessions, will return values without session IDs. see. Example4 and Example5
Parameters
[in]_keyConfiguration key. For example, to get the current working directory on the commander server use "server.work_dir". Currently support configuration keys can be found in the User's manual "Chapter 5. Configuration".
Returns
A string value of the given configuration key or an empty string if the key is invalid.
Exceptions
Doesn'tthrow

◆ 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: