Master execution controller. More...

#include "coral/master/execution.hpp"

Public Member Functions
	Execution (const std::string &executionName, const ExecutionOptions &options=ExecutionOptions{})
	Constructor. More...

	~Execution () CORAL_NOEXCEPT
	Destructor.

	Execution (Execution &&) CORAL_NOEXCEPT
	Move constructor.

Execution &	operator= (Execution &&) CORAL_NOEXCEPT
	Move assignment operator.

void	Reconstitute (std::vector< AddedSlave > &slavesToAdd, std::chrono::milliseconds commTimeout)
	Adds new slaves to the execution. More...

void	Reconfigure (std::vector< SlaveConfig > &slaveConfigs, std::chrono::milliseconds commTimeout)
	Sets the values of and/or connects variables. More...

StepResult	Step (coral::model::TimeDuration stepSize, std::chrono::milliseconds timeout, std::vector< std::pair< coral::model::SlaveID, StepResult >> *slaveResults=nullptr)
	Steps the simulation forward. More...

void	AcceptStep (std::chrono::milliseconds timeout)
	Accepts a time step, making the simulation ready to execute the next. More...

void	Terminate ()
	Terminates the execution. More...

Detailed Description

Master execution controller.

This class is used by the master entity in an execution to initialize, run and shut down the simulation.

Constructor & Destructor Documentation

coral::master::Execution::Execution	(	const std::string &	executionName,
		const ExecutionOptions &	options = `ExecutionOptions{}`
	)

explicit

Constructor.

Parameters

[in]	executionName	A (preferably unique) name for the execution.
[in]	options	Configuration settings for the execution.

Member Function Documentation

void coral::master::Execution::AcceptStep ( std::chrono::milliseconds timeout )

Accepts a time step, making the simulation ready to execute the next.

This function causes each slave to verify that it has received all its inputs for the time step just performed, and return to a state where it is ready to receive a new step command.

The function may only be called if the previous step succeeded, and must be called before a new step can be taken.

Parameters

[in] timeout The amount of time given to each slave for confirming that it is ready for a new step. Note that if a slave fails to report back within this time, it is considered a fatal error which will cause the entire simulation to shut down. (Essentially, it is assumed that we have lost connection with the slave for some reason.)

void coral::master::Execution::Reconfigure	(	std::vector< SlaveConfig > &	slaveConfigs,
		std::chrono::milliseconds	commTimeout
	)

Sets the values of and/or connects variables.

On input, theslaveConfigs` vector must contain a list of slaves whose variables are to be modified, (re)connected and/or disconnected. It must contain exactly one SlaveConfig object for each slave whose configuration is to be changed.

When a connection is made between an output variable and an input variable, or such a connection is to be broken, this is specified in the SlaveConfig object for the slave which owns the input variable.

If the function throws an exception, and the error originates in one or more of the slaves, the error fields of the corresponding SlaveConfig objects will be set to values that describe the errors.

Parameters

[in,out]	slaveConfigs	A list of slave configuration change specifications, at most one entry per slave.
[in]	commTimeout	The communications timeout used to detect loss of communication with the slaves.

void coral::master::Execution::Reconstitute	(	std::vector< AddedSlave > &	slavesToAdd,
		std::chrono::milliseconds	commTimeout
	)

Adds new slaves to the execution.

On input, the slavesToAdd vector must contain a list of slaves to add, the name and location of each specified in an AddedSlave object. When the function returns successfully, these objects will have been updated with the ID numbers assigned to the respective slaves.

If the function throws an exception, and the error is related to one or more of the slaves, the corresponding AddedSlave objects will contain information about the errors.

The naming of this function reflects the fact that, in a future version, it is intended to also support removing slaves from an execution, and not just adding.

Parameters

[in,out]	slavesToAdd	A list of slaves to add. If empty, the function returns vacuously. Contains information about the slaves on output.
[in]	commTimeout	The communications timeout used to detect loss of communication with the slaves.

StepResult coral::master::Execution::Step	(	coral::model::TimeDuration	stepSize,
		std::chrono::milliseconds	timeout,
		std::vector< std::pair< coral::model::SlaveID, StepResult >> *	slaveResults = `nullptr`
	)

Steps the simulation forward.

The function returns whether the step succeeded or not. If all slaves were able to carry out their computations for the time step, STEP_COMPLETE will be returned. If one or more slaves were only able to carry out a partial time step, or could not carry out the time step at all, STEP_FAILED will be returned. It may then be possible to discard the step and retry with a shorter step size, but this requires that all slaves support this functionality. Otherwise, the only option is to terminate the simulation.

A list of which slaves succeeded and which failed may be obtained by supplying an output vector via the slaveResults parameter.

Note that general errors (e.g. network failure) are reported via exceptions, and are generally irrecoverable.

Note: Support for discarding and redoing time steps has not been implemented yet, so if the function returns STEP_FAILED, the only possible course of action is currently to terminate the simulation.

Parameters

[in]	stepSize	The time step size. Must be a positive number.
[in]	timeout	The amount of time given to each slave for completing its calculations in this time step and reporting back to the master. Note that if a slave fails to report back within this time, it is considered a fatal error which will cause the entire simulation to shut down. (Essentially, it is assumed that we have lost connection with the slave for some reason.) Must be a positive number.
[in]	slaveResults	An optional vector which, if given, will be cleared and filled with the result reported by each slave.

void coral::master::Execution::Terminate ( )

Terminates the execution.

This function will tell all participants to terminate, and then return immediately. It does not (and can not) verify that the participants do in fact terminate. Once all participants have been notified, the execution itself, and the thread it is running in, will terminate.

No other methods may be called after a successful Terminate() call.

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

coral/master/execution.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation