An implementation of ISlaveControlMessenger for version 0 of the master/slave communication protocol. More...

#include "coral/bus/slave_control_messenger_v0.hpp"

Inheritance diagram for coral::bus::SlaveControlMessengerV0:

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

void	Close () override
	Ends all communication with the slave. More...

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

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

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

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

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

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

void	Terminate () override
	Instructs the slave to terminate, then closes the connection. More...

Public Member Functions inherited from coral::bus::ISlaveControlMessenger
virtual	~ISlaveControlMessenger () CORAL_NOEXCEPT
	Destructor. More...

Additional Inherited Members
Public Types inherited from coral::bus::ISlaveControlMessenger
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()

Detailed Description

An implementation of ISlaveControlMessenger for version 0 of the master/slave communication protocol.

Member Function Documentation

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

void coral::bus::SlaveControlMessengerV0::Close ( )

overridevirtual

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

Implements coral::bus::ISlaveControlMessenger.

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

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

overridevirtual

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.

Implements coral::bus::ISlaveControlMessenger.

void coral::bus::SlaveControlMessengerV0::Terminate ( )

overridevirtual

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

Implements coral::bus::ISlaveControlMessenger.

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

coral/bus/slave_control_messenger_v0.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation