sp_executor.hGo 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 |