libFAUDES

Sections

Index

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 executor 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 tGenerator.
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 tGenerator, however inheritence is private.
00080  * The common way to initialise an Executor object is to construct it from a const ref to a tGenerator,
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 : private tGenerator {      
00093     public:
00094            
00095 
00096     /** Typedef for timed state */
00097     typedef struct {
00098       Idx State;                       // discrete state
00099       std::map<Idx,tpTime::Type> ClockValue; // map clockindex to value
00100     } TimedState;
00101 
00102 
00103    /**
00104     * Creates an emtpy Executer
00105     */
00106     Executor(void);
00107 
00108    /** 
00109     * Construct from tgenerator. 
00110     *
00111     * Construction from a tGenerator will copy all given tGenerator data and complie it to
00112     * some additional Executor specific data. Thus, if the original tGenerator changes
00113     * the Executor will not reflect these changes.
00114     *
00115     * @param rGen
00116     *   Input generator
00117     *
00118     * @exception Exception
00119     *   - Nondetrministic input generator (id 501)
00120     */
00121     Executor(const tGenerator& rGen);
00122 
00123    /**
00124     * Construct from tGenerator file.
00125     *
00126     * @param rFileName
00127     *   File to read
00128     *
00129     * @exception Exception
00130     *   - IO errors (id 1)
00131     *   - token mismatch (id 50, 51, 52, 80, 85)
00132     *   - nondetrministic generator (id 501)
00133     */
00134     Executor(const std::string& rFileName);
00135 
00136    /**
00137     * Read tGenerator file
00138     *
00139     * @param rFileName
00140     *   File to read
00141     *
00142     * @exception Exception
00143     *   - IO errors (id 1)
00144     *   - token mismatch (id 50, 51, 52, 80, 85)
00145     *   - nondetrministic generator (id 501)
00146     */
00147     void Read(const std::string& rFileName);
00148 
00149    /**
00150     * Read form tokenreader
00151     *
00152     * @param rTr
00153     *   tokenreader
00154     *
00155     * @exception Exception
00156     *   - IO errors (id 1)
00157     *   - token mismatch (id 50, 51, 52, 80, 85)
00158     *   - nondetrministic generator (id 501)
00159     */
00160     void Read(TokenReader& rTr);
00161 
00162    /**
00163     * Write to tokenwriter
00164     *
00165     * @param rTw
00166     *   WokenWriter
00167     *
00168     * @exception Exception
00169     *   - IO errors (id 2)
00170     */
00171     void Write(TokenWriter& rTw) const { tGenerator::Write(rTw); };
00172 
00173    /**
00174     * Write to file
00175     *
00176     * @param rFileName
00177     *   File to write
00178     * @param openmode
00179     *   ios::openmode 
00180     *
00181     * @exception Exception
00182     *   - IO errors (id 2)
00183     */
00184     void Write(const std::string& rFileName, std::ios::openmode openmode = std::ios::out|std::ios::trunc)
00185     { tGenerator::Write(rFileName,"",0,openmode); };
00186 
00187     /**
00188      * Initialise from tGenerator.
00189      *
00190      *  @param rGen 
00191      *    Input generator
00192      */
00193     void Generator(const tGenerator& rGen);
00194   
00195 
00196     /**
00197      * Reference to the internal generator for inspection
00198      *
00199      *  @return 
00200      * const reference of mTGen
00201      */
00202     const tGenerator& Generator(void) const;
00203       
00204     /**
00205      * Generator name (for convenience)
00206      *
00207      */
00208     const std::string& Name(void) const {return tGenerator::Name();} ;
00209 
00210     /**
00211      * State name (for convenience)
00212      *
00213      */
00214     std::string StateName(Idx idx) const {return tGenerator::StateName(idx);} ;
00215 
00216   
00217     /**
00218      * Event name (for convenience)
00219      *
00220      */
00221     std::string EventName(Idx idx) const {return tGenerator::EventName(idx);} ;
00222 
00223   
00224     /**
00225      * Clear all data incl tGenerator
00226      *
00227      */
00228     void Clear(void);
00229 
00230 
00231     /** 
00232      * Reset all clocks and assign initial state.
00233      */
00234     void Reset();
00235 
00236     /**
00237      * Get maximal interval of time that can pass without executing an event.
00238      * This corresponds to the inveriant of the current timed state.
00239      *
00240      *  @return TimeInterval 
00241      *  
00242      */
00243     const TimeInterval& EnabledTime() const;
00244 
00245     /**
00246      *  Get set of events that are enabled at current (timed) state
00247      *
00248      *  @return 
00249      *     Set of enabled events
00250      */
00251     const EventSet& EnabledEvents() const;
00252 
00253     /**
00254      *  Get set of events that are disabled at current (timed) state
00255      *
00256      *  @return 
00257      *     Set of disabled events
00258      */
00259     const EventSet& DisabledEvents() const;
00260 
00261     /**
00262      *  Get maximal interval on which set of enabled events is constant
00263      *
00264      *  @return TimeInterval 
00265      *  
00266      */
00267     const TimeInterval& EnabledInterval() const;
00268   
00269 
00270     /**
00271      *  Get interval on which an active event is enabled. 
00272      *
00273      *  @param event
00274      *     Active event
00275      *
00276      *  @return TimeInterval 
00277      *     (empty if event not active or active with guard violated) 
00278      *  
00279      */
00280     TimeInterval EnabledEventTime(Idx event) const;
00281 
00282 
00283     /**
00284      *  Get interval on which an active event satisfies its guard. 
00285      *
00286      *  @param event
00287      *     Active event
00288      *
00289      *  @return TimeInterval 
00290      *     (empty if event not active or active with guard violated) 
00291      *  
00292      */
00293     TimeInterval EnabledGuardTime(Idx event) const;
00294 
00295 
00296     /**
00297      *  Get set of events that are active at current (untimed) state.
00298      *
00299      *  @return 
00300      *     Set of active events
00301      */
00302     const EventSet& ActiveEventSet(void) const;
00303 
00304     /**
00305      *  Get set of transitions that are active at current (untimed) state
00306      *
00307      *  @return 
00308      *     Set of active trans
00309      */
00310     const TransSet& ActiveTransSet(void) const;
00311 
00312     /** 
00313      * Let time pass. Returns false if the specified amount 
00314      * of time cannot elapse without an event being executed
00315      *
00316      * @param time
00317      *    Amount of time that shall elapse.
00318      * @return
00319      *   True/false -- success
00320      */
00321      bool ExecuteTime(tpTime::Type time);
00322 
00323     /** 
00324      * Execute transition. Returns false if the transition
00325      * is not enabled and hence cannot be executed at the current time
00326      *
00327      * @param event
00328      *    Indicate transition to execute
00329      * @return
00330      *   True/false -- success
00331      */
00332      bool ExecuteEvent(Idx event);
00333 
00334      /** 
00335       * Set timed state. Returns false if state or clock values are invalid.
00336       *
00337       * @param tstate
00338       *  State to set. 
00339       *
00340       * @return
00341       *   True/false -- success
00342       */
00343      bool CurrentTimedState(const TimedState& tstate);
00344  
00345      /** 
00346       * Get timed state.
00347       *
00348       * @return
00349       *   Current discrete state and clock values. 
00350       */
00351      const TimedState& CurrentTimedState(void) const;
00352  
00353      /** 
00354       * Set discrete state. Returns false if state is not 
00355       * in state set.
00356       *
00357       * @param index
00358       *  State index
00359       *
00360       * @return
00361       *   True/false -- success
00362       */
00363      bool CurrentState(Idx index);
00364  
00365      /** 
00366       * Get discrete state. 
00367       *
00368       * @return
00369       *   Discret state by index
00370       */
00371      Idx CurrentState(void) const;
00372  
00373      /** 
00374       * Set value of clock variable.
00375       * Returns false if clock not in clockset. 
00376       *
00377       * @param clock
00378       *    Index of clock variable to set 
00379       * @param time
00380       *    Time to set 
00381       * @return
00382       *   True/false -- success
00383       */
00384       bool CurrentClockValue(Idx clock, tpTime::Type time);
00385       
00386      /** 
00387       * Get value of clock
00388       *
00389       * @param clock
00390       *    Index of clock variable
00391       * @return time
00392       *    Value of clock variable 
00393       */
00394       tpTime::Type CurrentClockValue(Idx clock) const;
00395                     
00396      /** 
00397       * Set current time.
00398       *
00399       * @param time
00400       *    New current time 
00401       */
00402       void CurrentTime(tpTime::Type time);
00403 
00404      /** 
00405       * Get current time
00406       *
00407       * @return time
00408       *    Current time
00409       */
00410       tpTime::Type CurrentTime(void) const;
00411 
00412      /** 
00413       * Set logic time (# of steps)
00414       *
00415       * @param step
00416       *    New logic time 
00417       */
00418       void CurrentStep(int step);
00419 
00420     
00421       /** 
00422        * Get logic time ie numer of transitions so far.
00423        *
00424        */
00425       int CurrentStep(void) const;
00426 
00427       /** 
00428        * Returns true if timed generator is in a deadlocked state.
00429        *
00430        *  @return true/false
00431        */
00432       bool IsDeadlocked() const;
00433       
00434       
00435       /** 
00436        * Check if Executor is valid. 
00437        * Not implemented, should check for determinism and consitency of current state and clock values.
00438        *
00439        * @return 
00440        *   Success
00441        */
00442       virtual bool Valid(void) const {return true;};
00443 
00444 
00445       /** 
00446        * Pretty printable string of current state
00447        */
00448       std::string CurrentTimedStateStr(void) const;
00449       
00450       /** 
00451        * Pretty printable string of timed state
00452        */
00453       std::string TSStr(const TimedState& tstate) const;
00454 
00455       /** 
00456        * Pretty printable string of timed event
00457        */
00458       std::string TEStr(const TimedEvent& tevent) const;
00459 
00460       /** 
00461        * Pretty printable string of clock name
00462        */
00463       std::string CStr(Idx idx) const;
00464 
00465       /** 
00466        * Pretty printable string of event
00467        */
00468       std::string EStr(Idx idx) const;
00469 
00470       /** 
00471        * Pretty printable string of state
00472        */
00473       std::string SStr(Idx idx) const;
00474 
00475 
00476  private:
00477      
00478     /** Current state incl clock values */
00479     TimedState mCurrentTimedState;
00480 
00481     /** Current clock time */
00482     tpTime::Type mCurrentTime;
00483 
00484     /** Current logic time */
00485     int mCurrentStep;
00486 
00487     /** Prepare internal data structurs from generator */
00488     void Compile(void);
00489 
00490     /** Compute enabled events and enabled interval (fake const) */
00491     void ComputeEnabled(void) const;
00492 
00493     /** Compute enabled core routine (non const) */
00494     void ComputeEnabledNonConst(void);
00495 
00496     /** Record enabled time */
00497     TimeInterval mETime;
00498 
00499     /** Record enabled events */
00500     EventSet mEEvents;
00501 
00502     /** Record rime on shich mEEvents is constant  */
00503     TimeInterval mEInterval;
00504 
00505     /** Record interval in which each guard is enabled  */
00506     std::map<Idx,TimeInterval> mEGuardInterval;
00507 
00508     /** Record disabled events */
00509     EventSet mDEvents;
00510 
00511     /** Record active events (ie regardles time) */
00512     EventSet mAEvents;
00513 
00514     /** Record active transitions (regardles time) */
00515     TransSet mATrans;
00516 
00517     /** Validity flag for the above data */
00518     bool mEValid;
00519 
00520     /** Compiled generator data: map transition to clock to interval constraint */
00521     std::map<Transition, std::map<Idx,TimeInterval> > mTransClockIntervalMap;
00522 
00523     /** Compiled generator data: map state to clock to interval constraint */
00524     std::map<Idx, std::map<Idx,TimeInterval> > mStateClockIntervalMap;
00525 
00526 }; // end class Executor
00527 
00528 
00529 
00530 } // namespace faudes
00531 
00532 
00533 #endif
00534 

libFAUDES 2.16b --- 2010-9-8 --- c++ source docu by doxygen 1.6.3