sp_executor.h

Go to the documentation of this file.
00001 /** @file sp_executor.h Execute transitions in a timed generator  */
00002 
00003 
00004 /* 
00005    FAU Discrete Event Systems Library (libfaudes)
00006 
00007    Copyright (C) 2007  Ruediger Berndt
00008    Copyright (C) 2007  Thomas Moor
00009    Exclusive copyright is granted to Klaus Schmidt
00010 
00011 
00012 */
00013 
00014 
00015 
00016 #ifndef FAUDES_SP_EXECUTOR_H
00017 #define FAUDES_SP_EXECUTOR_H
00018 
00019 #include "corefaudes.h"
00020 #include "tp_include.h"
00021 
00022 
00023 // debugging: executor level
00024 #ifdef FAUDES_DEBUG_EXECUTOR
00025 #define FD_DX(message) FAUDES_WRITE_CONSOLE("FAUDES_EXECUTOR: " << message)
00026 #else
00027 #define FD_DX(message)
00028 #endif
00029 
00030 // debugging: proposing executor level
00031 #ifdef FAUDES_DEBUG_SIMULATOR
00032 #define FD_DS(message) FAUDES_WRITE_CONSOLE("FAUDES_SIMULATOR: " << message)
00033 #else
00034 #define FD_DS(message)
00035 #endif
00036 
00037 // debugging: device synchronization level
00038 #ifdef FAUDES_DEBUG_SIMULATOR_SYNC
00039 #define FD_DS_SYNC(message) FAUDES_WRITE_CONSOLE("FAUDES_RUNSYNC: " << message)
00040 #else
00041 #define FD_DS_SYNC(message)
00042 #endif
00043 
00044 
00045 
00046 namespace faudes {
00047 
00048 
00049 /** Global Tyoedefs */
00050    
00051 
00052 /** typedef for external trace */
00053 typedef struct {
00054   Idx Event;
00055   tpTime::Type Time;
00056 } TimedEvent;
00057 
00058 /**
00059  * An Executor is a timed generator that maintains a current state. 
00060  * 
00061  * The Executor is the lowest level building block for the libFAUDES simulator plugin.
00062  * It maintains a current state that consists of 
00063  *  - the discrete state;
00064  *  - a value map that assigns values to clock variables;
00065  *  - the current step aka logical time;
00066  *  - the current global clock aka clock time; as with faudes timed automata,
00067  *    clock time is in faudes-time units which may be mapped to physical time by a fixed
00068  *    conversion factor; see also DeviceExecutor.
00069  * The state can be retrieved by the method Executor::CurrentState(void), 
00070  * and it is updated whenever time or transitions are executed via Executor::ExecuteTime(tpTime::Type) 
00071  * or Executor::ExecuteEvent(Idx). If you plan to execute multiple generators with synchronized shared 
00072  * events, you will find the class ParallelExecutor with a very similar interface more appropriate.
00073  *
00074  * The Executor provides Methods that indicate which transitions currently are enabled, referring to the
00075  * current state, the current clock values and the guard and invariant data from the TimedGenerator.
00076  * In contrast to enabled events, there is also the notion of active events, which refers to
00077  * the discrete state only, ignoring guards and invariants.
00078  * 
00079  * Technically, the Executor class is derived from the TimedGenerator, however inheritence is private.
00080  * The common way to initialise an Executor object is to construct it from a const ref to a TimedGenerator,
00081  * which sets up additional internal data structures. Read-only access to the underlying generator
00082  * is given by the faudes::Executor::Generator() method.
00083  *
00084  * Note: a prequisit of the current implementation is that the underlying generator
00085  * is deterministic ie the current discrete state is uniquely determind by the external
00086  * sequence of discrete events.
00087  *
00088  *
00089  * @ingroup SimulatorPlugin 
00090  */
00091 
00092 class Executor : protected TimedGenerator {      
00093 
00094 FAUDES_TYPE_DECLARATION(Executor,Executor,TimedGenerator)
00095 
00096     public:
00097            
00098 
00099     /** Typedef for timed state */
00100     typedef struct {
00101       Idx State;                       // discrete state
00102       std::map<Idx,tpTime::Type> ClockValue; // map clockindex to value
00103     } TimedState;
00104 
00105 
00106    /**
00107     * Creates an emtpy Executer
00108     */
00109     Executor(void);
00110 
00111    /** 
00112     * Construct from tgenerator. 
00113     *
00114     * Construction from a TimedGenerator will copy all given TimedGenerator data and complie it to
00115     * some additional Executor specific data. Thus, if the original TimedGenerator changes
00116     * the Executor will not reflect these changes.
00117     *
00118     * @param rGen
00119     *   Input generator
00120     *
00121     * @exception Exception
00122     *   - Nondetrministic input generator (id 501)
00123     */
00124     Executor(const TimedGenerator& rGen);
00125 
00126    /**
00127     * Construct from TimedGenerator file.
00128     *
00129     * @param rFileName
00130     *   File to read
00131     *
00132     * @exception Exception
00133     *   - IO errors (id 1)
00134     *   - token mismatch (id 50, 51, 52, 80, 85)
00135     *   - nondetrministic generator (id 501)
00136     */
00137     Executor(const std::string& rFileName);
00138 
00139     /**
00140      * Initialise from TimedGenerator.
00141      *
00142      *  @param rGen 
00143      *    Input generator
00144      */
00145     void Generator(const TimedGenerator& rGen);
00146   
00147 
00148     /**
00149      * Reference to the internal generator for inspection
00150      *
00151      *  @return 
00152      * const reference of mTGen
00153      */
00154     const TimedGenerator& Generator(void) const;
00155       
00156     /**
00157      * Generator name (for convenience)
00158      *
00159      */
00160     const std::string& Name(void) const {return TimedGenerator::Name();} ;
00161 
00162     /**
00163      * State name (for convenience)
00164      *
00165      */
00166     std::string StateName(Idx idx) const {return TimedGenerator::StateName(idx);} ;
00167 
00168   
00169     /**
00170      * Event name (for convenience)
00171      *
00172      */
00173     std::string EventName(Idx idx) const {return TimedGenerator::EventName(idx);} ;
00174 
00175   
00176     /**
00177      * Clear all data incl TimedGenerator
00178      *
00179      */
00180     void Clear(void);
00181 
00182 
00183     /** 
00184      * Reset all clocks and assign initial state.
00185      */
00186     void Reset();
00187 
00188     /**
00189      * Get maximal interval of time that can pass without executing an event.
00190      * This corresponds to the inveriant of the current timed state.
00191      *
00192      *  @return TimeInterval 
00193      *  
00194      */
00195     const TimeInterval& EnabledTime() const;
00196 
00197     /**
00198      *  Get set of events that are enabled at current (timed) state
00199      *
00200      *  @return 
00201      *     Set of enabled events
00202      */
00203     const EventSet& EnabledEvents() const;
00204 
00205     /**
00206      *  Get set of events that are disabled at current (timed) state
00207      *
00208      *  @return 
00209      *     Set of disabled events
00210      */
00211     const EventSet& DisabledEvents() const;
00212 
00213     /**
00214      *  Get maximal interval on which set of enabled events is constant
00215      *
00216      *  @return TimeInterval 
00217      *  
00218      */
00219     const TimeInterval& EnabledInterval() const;
00220   
00221 
00222     /**
00223      *  Get interval on which an active event is enabled. 
00224      *
00225      *  @param event
00226      *     Active event
00227      *
00228      *  @return TimeInterval 
00229      *     (empty if event not active or active with guard violated) 
00230      *  
00231      */
00232     TimeInterval EnabledEventTime(Idx event) const;
00233 
00234 
00235     /**
00236      *  Get interval on which an active event satisfies its guard. 
00237      *
00238      *  @param event
00239      *     Active event
00240      *
00241      *  @return TimeInterval 
00242      *     (empty if event not active or active with guard violated) 
00243      *  
00244      */
00245     TimeInterval EnabledGuardTime(Idx event) const;
00246 
00247 
00248     /**
00249      *  Get set of events that are active at current (untimed) state.
00250      *
00251      *  @return 
00252      *     Set of active events
00253      */
00254     const EventSet& ActiveEventSet(void) const;
00255 
00256     /**
00257      *  Get set of transitions that are active at current (untimed) state
00258      *
00259      *  @return 
00260      *     Set of active trans
00261      */
00262     const TransSet& ActiveTransSet(void) const;
00263 
00264     /** 
00265      * Let time pass. Returns false if the specified amount 
00266      * of time cannot elapse without an event being executed
00267      *
00268      * @param time
00269      *    Amount of time that shall elapse.
00270      * @return
00271      *   True/false -- success
00272      */
00273      bool ExecuteTime(tpTime::Type time);
00274 
00275     /** 
00276      * Execute transition. Returns false if the transition
00277      * is not enabled and hence cannot be executed at the current time
00278      *
00279      * @param event
00280      *    Indicate transition to execute
00281      * @return
00282      *   True/false -- success
00283      */
00284      bool ExecuteEvent(Idx event);
00285 
00286      /** 
00287       * Set timed state. Returns false if state or clock values are invalid.
00288       *
00289       * @param tstate
00290       *  State to set. 
00291       *
00292       * @return
00293       *   True/false -- success
00294       */
00295      bool CurrentTimedState(const TimedState& tstate);
00296  
00297      /** 
00298       * Get timed state.
00299       *
00300       * @return
00301       *   Current discrete state and clock values. 
00302       */
00303      const TimedState& CurrentTimedState(void) const;
00304  
00305      /** 
00306       * Set discrete state. Returns false if state is not 
00307       * in state set.
00308       *
00309       * @param index
00310       *  State index
00311       *
00312       * @return
00313       *   True/false -- success
00314       */
00315      bool CurrentState(Idx index);
00316  
00317      /** 
00318       * Get discrete state. 
00319       *
00320       * @return
00321       *   Discret state by index
00322       */
00323      Idx CurrentState(void) const;
00324  
00325      /** 
00326       * Set value of clock variable.
00327       * Returns false if clock not in clockset. 
00328       *
00329       * @param clock
00330       *    Index of clock variable to set 
00331       * @param time
00332       *    Time to set 
00333       * @return
00334       *   True/false -- success
00335       */
00336       bool CurrentClockValue(Idx clock, tpTime::Type time);
00337       
00338      /** 
00339       * Get value of clock
00340       *
00341       * @param clock
00342       *    Index of clock variable
00343       * @return time
00344       *    Value of clock variable 
00345       */
00346       tpTime::Type CurrentClockValue(Idx clock) const;
00347                     
00348      /** 
00349       * Set current time.
00350       *
00351       * @param time
00352       *    New current time 
00353       */
00354       void CurrentTime(tpTime::Type time);
00355 
00356      /** 
00357       * Get current time
00358       *
00359       * @return time
00360       *    Current time
00361       */
00362       tpTime::Type CurrentTime(void) const;
00363 
00364      /** 
00365       * Set logic time (# of steps)
00366       *
00367       * @param step
00368       *    New logic time 
00369       */
00370       void CurrentStep(int step);
00371 
00372     
00373       /** 
00374        * Get logic time ie numer of transitions so far.
00375        *
00376        */
00377       int CurrentStep(void) const;
00378 
00379       /** 
00380        * Returns true if timed generator is in a deadlocked state.
00381        *
00382        *  @return true/false
00383        */
00384       bool IsDeadlocked() const;
00385       
00386       
00387       /** 
00388        * Check if Executor is valid. 
00389        * Not implemented, should check for determinism and consitency of current state and clock values.
00390        *
00391        * @return 
00392        *   Success
00393        */
00394       virtual bool Valid(void) const {return true;};
00395 
00396 
00397       /** 
00398        * Pretty printable string of current state
00399        */
00400       std::string CurrentTimedStateStr(void) const;
00401       
00402       /** 
00403        * Pretty printable string of timed state
00404        */
00405       std::string TSStr(const TimedState& tstate) const;
00406 
00407       /** 
00408        * Pretty printable string of timed event
00409        */
00410       std::string TEStr(const TimedEvent& tevent) const;
00411 
00412       /** 
00413        * Pretty printable string of clock name
00414        */
00415       std::string CStr(Idx idx) const;
00416 
00417       /** 
00418        * Pretty printable string of event
00419        */
00420       std::string EStr(Idx idx) const;
00421 
00422       /** 
00423        * Pretty printable string of state
00424        */
00425       std::string SStr(Idx idx) const;
00426 
00427       // std faudes type interface
00428       using TimedGenerator::Read;
00429       using TimedGenerator::Write;
00430 
00431  protected:
00432 
00433   /**
00434    * Assignment method. 
00435    *
00436    * @param rSrc
00437    *    Source to assign from
00438    */
00439   virtual void DoAssign(const Executor& rSrc);
00440 
00441   /**
00442    * Reads configuration from TokenReader, see Typefor public wrappers.
00443    *
00444    * @param rTr
00445    *   TokenReader to read from
00446    * @param rLabel
00447    *   Section to read
00448    * @param pContext
00449    *   Read context to provide contextual information
00450    *
00451    * @exception Exception
00452    *   - IO error (id 1)
00453    */
00454   virtual void DoRead(TokenReader& rTr, const std::string& rLabel="", const Type* pContext=0);
00455  
00456   /**
00457    * Writes configuration to TokenWriter, see Type for public wrappers.
00458    *
00459    * @param rTw
00460    *   TokenWriter to write to
00461    * @param rLabel
00462    *   Section to write
00463    * @param pContext
00464    *   Write context to provide contextual information
00465    *
00466    * @exception Exception
00467    *   - IO error (id 2)
00468    */
00469   virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00470 
00471 
00472 
00473 
00474  private:
00475      
00476     /** Current state incl clock values */
00477     TimedState mCurrentTimedState;
00478 
00479     /** Current clock time */
00480     tpTime::Type mCurrentTime;
00481 
00482     /** Current logic time */
00483     int mCurrentStep;
00484 
00485     /** Prepare internal data structurs from generator */
00486     void Compile(void);
00487 
00488     /** Compute enabled events and enabled interval (fake const) */
00489     void ComputeEnabled(void) const;
00490 
00491     /** Compute enabled core routine (non const) */
00492     void ComputeEnabledNonConst(void);
00493 
00494     /** Record enabled time */
00495     TimeInterval mETime;
00496 
00497     /** Record enabled events */
00498     EventSet mEEvents;
00499 
00500     /** Record rime on shich mEEvents is constant  */
00501     TimeInterval mEInterval;
00502 
00503     /** Record interval in which each guard is enabled  */
00504     std::map<Idx,TimeInterval> mEGuardInterval;
00505 
00506     /** Record disabled events */
00507     EventSet mDEvents;
00508 
00509     /** Record active events (ie regardles time) */
00510     EventSet mAEvents;
00511 
00512     /** Record active transitions (regardles time) */
00513     TransSet mATrans;
00514 
00515     /** Validity flag for the above data */
00516     bool mEValid;
00517 
00518     /** Compiled generator data: map transition to clock to interval constraint */
00519     std::map<Transition, std::map<Idx,TimeInterval> > mTransClockIntervalMap;
00520 
00521     /** Compiled generator data: map state to clock to interval constraint */
00522     std::map<Idx, std::map<Idx,TimeInterval> > mStateClockIntervalMap;
00523 
00524 }; // end class Executor
00525 
00526 
00527 
00528 } // namespace faudes
00529 
00530 
00531 #endif
00532 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen