Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

Manoeuvre Class Reference
[Manoeuvre Management]

#include <Manoeuvre.h>

Inheritance diagram for Manoeuvre:

CC_RootObject DC_DummyConfigurableManoeuvre DC_DummyManoeuvre PUSTcManoeuvre DC_TestPUSConfigurableManoeuvre List of all members.

Detailed Description

Base class from which all manoeuvre classes are derived.

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:

Manoeuvres can be disabled and enabled. When a manoeuvre is disabled, its start check is guaranteed to return: "manoeuvre cannot start". This class is responsible for the management of the enable status and for ensuring that this constraint is respected. Note that this means that changes in the enable status of a manoeuvre have no effect upon manoeuvres that are already executiong.
See also:
CC_ManoeuvreFactory

CC_ManoeuvreManager

Author:
Alessandro Pasetti (P&P Software GmbH)
Version:
1.0

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.


Constructor & Destructor Documentation

Manoeuvre::Manoeuvre void   ) 
 

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.


Member Function Documentation

void Manoeuvre::abort void   ) 
 

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 canContinue method returns false) in which case the manoeuvre must be aborted. After being aborted, a manoeuvre should be de-scheduled and should no longer be considered for execution. A pseudo-code implementation for this method is as follows:

   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.
See also:
TD_EventType

canContinue

CC_ManoeuvreManager::activate

CC_ManoeuvreManager::abort

Definition at line 73 of file Manoeuvre.cpp.

bool Manoeuvre::canContinue void   )  [virtual]
 

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 abort). This class offers a default implementation that returns "manoeuvre can continue".

This method should only be called on a manoeuvre that is in use and that is already executing.

See also:
CC_ManoeuvreManager::activate

abort

Returns:
true if the manoeuvre can continue execution

Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre.

Definition at line 50 of file Manoeuvre.cpp.

bool Manoeuvre::canStart void   )  [virtual]
 

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.
See also:
CC_ManoeuvreManager::activate
Returns:
true if the manoeuvre is ready to start

Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre.

Definition at line 36 of file Manoeuvre.cpp.

void Manoeuvre::doContinue void   ) 
 

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.

See also:
TD_EventType

CC_ManoeuvreManager::activate

Definition at line 59 of file Manoeuvre.cpp.

virtual void Manoeuvre::doInternalContinue void   )  [protected, pure virtual]
 

Encapsulate the implementation of the continuation actions to be carried out by the manoeure.

This method is called by method doContinue() in this same class.

See also:
doContinue

Implemented in DC_DummyConfigurableManoeuvre, DC_DummyManoeuvre, and DC_TestPUSConfigurableManoeuvre.

unsigned int Manoeuvre::getActivationStepCounter void   )  const
 

Return the value of the activation step counter.

See also:
doContinue
Returns:
the current value of the activation step counter

Definition at line 123 of file Manoeuvre.cpp.

TD_CheckCode Manoeuvre::getContinuationCheckCode void   )  const [virtual]
 

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 canContinue has returned false). This class provides a default implementation that returns zero.

See also:
canContinue
Returns:
the continuation check code

Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre.

Definition at line 55 of file Manoeuvre.cpp.

void Manoeuvre::initialize void   )  [virtual]
 

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.

See also:
CC_ManoeuvreManager::activate

canStart

Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre.

Definition at line 45 of file Manoeuvre.cpp.

void Manoeuvre::internalAbort void   )  [protected, virtual]
 

Encapsulate the implementation of the actions to be carried out by the manoeure after it is aborted.

This method is called by method abort() in this same class. This class offers a default implementation that returns without taking any actions.

See also:
abort

Definition at line 24 of file Manoeuvre.cpp.

bool Manoeuvre::internalCanStart void   )  [protected, virtual]
 

Encapsulate the implementation of the start check associated to this manoeuvre.

This method is called by method canStart() in this same class. This class offers a default implementation that returns "manoeuvre can start".

See also:
canStart
Returns:
true if the manoeuvre can start execution, false otherwise

Definition at line 32 of file Manoeuvre.cpp.

void Manoeuvre::internalTerminate void   )  [protected, virtual]
 

Encapsulate the implementation of the termination actions associated to this manoeuvre.

This method is called by method terminate() in this same class. This class offers a default implementation that returns without taking any action.

See also:
terminate

Reimplemented in DC_DummyConfigurableManoeuvre, and DC_TestPUSConfigurableManoeuvre.

Definition at line 28 of file Manoeuvre.cpp.

bool Manoeuvre::isEnabled void   )  const
 

Check the enable status of the manoeuvre profile.

Returns:
true if the manoeuvre is enabled, false otherwise

Definition at line 119 of file Manoeuvre.cpp.

bool Manoeuvre::isExecuting void   )  const
 

Return the value of the isExecuting flag.

Returns:
the value of the isExecuting flag.

Definition at line 111 of file Manoeuvre.cpp.

virtual bool Manoeuvre::isFinished void   )  [pure virtual]
 

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.

See also:
CC_ManoeuvreManager::activate
Returns:
true if the manoeuvre has terminated execution

Implemented in DC_DummyConfigurableManoeuvre, DC_DummyManoeuvre, and DC_TestPUSConfigurableManoeuvre.

bool Manoeuvre::isInUse void   )  const
 

Return the value of the inUse flag.

Returns:
the value of the inUse flag

Definition at line 95 of file Manoeuvre.cpp.

bool Manoeuvre::isSuspended void   )  const
 

Return the value of the isSuspended flag.

Returns:
the value of the isSuspended flag

Definition at line 107 of file Manoeuvre.cpp.

void Manoeuvre::setEnabled bool  isEnabled  ) 
 

Set the enable status of the manoeuvre.

Parameters:
isEnabled if true, then the manoeuvre is enabled; if false, then the manoeuvre is disabled

Definition at line 115 of file Manoeuvre.cpp.

void Manoeuvre::setInUse bool  newInUse  ) 
 

Set the value of the inUse flag.

See also:
TD_EventType

CC_ManoeuvreManager::load

Parameters:
newInUse the new value of the inUse flag

Definition at line 91 of file Manoeuvre.cpp.

void Manoeuvre::setIsSuspended bool  newIsSuspended  ) 
 

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; 
See also:
TD_EventType

doContinue

Parameters:
newIsSuspended the new value of the isSuspended flag

Definition at line 99 of file Manoeuvre.cpp.

void Manoeuvre::terminate void   ) 
 

Perform the termination actions associated to this manoeuvre.

This method is intended to be called when a manoeuvre has terminated execution nominally (after its isFinished method returns true). It can be used to implement any clean-up actions that is required at the end of a manoeuvre's execution. The manoeuvre is forced into "not suspended" status (its isSuspended flag is set to false). The implementation in this class is responsible for resetting the isExecuting and isSuspended flags and for creating an event report recording the termination of the manoeuvre. A pseudo-code implementation for this method is as follows:

   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.

See also:
TD_EventType

doContinue

CC_ManoeuvreManager::activate

Definition at line 83 of file Manoeuvre.cpp.


The documentation for this class was generated from the following files:
Copyright 2003 P&P Software GmbH - All Rights Reserved