coral::bus Namespace Reference

Functions and classes related to the simulation bus structure. More...

Classes
struct	AddedSlave
	Used in ExecutionManager::Reconstitute() to specify a slave which should be added to the simulation. More...
class	ExecutionManager
	Manages and coordinates all participants in an execution. More...
class	ExecutionManagerPrivate
	Implementation class for coral::bus::ExecutionManager. More...
class	ExecutionState
	The superclass of all classes that represent execution states. More...
class	ISlaveControlMessenger
	An interface for classes that implement various versions of the master/slave communication protocol. More...
class	PendingSlaveControlConnection
	A handle for a pending connection to a slave. More...
class	Shutdown
	Exception thrown when the slave receives a TERMINATE command. More...
class	SlaveAgent
	A class which contains the state of the slave and takes care of responding to requests from the master node in an appropriate manner. More...
struct	SlaveConfig
	Used in ExecutionManager::Reconfigure() to specify variable value and connection changes. More...
class	SlaveControlConnection
	A handle for an established connection to a slave. More...
class	SlaveController
	A class which is used for controlling one slave in an execution. More...
class	SlaveControlMessengerV0
	An implementation of ISlaveControlMessenger for version 0 of the master/slave communication protocol. More...
class	SlaveProviderClient
	A class for communicating with a single slave provider. More...
class	SlaveProviderOps
	An interface for the services offered by a slave provider, for use with MakeSlaveProviderServer(). More...
struct	SlaveSetup
	Configuration data which is sent to each slave as they are added to the simulation. More...
class	VariablePublisher
	A class which handles publishing of variable values on the network. More...
class	VariableSubscriber
	A class which handles subscriptions to and receiving of variable values. More...

Typedefs
typedef std::function< void(const std::error_code &, SlaveControlConnection)>	ConnectToSlaveHandler
	Completion handler type for ConnectToSlave()
typedef std::function< void(const std::error_code &)>	MakeSlaveControlMessengerHandler
	Completion handler type for MakeSlaveControlMessenger()

Enumerations

Functions
PendingSlaveControlConnection	ConnectToSlave (coral::net::Reactor &reactor, const coral::net::SlaveLocator &slaveLocator, int maxAttempts, std::chrono::milliseconds timeout, ConnectToSlaveHandler onComplete)
	Initiates a master's connection to a slave. More...
std::unique_ptr< ISlaveControlMessenger >	MakeSlaveControlMessenger (SlaveControlConnection connection, coral::model::SlaveID slaveID, const std::string &slaveName, const SlaveSetup &setup, MakeSlaveControlMessengerHandler onComplete)
	Returns an object which handles communication with a slave after the connection has been established. More...
void	MakeSlaveProviderServer (coral::net::reqrep::Server &server, std::shared_ptr< SlaveProviderOps > slaveProvider)
	Creates a server to be used by slave providers to handle incoming requests from a SlaveProviderClient. More...

Detailed Description

Functions and classes related to the simulation bus structure.

Enumeration Type Documentation

enum coral::bus::SlaveState

The various states a slave may be in.

Enumerator
SLAVE_NOT_CONNECTED	Slave is not yet connected.
SLAVE_READY	Slave is ready.
SLAVE_STEP_OK	Slave has performed a step and published its variables.
SLAVE_STEP_FAILED	Slave failed to perform a time step.
SLAVE_BUSY	Slave is currently performing some action.

Function Documentation

PendingSlaveControlConnection coral::bus::ConnectToSlave	(	coral::net::Reactor &	reactor,
		const coral::net::SlaveLocator &	slaveLocator,
		int	maxAttempts,
		std::chrono::milliseconds	timeout,
		ConnectToSlaveHandler	onComplete
	)

Initiates a master's connection to a slave.

This function attempts to send a HELLO message to the slave, and then immediately returns a PendingSlaveControlConnection object which acts as a reference to the pending connection. It is the caller's responsibility to hold on to this object until the connection has been established, as it will be aborted otherwise.

When the slave replies with a HELLO message of its own, thus completing the handshake, the completion handler (onComplete) is called. This handler is passed a SlaveControlConnection object, which acts as a reference to the established connection. From this moment, the previously returned PendingSlaveControlConnection object has served its purpose, and may be disposed of (or simply ignored).

The SlaveControlConnection object contains, among other things, which protocol the slave expects to use. To continue communication with the slave, this object must be passed to the MakeSlaveControlMessenger() function, which will create and return an appropriate ISlaveControlMessenger for the requested protocol. If the object is destroyed without being passed to MakeSlaveControlMessenger, the connection will be closed.

The timeout argument specifies how long to wait for a reply from the slave. If no reply is received within the given duration, the connection may be retried so that a new HELLO is sent. The maximum number of attempts (including the first) is specified by maxAttempts.

If the connection fails for some reason (e.g. it is refused by the slave, or the timeout is reached after the last attempt) the completion handler is called with an error code and a "null" SlaveControlConnection object.

onComplete must have the following signature:

void f(const std::error_code&, SlaveControlConnection);

Possible error conditions are:

• std::errc::connection_refused: The connection was aborted by the slave due to an error.
• std::errc::permission_denied: The connection was denied by the slave.
• std::errc::bad_message: The slave sent invalid data.
• std::errc::timed_out: The slave is unreachable, and the last connection attempt timed out.
• std::errc::operation_canceled: The connection was aborted because PendingSlaveControlConnection::Close() was called.

Note that the completion handler is never called if ConnectToSlave() throws an exception.

Parameters

[in]	reactor	The reactor used to listen for a reply from the slave. This will later be used by the ISlaveControlMessenger object to perform further communication with it, so it is important that it outlives this object.
[in]	slaveLocator	Information about how to connect to the slave. May not be empty.
[in]	maxAttempts	The maximum number of times to attempt a connection. Must be at least 1.
[in]	timeout	The maximum time to wait for a reply from the slave for each connection attempt. Must be at least 1 ms.
[in]	onComplete	Completion handler. May not be null.

Exceptions

std::invalid_argument

if any of the arguments are invalid.

std::unique_ptr<ISlaveControlMessenger> coral::bus::MakeSlaveControlMessenger	(	SlaveControlConnection	connection,
		coral::model::SlaveID	slaveID,
		const std::string &	slaveName,
		const SlaveSetup &	setup,
		MakeSlaveControlMessengerHandler	onComplete
	)

Returns an object which handles communication with a slave after the connection has been established.

Before this function can be called, a connection to the slave must be established using ConnectToSlave(). Its completion handler receives a SlaveControlConnection object which is then passed to this function, which in turn creates and returns an ISlaveControlMessenger object appropriate for the protocol version requested by the slave. When the function returns, the SlaveControlConnection object has served its purpose and may be disposed of (or simply ignored).

This function also sends some initial configuration data to the slave, for for example its assigned numeric ID. When the slave has received and acknowledged this, the completion handler onComplete is called. Until then, the returned messenger object will be in the SLAVE_BUSY state, and most of its methods may not be called. (See the ISlaveControlMessenger documentation for information about each method's preconditions.)

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 has become unreachable and the connection timed out. The timeout used is the one which was passed to ConnectToSlave().
• coral::error::generic_error::operation_failed: The operation failed (e.g. due to an error in the slave).

Note that the completion handler is never called if MakeSlaveControlMessenger() throws an exception.

Parameters

[in]	connection	The connection object passed to ConnectToSlave()'s completion handler. Must refer to an established connection.
[in]	slaveID	The ID number assigned to the slave. Must be a valid ID.
[in]	slaveName	The name given to the slave.
[in]	setup	Slave configuration parameters
[in]	onComplete	Completion handler. May not be null.

Exceptions

coral::error::ProtocolNotSupported	if the slave requested an unsupported protocol version.
std::invalid_argument	if any of the input arguments are invalid.

void coral::bus::MakeSlaveProviderServer	(	coral::net::reqrep::Server &	server,
		std::shared_ptr< SlaveProviderOps >	slaveProvider
	)

Creates a server to be used by slave providers to handle incoming requests from a SlaveProviderClient.

Parameters

[in]	server	The server that will handle the requests. The function will add an appropriate protocol handler to this server.
[in]	slaveProvider	The object that will carry out any incoming requests.