ControlFlow.h

Go to the documentation of this file.

/*
    Copyright (C) 2010-2012
    Johannes Feuser <feuser@uni-bremen.de>
    This file is part of the openETCS library.

    The openETCS library is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    any later version.

    The openETCS library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with the openETCS library.  If not, see <http://www.gnu.org/licenses/>.
*/

/*!
 *  \author Johannes Feuser <feuser@uni-bremen.de>
 *  \brief control flow classes 
 */

#ifndef __OETCS_DF_CONTROLFLOW_H__
#define __OETCS_DF_CONTROLFLOW_H__




#include <string>
#include <vector>
#include "EVCStateMachine.h"
#include "Error/ExceptionTypes.h"


namespace oETCS { namespace DF { class CCondition; }  } 

namespace oETCS { namespace DF { class CAbstractFlow; }  } 
namespace oETCS { namespace DF { class CTransition; }  } 
namespace oETCS { namespace DF { class CEVCStateMachine; }  } 


namespace oETCS {

namespace DF {


/*!
 *  \brief control flow (state machine) class used in a data flow
 */
class CControlFlow : public oETCS::DF::CFunctionBlock 
{
  public:
    /*!
     *  \brief state class within a control flow
     */
    class CState 
    {
      public:
        /*!
         *  \brief general constructor
         *
         *  Parameterises the state with all constant members.
         *  The data flow object takes over the posession of the passed data flow object.
         *
         *  \param[in] pParent pointer to the parent control flow object
         *  \param[in] StateName literal name of the state
         *  \param[in] FunctionBlocks vector with pointers to function blocks, which are executed by this state
         *  \param[in] Flows vector with pointer to flow objects, which connect function blocks in this state
         *  \param[in] bIsFinal optinal flag for a final state
         *  \param[in] bIsFinal optinal flag for the initial state
         */
        CState(CControlFlow * const pParent, const std::string & StateName, const ::std::vector< oETCS::DF::CFunctionBlock * >& FunctionBlocks, const ::std::vector< oETCS::DF::CAbstractFlow * >& Flows, const bool & bIsFinal = false, const bool & bIsInitial = false) throw();
        
        

        virtual ~CState() throw();
        
        

        /*!
         *  \brief returns true, if a CFunctionBlock objects is active in a control flow
         *
         *  \param[in] pFunctionBlock pointer to a function block object to be testetd
         *  \return active state flag
         */
        bool IsActiveFunctionBlock(const oETCS::DF::CFunctionBlock * const pFunctionBlock) const throw();
        
        

        /*!
         *  \brief returns true, if a CFlow object is active in a control flow
         *
         *  \param[in] pFlow pointer to a concerete flow object
         *  \return active flow flag
         */
        bool IsActiveFlow(const oETCS::DF::CAbstractFlow * const pFlow) const throw();
        
        

        /*!
         *  \brief executes the state including data flow and possible transitions
         */
        void Execute() throw(::oETCS::DF::Error::CException);
        
        

        /*!
         *  \brief literal name of the state
         */
        const ::std::string m_Name;
        
        

        /*!
         *  \brief flag for a final state
         */
        const bool m_bIsFinal;
        
        


      private:
        /*!
         *  \brief pointer to the parent control flow object
         */
        CControlFlow* const m_pParent;
        
        

        /*!
         *  \brief vector with pointers to transition objects, which were activated
         */
        ::std::vector< oETCS::DF::CTransition* > m_TransitionStack;
        
        

        /*!
         *  \brief vector with pointers to all function block objects, which are executed in a state
         */
        const ::std::vector< oETCS::DF::CFunctionBlock* > m_FunctionBlocks;
        
        

        /*!
         *  \brief vector with pointer to all flows/connections used in a control flow state
         */
        ::std::vector< oETCS::DF::CAbstractFlow* > m_Flows;
        
        

  friend class oETCS::DF::CCondition;

    }; // class CState
    
    
    

    /*!
     *  \brief general constructor
     *
     *  \param[in] pStateMachine pointer to the contenting state machine
     */
    explicit CControlFlow(oETCS::DF::CEVCStateMachine * const pStateMachine) throw();
    
    

    /*!
     *  \brief destructor
     */
    virtual ~CControlFlow() throw();
    
    

    /*!
     *  \brief registers a new state object in a control flow
     *
     *  \param[in] pState pointer to state object to be registered
     *  \param[in] bIsInitial optional flag, if state is the initial state
     */
    void AddState(CState * const pState, const bool& bIsInitial) throw();
    
    

    /*!
     *  \brief returns true, if a CFunctionBlock objects is active in a control flow
     *
     *  \param[in] pFunctionBlock pointer to a function block object to be testetd
     *  \return active state flag
     */
    bool IsActiveFunctionBlock(const oETCS::DF::CFunctionBlock * const pFunctionBlock) const throw();
    
    

    /*!
     *  \brief returns true, if a CFlow object is active in a control flow
     *
     *  \param[in] pFlow pointer to a concerete flow object
     *  \return active flow flag
     */
    bool IsActiveFlow(const oETCS::DF::CAbstractFlow * const pFlow) const throw();
    
    

    /*!
     *  \brief gets the current state of the control flow
     *
     *  \return pointer to the current state object
     */
    CState* const GetCurrentState() const throw();
    
    

    /*!
     *  \brief virtual method for computing all outputs and setting the all referenced outputs
     *
     *  \remark must be implemented by any inheriting class
     */
    virtual void Calculate() throw(::oETCS::DF::Error::CException);
    
    

    /*!
     *  \brief storage of the start input value
     */
    oETCS::DF::BOOL_INPUT_T m_bStart;
    
    

    /*!
     *  \brief pointers to outputs for active state name
     */
    ::std::vector< oETCS::DF::STRING_OUTPUT_T > m_ActiveStateName;
    
    

    /*!
     *  \brief pointers to outputs for running flag
     */
    ::std::vector< oETCS::DF::BOOL_OUTPUT_T > m_IsRunning;
    
    


  private:
    /*!
     *  \brief vector with pointers to all available states in the control flow
     */
    ::std::vector< CState* > m_AvailableStates;
    
    

    /*!
     *  \brief pointer to current active state
     */
    CState* m_pCurrentState;
    
    

    /*!
     *  \brief pointer to the unique initial state object
     */
    CState* m_pInitialState;
    
    


}; // class CControlFlow : public oETCS::DF::CFunctionBlock





} // namespace oETCS::DF

} // namespace oETCS

#endif // __ OETCS_DF_CONTROLFLOW_H__