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...

static void	setup ()
	Setups DDS environment. 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
SSubmitRequest::request_t submitInfo;
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();
SSubmitRequest::request_t submitInfo;
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);
STopologyRequest::request_t topoInfo;
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

Example5: Subscribe on TaskDone events: ...
// create a session
SOnTaskDoneRequest::request_t request;
SOnTaskDoneRequest::ptr_t requestPtr = SOnTaskDoneRequest::makeRequest(request);
int nTaskDoneCount{ 0 };
requestPtr->setResponseCallback(
[&nTaskDoneCount](const SOnTaskDoneResponseData& _info)
{
++nTaskDoneCount;
cout << "Recieved onTaskDone event. TaskID: " << _info.m_taskID
<< " ; ExitCode: " << _info.m_exitCode
<< " ; Signal: " << _info.m_signal;
});
session.sendRequest<SOnTaskDoneRequest>(requestPtr);
...

Example5: Request Agent shutdown by AgentID with a sync request: ...
// create a session
SAgentCommandRequest::request_t agentCmd;
agentCmd.m_commandType = SAgentCommandRequestData::EAgentCommandType::shutDownByID;
agentCmd.m_arg1 = <Given AgentID>;
session.syncSendRequest<SAgentCommandRequest>(agentCmd, kTimeout, &std::cout);
...

Member Enumeration Documentation

◆ EAgentState

enum dds::tools_api::CSession::EAgentState

strong

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] _sid A destination DDS session ID

◆ attach() [2/2]

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

Attaches to an existing DDS session.

Parameters

[in] _sid A 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:

10 minutes timeout;
Failed connection to DDS commander or disconnection from DDS commander;
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< SAgentCommandRequest > ( typename T::ptr_t _request )

Sends the async request to DDS commander.

Parameters

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

◆ setup()

void CSession::setup ( )

static

Setups DDS environment.

◆ 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]	_requestData	Request data object.
[in]	_timeout	Timeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]	_out	Pointer 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]	_requestData	Request data object.
[out]	_responseData	Response data object.
[in]	_timeout	Timeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]	_out	Pointer 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]	_requestData	Request data object.
[out]	_responseDataVector	Vector of response data object.
[in]	_timeout	Timeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]	_out	Pointer 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] _key Configuration 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't throw

◆ 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]	_numAgents	Required number of agents. Must be > 0.
[in]	_timeout	Timeout per each request and total timeout in seconds. Timeout of 0 means no timeout is applied (default).
[in]	_requestInterval	Interval between SAgentCountRequest requests in milliseconds.
[in]	_out	Pointer 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:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ EAgentState

Constructor & Destructor Documentation

◆ CSession()

◆ ~CSession()

Member Function Documentation

◆ attach() [1/2]

◆ attach() [2/2]

◆ blockCurrentThread()

◆ create()

◆ detach()

◆ getDefaultSessionID()

◆ getDefaultSessionIDString()

◆ getSessionID()

◆ IsRunning()

◆ sendRequest()

◆ setup()

◆ shutdown()

◆ syncSendRequest() [1/3]

◆ syncSendRequest() [2/3]

◆ syncSendRequest() [3/3]

◆ unblockCurrentThread()

◆ userDefaultsGetValueForKey()

◆ waitForNumAgents() [1/2]

◆ waitForNumAgents() [2/2]