#include <Manoeuvre.h>
Inheritance diagram for Manoeuvre:
A manoeuvre is primarily characterized by its ability to encapsulate an action that takes place over a period of time. In this sense, it is opposed to a punctual action which instead encapsulates an action that takes place "in one shot". More specifically, manoeuvres are characterized by three types of actions and three types of checks which they can perform. The actions are:<ul> An initialization action that is executed once when the manoeuvre first becomes due for execution. A continuation action that is executed repeatedly until the manoeuvre has terminated execution. A termination action that is executed once when the manoeuvre has terminated execution. An activation step counter is associated to the continuation action. This is initialized to zero when the manoeuvre starts execution and is incremented by one every time the continuation action is advanced by a step (i.e. every time method doInternalContinue
is executed). This counter helps other components keep track of the progress of the manoeuvre.
The three checks that are associated to a manoeuvre are:<ul> A start check to be performed just before launching execution of a manoeuvre. It verifies whether the manoeuvre is ready to start execution. A continuation check to be performed while the manoeuvre is executing to verify whether continuation can be continued or whether the manoeuvre should be aborted. A termination check to be performed before terminating execution of the manoeuvre. It checks whether the manoeuvre has terminated its execution and whether it should be terminated. This class is abstract. Concrete manoeuvre actions and manoeuvre checks are defined by subclasses. This class provides either default trivial implementations or leaves the implementation of the actions and checks undefined.
Execution of a manoeuvre as defined here must respect certain constraints (e.g. a start check should be performed before starting execution of a manoeuvre, a termination action should be performed before terminating execution of a manoeuvre, etc). Manoeuvres are defined here as low-level components that cannot take responsibility for their own execution. They are intended to be loaded into some other component that is then responsible for calling their methods in the correct sequence and in compliance with the constraints defined by the present interface. This class implements assertions that, to some extent, ensure that the manoeuvre is used correctly but responsibility for correct usage lies with the component managing a manoeuvre. In the OBS Framework, manoeuvres are normally loaded in the manoeuvre manager (instance of class CC_ManoeuvreManager
) which then becomes responsible for their execution.
This class additionally manages three boolean flags: isExecuting, inUse, and isSuspended. Flag isExecuting is set to true immediately after the execution of the manoeuvre starts and is reset to false when execution has terminated or the manoeuvre is aborted. This flag is useful for external entities that wish to check whether a manoeuvre is actually executing.
Manoeuvres are intended to be used by some other components. Since they have an internal state, they cannot normally be used by more than one component at a time. Flag inUse helps prevent this type of conflict. The component that uses the manoeuvre should set it when it starts using it and should reset it when it finishes using it. Normally, the management of the inUse flag is done jointly by the manoeuvre factory component (instance of class CC_ManoeuvreFactory
) and by the manoeuvre manager.
Flag isSuspended is set to true to signify that execution of the manoeuvre should be temporarily suspended ("the manoeuvre is held"). Execution resumes when the flag is reset to false. When a manoeuvre is suspended, its continuation action is not performed but this is the only effect of suspension: the other two actions and all three checks remain unaffected. However, when a manoeuvre terminates or aborts, its isSuspended flag is set to false.
Certain changes in the execution state of a manoeuvre should be recorded through event reports. This class is responsible for creating event reports in the following cases:
Definition at line 120 of file Manoeuvre.h.
Public Member Functions | |
Manoeuvre (void) | |
Instantiate a manoeuvre object. | |
virtual bool | canStart (void) |
Perform the start check for the manoeuvre: return true if the manoeuvre is ready to start execution. | |
virtual void | initialize (void) |
Perform the initialization action associated to this manoeuvre. | |
virtual bool | canContinue (void) |
Perform the continuation check for the manoeuvre: return true if the manoeuvre can safely continue execution. | |
virtual TD_CheckCode | getContinuationCheckCode (void) const |
Return the continuation check code for the manoeuvre. | |
void | doContinue (void) |
Advance the execution of the manoeuvre. | |
void | abort (void) |
Abort execution of a running manoeuvre. | |
void | terminate (void) |
Perform the termination actions associated to this manoeuvre. | |
virtual bool | isFinished (void)=0 |
Perform the termination check for the manoeuvre: return true if the manoeuvre has terminated executing its allotted actions. | |
void | setInUse (bool newInUse) |
Set the value of the inUse flag. | |
bool | isInUse (void) const |
Return the value of the inUse flag. | |
void | setIsSuspended (bool newIsSuspended) |
Set the value of the isSuspended flag. | |
bool | isSuspended (void) const |
Return the value of the isSuspended flag. | |
bool | isExecuting (void) const |
Return the value of the isExecuting flag. | |
void | setEnabled (bool isEnabled) |
Set the enable status of the manoeuvre. | |
bool | isEnabled (void) const |
Check the enable status of the manoeuvre profile. | |
unsigned int | getActivationStepCounter (void) const |
Return the value of the activation step counter. | |
Protected Member Functions | |
virtual void | doInternalContinue (void)=0 |
Encapsulate the implementation of the continuation actions to be carried out by the manoeure. | |
virtual void | internalAbort (void) |
Encapsulate the implementation of the actions to be carried out by the manoeure after it is aborted. | |
virtual void | internalTerminate (void) |
Encapsulate the implementation of the termination actions associated to this manoeuvre. | |
virtual bool | internalCanStart (void) |
Encapsulate the implementation of the start check associated to this manoeuvre. |
|
Instantiate a manoeuvre object. The enabled status of the manoeuvre is initialized to "enabled". The isExecuting, isInUse and isSuspended flags are initialized to false. The activation step counter is initialized to zero. Definition at line 16 of file Manoeuvre.cpp. |
|
Abort execution of a running manoeuvre. If the manoeuvre is not currently executing (if the isExecuting flag is false), no action is taken. Otherwise, its execution status is changed to "not executing", an event reporting the abort operation is created, and the abort operations are executed. The manoeuvre is forced into "not suspended" status (its isSuspended flag is set to false).
In general, a manoeuvre may be aborted either as a result of an autonomous decision of an external entity or because the manoeuvre itself declares that it is unable to continue execution (i.e. its isSuspended = false; if ( !isExecuting ) return; else { isExecuting = false; createEventReport(EVT_MAN_ABORTED); internalAbort(void); }The internalAbort() method is intended to be overridden by subclasses to specify concrete actions to be taken by a manoeuvre that is aborted. These would typically be clean-up actions that bring the internal state of the manoeuvre to some pre-defined and consistent state.
Definition at line 73 of file Manoeuvre.cpp. |
|
Perform the continuation check for the manoeuvre: return true if the manoeuvre can safely continue execution.
A manoeuvre that whose continuation check returns "cannot continue execution" should normally be aborted (method This method should only be called on a manoeuvre that is in use and that is already executing.
Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre. Definition at line 50 of file Manoeuvre.cpp. |
|
Perform the start check for the manoeuvre: return true if the manoeuvre is ready to start execution. This method should be called only on a manoeuvre that is already in used but that is not yet executing. Execution of a manoeuvre should be initiated only when this check has been performed and has returned: "manoeuvre ready to start". If a manoeuvre is disabled, the check always returns: "manoeuvre cannot start". Otherwise, a manouvre-specific check is performed. A pseudo-code implementation for this method is as follows: if ( !isEnabled() ) return MAN_CANNOT_START; else return internalCanStart();The internalCanStart() method is virtual and encapsulates the implementation of the manoeuvre-specific part of the start check.
Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre. Definition at line 36 of file Manoeuvre.cpp. |
|
Advance the execution of the manoeuvre. Manoeuvres execute over a prolonged period of time. This method is intended to be called to advance the execution of the manoeuvre. The implementation provided by this class is responsible for managing the isExecuting flag, for managing the activation step counter, and for creating an event report when the status of the flag changes from "not executing" to "executing" (this signals the beginning of the execution of the manoeuvre). Execution of the manoeuvre is advanced only if the manoeuvre is not suspended. A pseudo-code implementation for this method is as follows: if ( !isExecuting ) { activationStepCounter = 0; isExecuting=true; createEventReport(EVT_MAN_STARTED); } if ( !isSuspended() ) { activationStepCounter++; doInternalContinue(); }The doInternalContinue() method is virtual and encapsulates the implementation of the actions to be performed by the manoeuvre. This method is only called if the manoeuvre is not suspended. The isExecuting flag is initialized to false by the constructor and is reset to false when the manoeuvre has finished execution or is aborted. Note that the activation step counter is implemented as an unsigned integer and there is no protection against overflow. This puts an upper ceiling on the number of activation steps of a manoeuvre. The manId parameter in the pseudo-code is a manoeuvre identifier. This class uses the class identifier of the manoeuvre component as manoeuvre identifier. This method should only be called on a manoeuvre that is already in use. Definition at line 59 of file Manoeuvre.cpp. |
|
Encapsulate the implementation of the continuation actions to be carried out by the manoeure.
This method is called by method
Implemented in DC_DummyConfigurableManoeuvre, DC_DummyManoeuvre, and DC_TestPUSConfigurableManoeuvre. |
|
Return the value of the activation step counter.
Definition at line 123 of file Manoeuvre.cpp. |
|
Return the continuation check code for the manoeuvre.
The continuation check code allows a manoeuvre to make information available about the reasons for the failure of the continuation check. The return value of this method is only valid if the continuation check has returned "manoeuvre cannot continue" (ie. if method
Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre. Definition at line 55 of file Manoeuvre.cpp. |
|
Perform the initialization action associated to this manoeuvre. This method should be called on a manoeuvre that is alredy in use but not yet executing. It should be called immediately before the execution of the manoeuvre is initiated. It should be called only when the execution check returns "manoeuvre can start". This class offers a default implementation that returns without doing anything.
Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre. Definition at line 45 of file Manoeuvre.cpp. |
|
Encapsulate the implementation of the actions to be carried out by the manoeure after it is aborted.
This method is called by method
Definition at line 24 of file Manoeuvre.cpp. |
|
Encapsulate the implementation of the start check associated to this manoeuvre.
This method is called by method
Definition at line 32 of file Manoeuvre.cpp. |
|
Encapsulate the implementation of the termination actions associated to this manoeuvre.
This method is called by method
Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre. Definition at line 28 of file Manoeuvre.cpp. |
|
Check the enable status of the manoeuvre profile.
Definition at line 119 of file Manoeuvre.cpp. |
|
Return the value of the isExecuting flag.
Definition at line 111 of file Manoeuvre.cpp. |
|
Perform the termination check for the manoeuvre: return true if the manoeuvre has terminated executing its allotted actions. After this method returns "manoeuvre has terminated", the termination action should be executed.
Implemented in DC_DummyConfigurableManoeuvre, DC_DummyManoeuvre, and DC_TestPUSConfigurableManoeuvre. |
|
Return the value of the inUse flag.
Definition at line 95 of file Manoeuvre.cpp. |
|
Return the value of the isSuspended flag.
Definition at line 107 of file Manoeuvre.cpp. |
|
Set the enable status of the manoeuvre.
Definition at line 115 of file Manoeuvre.cpp. |
|
Set the value of the inUse flag.
Definition at line 91 of file Manoeuvre.cpp. |
|
Set the value of the isSuspended flag. If the requested value of the flag is different from the current value (indicating a change in the state of the manoevre), this is recorded through an even report. A pseudo-code implementation for this method is as follows: if ( isSuspended and !newIsSuspended ) // manoeuvre is resumed createEventReport(EVT_MAN_RESUMED); else if ( !isSuspended and newIsSuspended ) createEventReport(EVT_MAN_SUSPENDED); isSuspended = newIsSuspended;
Definition at line 99 of file Manoeuvre.cpp. |
|
Perform the termination actions associated to this manoeuvre.
This method is intended to be called when a manoeuvre has terminated execution nominally (after its isSuspended = false; isExecuting = false; createEventReport(EVT_MAN_TERMINATED); internalTerminate();The internalTerminate() method can be overridden by concrete subclasses to implement their own termination actions. This method should only be called on a manoeuvre that is in use and that is already executing. Definition at line 83 of file Manoeuvre.cpp. |