User story: disengage / reengage a simulator family (all instances of an FMU) while an execution is running (for debugging purposes and recompilation)

[xmirabel]

NEED

On a vehicule (boat, aircraft, rolling vehicle), an external device can be part of the simulation. It should be possible for the operator to disengage (disable + terminate + unload) or reengage (reload + restart + enable) a slave family (all instances of the same FMU) during an experiment without disturbing the global execution of a simulation. The goal is to be able to update or debug the model code, recompile it and reintegrate it for test in the same complex experiment.

DESCRIPTION

As a	OSP user
I want to	be able to disengage (disable + terminate + unload) or reengage (reload + restart + enable) a slave family (all instances of an FMU) while an execution is running
So that	the execution continue running with their last output data but without (when disengaged) / with (when engaged) executing the simulator instances "set inputs" and then "do step" and then "get outputs".

ACCEPTANCE TESTS

Given that	a whole simulator family is engaged
When	the user disengage it
Then	the simulator family (all simulators instances of the same FMU of this simulator) are frozen in their current state, i.e. no more interaction are done with the FMU, but their last output values are available to the rest of the platform. The execution is not disturbed at all by this event.
Then	all instances are disconnected to the execution and are terminated.
Then	the FMU library is unloaded.

Given that	a whole simulator family is disengaged
When	the user reengage it
Then	the simulator family is reloaded, then restarted (respecting the starting steps of the model), then reconnected to the execution and then reintegrated to the step cycle in its new current state, i.e. interactions restart with the FMU, with its last input values. The execution is not disturbed at all by this event.

Given that	a whole simulator family is engaged
When	the user reengage it
Then	nothing happens.

Given that	a whole simulator family is disengaged
When	the user disengage it
Then	nothing happens.

EXAMPLE OF SIGNATURES

/**
 *  Engage a slave family to an execution.
 *
 *  \param [in] execution
 *      The concerned execution.
 *  \param [in] cosim_slave_index
 *      One slave of the slave family to be engaged.
 *
 *  \returns
 *      0 on success and -1 on error.
 */
int cosim_execution_engage_slave_family(cosim_execution* execution, cosim_slave_index slave);

/**
 *  Disengage a slave family from an execution.
 *
 *  \param [in] execution
 *      The concerned execution.
 *  \param [in] cosim_slave_index
 *      One slave of the slave family to be disengaged.
 *
 *  \returns
 *      0 on success and -1 on error.
 */
int cosim_execution_disengage_slave_family(cosim_execution* execution, cosim_slave_index slave);

// Slave family execution status.
typedef enum
{
    COSIM_SLAVE_FAMILY_EXECUTION_DISENGAGED,
    COSIM_SLAVE_FAMILY_EXECUTION_ENGAGED
} cosim_slave_family_execution_status;

/**
 *  Get a slave execution status.
 *
 *  \param [in] execution
 *      The concerned execution.
 *  \param [in] cosim_slave_index
 *      The slave to be queried.
 *  \param [out] status
 *      The slave status.
 *
 *  \returns
 *      0 on success and -1 on error (if slave index is invalid for instance).
 */
int cosim_execution_get_slave_family_execution_status(cosim_execution* execution, cosim_slave_index slave, cosim_slave_family_execution_status* status);