An interface for classes that implement various versions of the master/slave communication protocol. More...

#include "coral/bus/slave_control_messenger.hpp"

Inheritance diagram for coral::bus::ISlaveControlMessenger:

Public Types
typedef std::function< void(const std::error_code &)>	VoidHandler
	Basic completion handler type without any arguments aside from an error code.

typedef std::function< void(const std::error_code &, const coral::model::SlaveDescription &)>	GetDescriptionHandler
	Completion handler type for GetDescription()

typedef VoidHandler	SetVariablesHandler
	Completion handler type for SetVariables()

typedef VoidHandler	SetPeersHandler
	Completion handler type for SetPeers()

typedef VoidHandler	ResendVarsHandler
	Completion handler type for ResendVars()

typedef VoidHandler	StepHandler
	Completion handler type for Step()

typedef VoidHandler	AcceptStepHandler
	Completion handler type for AcceptStep()

Public Member Functions
virtual	~ISlaveControlMessenger () CORAL_NOEXCEPT
	Destructor. More...

virtual SlaveState	State () const CORAL_NOEXCEPT=0
	Returns the current state of the slave, as deduced from the messages that have been sent to it and its replies (or lack thereof).

virtual void	Close ()=0
	Ends all communication with the slave. More...

virtual void	GetDescription (std::chrono::milliseconds timeout, GetDescriptionHandler onComplete)=0
	Requests a description of the slave. More...

virtual void	SetVariables (const std::vector< coral::model::VariableSetting > &settings, std::chrono::milliseconds timeout, SetVariablesHandler onComplete)=0
	Sets the values of, or connects, one or more of the slave's variables. More...

virtual void	SetPeers (const std::vector< coral::net::Endpoint > &peer, std::chrono::milliseconds timeout, SetPeersHandler onComplete)=0
	Sets or resets the list of peers to which the slave should be connected for the purpose of subscribing to variable data. More...

virtual void	ResendVars (std::chrono::milliseconds timeout, ResendVarsHandler onComplete)=0
	Makes the slave send all variable values and then wait to receive values for all connected input variables. More...

virtual void	Step (coral::model::StepID stepID, coral::model::TimePoint currentT, coral::model::TimeDuration deltaT, std::chrono::milliseconds timeout, StepHandler onComplete)=0
	Tells the slave to perform a time step. More...

virtual void	AcceptStep (std::chrono::milliseconds timeout, AcceptStepHandler onComplete)=0
	Tells the slave that the time step is accepted and it should update its inputs with data from other slaves. More...

virtual void	Terminate ()=0
	Instructs the slave to terminate, then closes the connection. More...

Detailed Description

An interface for classes that implement various versions of the master/slave communication protocol.

Use the MakeSlaveControlMessenger() factory function to obtain a messenger of the appropriate type for a given slave.

Constructor & Destructor Documentation

virtual coral::bus::ISlaveControlMessenger::~ISlaveControlMessenger ( )

inlinevirtual

Destructor.

Note that the destructor does not call Terminate() or Close(). The completion handlers for any ongoing or pending operations will therefore never get called. Use Terminate() or Close() before destruction to ensure that all callbacks are called.

Member Function Documentation

virtual void coral::bus::ISlaveControlMessenger::AcceptStep	(	std::chrono::milliseconds	timeout,
		AcceptStepHandler	onComplete
	)

pure virtual

Tells the slave that the time step is accepted and it should update its inputs with data from other slaves.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_READY on success
SLAVE_NOT_CONNECTED on failure

onComplete must have the following signature:

void f(const std::error_code&);

Possible error conditions are:

std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
coral::error::generic_error::aborted: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

Parameters

[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_STEP_OK

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::Close ( )

pure virtual

Ends all communication with the slave.

This will cause the completion handler for any on-going operation to be called with error code coral::error::generic_error::aborted.

Note that this simply closes the communication channel without notifying the slave first. This means that the slave may stay alive, waiting for a command from the master which never comes, until it times out and shuts itself down. Use Terminate() to ensure a controlled slave termination.

Postcondition: State() == SLAVE_NOT_CONNECTED

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::GetDescription	(	std::chrono::milliseconds	timeout,
		GetDescriptionHandler	onComplete
	)

pure virtual

Requests a description of the slave.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_READY on success or non-fatal failure
SLAVE_NOT_CONNECTED on fatal failure

onComplete must have the following signature:

void f(const std::error_code&, const coral::model::SlaveDescription&);

The first argument specified whether an error occurred, and if so, which one. If an error occurred, the second argument should be ignored. Otherwise, the second argument is a description of the slave. Note that this object may not have a correct slave ID and name, as this information may not be known by the slave itself.

Possible error conditions are:

std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
std::errc::operation_canceled: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

All error conditions are fatal unless otherwise specified.

Parameters

[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_READY

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::ResendVars	(	std::chrono::milliseconds	timeout,
		ResendVarsHandler	onComplete
	)

pure virtual

Makes the slave send all variable values and then wait to receive values for all connected input variables.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_READY on success or non-fatal failure
SLAVE_NOT_CONNECTED on fatal failure

onComplete must have the following signature:

void f(const std::error_code&);

Possible error conditions are:

coral::error::sim_error::data_timeout: The slave did not receive all expected variable values in time. This is a non-fatal error.
std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
coral::error::generic_error::aborted: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

All error conditions are fatal unless otherwise specified.

Parameters

[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_READY

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::SetPeers	(	const std::vector< coral::net::Endpoint > &	peer,
		std::chrono::milliseconds	timeout,
		SetPeersHandler	onComplete
	)

pure virtual

Sets or resets the list of peers to which the slave should be connected for the purpose of subscribing to variable data.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_READY on success or non-fatal failure
SLAVE_NOT_CONNECTED on fatal failure

onComplete must have the following signature:

void f(const std::error_code&);

Possible error conditions are:

std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
coral::error::generic_error::aborted: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

All error conditions are fatal unless otherwise specified.

Note: At the moment, there are no non-fatal failures. In the future, errors such as "invalid variable value" will be non-fatal, but none such are implemented yet.

Parameters

[in]	peers	A list of peer endpoints
[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_READY

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::SetVariables	(	const std::vector< coral::model::VariableSetting > &	settings,
		std::chrono::milliseconds	timeout,
		SetVariablesHandler	onComplete
	)

pure virtual

Sets the values of, or connects, one or more of the slave's variables.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_READY on success or non-fatal failure
SLAVE_NOT_CONNECTED on fatal failure

onComplete must have the following signature:

void f(const std::error_code&);

Possible error conditions are:

std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
coral::error::generic_error::aborted: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

All error conditions are fatal unless otherwise specified.

Note: At the moment, there are no non-fatal failures. In the future, errors such as "invalid variable value" will be non-fatal, but none such are implemented yet.

Parameters

[in]	settings	A list of variable values and connections
[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_READY

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::Step	(	coral::model::StepID	stepID,
		coral::model::TimePoint	currentT,
		coral::model::TimeDuration	deltaT,
		std::chrono::milliseconds	timeout,
		StepHandler	onComplete
	)

pure virtual

Tells the slave to perform a time step.

On return, the slave state is SLAVE_BUSY. When the operation completes (or fails), onComplete is called. Before onComplete is called, the slave state is updated to one of the following:

SLAVE_STEP_OK if the step completed and the slave has sent its outputs
SLAVE_STEP_FAILED if the step could not be completed
SLAVE_NOT_CONNECTED on fatal failure

onComplete must have the following signature:

void f(const std::error_code&);

Possible error conditions are:

coral::error::sim_error::cannot_perform_timestep (non-fatal): The slave was unable to complete the time step.
std::errc::bad_message: The slave sent invalid data.
std::errc::timed_out: The slave did not reply in time.
coral::error::generic_error::aborted: The operation was aborted (e.g. by Close()).
coral::error::generic_error::failed: The operation failed (e.g. due to an error in the slave).

All error conditions are fatal unless otherwise specified.

Parameters

[in]	stepID	The ID of the time step to be performed
[in]	currentT	The current time point
[in]	deltaT	The step size
[in]	timeout	Max. allowed time for the operation to complete
[in]	onComplete	Completion handler

Exceptions

std::invalid_argument if timeout is less than 1 ms or if onComplete is empty.

Precondition: State() == SLAVE_READY

Postcondition: State() == SLAVE_BUSY.

Implemented in coral::bus::SlaveControlMessengerV0.

virtual void coral::bus::ISlaveControlMessenger::Terminate ( )

pure virtual

Instructs the slave to terminate, then closes the connection.

This function has the same effect as Close(), except that it instructs the slave to terminate first.

This function may be called while another operation is ongoing (i.e., State() == SLAVE_BUSY). This will cause the callback of the original operation to be called with error code std::errc::operation_canceled.

Precondition: State() != SLAVE_NOT_CONNECTED

Postcondition: State() == SLAVE_NOT_CONNECTED

Implemented in coral::bus::SlaveControlMessengerV0.

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

coral/bus/slave_control_messenger.hpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation