coral
A C++ library for distributed co-simulation
Public Types | Public Member Functions | List of all members
coral::bus::ISlaveControlMessenger Class Referenceabstract

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:
coral::bus::SlaveControlMessengerV0

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]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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:

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]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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]peersA list of peer endpoints
[in]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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]settingsA list of variable values and connections
[in]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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:

All error conditions are fatal unless otherwise specified.

Parameters
[in]stepIDThe ID of the time step to be performed
[in]currentTThe current time point
[in]deltaTThe step size
[in]timeoutMax. allowed time for the operation to complete
[in]onCompleteCompletion handler
Exceptions
std::invalid_argumentif 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: