Creates and controls an execution. More...

#include "coral/master/execution.hpp"

Public Member Functions
	Execution (const std::string &executionName, const ExecutionOptions &options=ExecutionOptions{})
	Constructor which creates a new execution. 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 input variable values and establishes connections between output and input variables. More...

StepResult	Step (coral::model::TimeDuration stepSize, std::chrono::milliseconds timeout, std::vector< std::pair< coral::model::SlaveID, StepResult >> *slaveResults=nullptr)
	Initiates a time step. More...

void	AcceptStep (std::chrono::milliseconds timeout)
	Confirms and completes a time step. More...

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

Detailed Description

Creates and controls an execution.

This class is used to set up and control an execution, i.e. a single simulation run. This includes connecting and initialising slaves and executing time steps.

Constructor & Destructor Documentation

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

explicit

Constructor which creates a new execution.

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 )

Confirms and completes a time step.

This method must be called after a successful Step() call, before any other operations are performed. See the Step() documentation for details.

Parameters

timeout The communications timeout used to detect loss of communication with slaves. A negative value means no timeout.

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

Sets input variable values and establishes connections between output and input variables.

On input, the slaveConfigs 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 SlaveConfig::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. A negative value means no timeout.

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. The `AddedSlave` objects will have been updated with information about the slaves on return.
[in]	commTimeout	The communications timeout used to detect loss of communication with slaves. A negative value means no timeout.

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

Initiates a time step.

This function requests that the simulation be advanced with the logical time specified by stepSize. It returns a value that specifies whether the slaves succeeded in performing their calculations for the time step. If the step was successful, i.e., the result is StepResult::completed, the operation may be confirmed and completed by calling AcceptStep().

The function may fail in two ways:

It may return StepResult::failed, which means that one or more slaves failed to complete a time step of the given length, but that they might have succeeded with a shorter step length.
It may throw an exception, which signals an irrecoverable error, e.g. network failure.

Note: Currently, discarding and retrying time steps are not supported, and both of the above must be considered irrecoverable failures. In future versions, it will be possible to call a DiscardStep() function in the first case, to thereafter call Step() again with a shorter step length. (This is the reason why two function calls, Step() and AcceptStep(), are required per time step.)

Parameters

[in]	stepSize	How much the simulation should be advanced in time. This must be a positive number.
[in]	timeout	The communications timeout used to detect loss of communication with slaves. A negative value means no timeout.
[in]	slaveResults	An optional vector which, if given, will be cleared and filled with the result reported by each slave.

Returns: Whether the operation was successful.

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

Terminates the execution.

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