sp_executor.h
Go to the documentation of this file.
1 /** @file sp_executor.h Execute transitions in a timed generator */
2 
3 
4 /*
5  FAU Discrete Event Systems Library (libfaudes)
6 
7  Copyright (C) 2007 Ruediger Berndt
8  Copyright (C) 2007 Thomas Moor
9  Exclusive copyright is granted to Klaus Schmidt
10 
11 
12 */
13 
14 
15 
16 #ifndef FAUDES_SP_EXECUTOR_H
17 #define FAUDES_SP_EXECUTOR_H
18 
19 #include "corefaudes.h"
20 #include "tp_include.h"
21 
22 
23 // debugging: executor level
24 #ifdef FAUDES_DEBUG_EXECUTOR
25 #define FD_DX(message) FAUDES_WRITE_CONSOLE("FAUDES_EXECUTOR: " << message)
26 #else
27 #define FD_DX(message)
28 #endif
29 
30 // debugging: proposing executor level
31 #ifdef FAUDES_DEBUG_SIMULATOR
32 #define FD_DS(message) FAUDES_WRITE_CONSOLE("FAUDES_SIMULATOR: " << message)
33 #else
34 #define FD_DS(message)
35 #endif
36 
37 // debugging: device synchronization level
38 #ifdef FAUDES_DEBUG_SIMULATOR_SYNC
39 #define FD_DS_SYNC(message) FAUDES_WRITE_CONSOLE("FAUDES_RUNSYNC: " << message)
40 #else
41 #define FD_DS_SYNC(message)
42 #endif
43 
44 
45 
46 namespace faudes {
47 
48 
49 /** Global Tyoedefs */
50 
51 
52 /** typedef for external trace */
53 typedef struct {
56 } TimedEvent;
57 
58 /**
59  * An Executor is a timed generator that maintains a current state.
60  *
61  * The Executor is the lowest level building block for the libFAUDES simulator plugin.
62  * It maintains a current state that consists of
63  * - the discrete state;
64  * - a value map that assigns values to clock variables;
65  * - the current step aka logical time;
66  * - the current global clock aka clock time; as with faudes timed automata,
67  * clock time is in faudes-time units which may be mapped to physical time by a fixed
68  * conversion factor; see also DeviceExecutor.
69  * The state can be retrieved by the method Executor::CurrentState(void),
70  * and it is updated whenever time or transitions are executed via Executor::ExecuteTime(tpTime::Type)
71  * or Executor::ExecuteEvent(Idx). If you plan to execute multiple generators with synchronized shared
72  * events, you will find the class ParallelExecutor with a very similar interface more appropriate.
73  *
74  * The Executor provides Methods that indicate which transitions currently are enabled, referring to the
75  * current state, the current clock values and the guard and invariant data from the TimedGenerator.
76  * In contrast to enabled events, there is also the notion of active events, which refers to
77  * the discrete state only, ignoring guards and invariants.
78  *
79  * Technically, the Executor class is derived from the TimedGenerator, however inheritence is private.
80  * The common way to initialise an Executor object is to construct it from a const ref to a TimedGenerator,
81  * which sets up additional internal data structures. Read-only access to the underlying generator
82  * is given by the faudes::Executor::Generator() method.
83  *
84  * Note: a prequisit of the current implementation is that the underlying generator
85  * is deterministic ie the current discrete state is uniquely determind by the external
86  * sequence of discrete events.
87  *
88  *
89  * @ingroup SimulatorPlugin
90  */
91 
92 class Executor : protected TimedGenerator {
93 
95 
96  public:
97 
98 
99  /** Typedef for timed state */
100  typedef struct {
101  Idx State; // discrete state
102  std::map<Idx,tpTime::Type> ClockValue; // map clockindex to value
103  } TimedState;
104 
105 
106  /**
107  * Creates an emtpy Executer
108  */
109  Executor(void);
110 
111  /**
112  * Construct from tgenerator.
113  *
114  * Construction from a TimedGenerator will copy all given TimedGenerator data and complie it to
115  * some additional Executor specific data. Thus, if the original TimedGenerator changes
116  * the Executor will not reflect these changes.
117  *
118  * @param rGen
119  * Input generator
120  *
121  * @exception Exception
122  * - Nondetrministic input generator (id 501)
123  */
124  Executor(const TimedGenerator& rGen);
125 
126  /**
127  * Construct from TimedGenerator file.
128  *
129  * @param rFileName
130  * File to read
131  *
132  * @exception Exception
133  * - IO errors (id 1)
134  * - token mismatch (id 50, 51, 52, 80, 85)
135  * - nondetrministic generator (id 501)
136  */
137  Executor(const std::string& rFileName);
138 
139  /**
140  * Initialise from TimedGenerator.
141  *
142  * @param rGen
143  * Input generator
144  */
145  void Generator(const TimedGenerator& rGen);
146 
147 
148  /**
149  * Reference to the internal generator for inspection
150  *
151  * @return
152  * const reference of mTGen
153  */
154  const TimedGenerator& Generator(void) const;
155 
156  /**
157  * Generator name (for convenience)
158  *
159  */
160  const std::string& Name(void) const {return TimedGenerator::Name();} ;
161 
162  /**
163  * State name (for convenience)
164  *
165  */
166  std::string StateName(Idx idx) const {return TimedGenerator::StateName(idx);} ;
167 
168 
169  /**
170  * Event name (for convenience)
171  *
172  */
173  std::string EventName(Idx idx) const {return TimedGenerator::EventName(idx);} ;
174 
175 
176  /**
177  * Clear all data incl TimedGenerator
178  *
179  */
180  void Clear(void);
181 
182 
183  /**
184  * Reset all clocks and assign initial state.
185  */
186  void Reset();
187 
188  /**
189  * Get maximal interval of time that can pass without executing an event.
190  * This corresponds to the inveriant of the current timed state.
191  *
192  * @return TimeInterval
193  *
194  */
195  const TimeInterval& EnabledTime() const;
196 
197  /**
198  * Get set of events that are enabled at current (timed) state
199  *
200  * @return
201  * Set of enabled events
202  */
203  const EventSet& EnabledEvents() const;
204 
205  /**
206  * Get set of events that are disabled at current (timed) state
207  *
208  * @return
209  * Set of disabled events
210  */
211  const EventSet& DisabledEvents() const;
212 
213  /**
214  * Get maximal interval on which set of enabled events is constant
215  *
216  * @return TimeInterval
217  *
218  */
219  const TimeInterval& EnabledInterval() const;
220 
221 
222  /**
223  * Get interval on which an active event is enabled.
224  *
225  * @param event
226  * Active event
227  *
228  * @return TimeInterval
229  * (empty if event not active or active with guard violated)
230  *
231  */
232  TimeInterval EnabledEventTime(Idx event) const;
233 
234 
235  /**
236  * Get interval on which an active event satisfies its guard.
237  *
238  * @param event
239  * Active event
240  *
241  * @return TimeInterval
242  * (empty if event not active or active with guard violated)
243  *
244  */
245  TimeInterval EnabledGuardTime(Idx event) const;
246 
247 
248  /**
249  * Get set of events that are active at current (untimed) state.
250  *
251  * @return
252  * Set of active events
253  */
254  const EventSet& ActiveEventSet(void) const;
255 
256  /**
257  * Get set of transitions that are active at current (untimed) state
258  *
259  * @return
260  * Set of active trans
261  */
262  const TransSet& ActiveTransSet(void) const;
263 
264  /**
265  * Let time pass. Returns false if the specified amount
266  * of time cannot elapse without an event being executed
267  *
268  * @param time
269  * Amount of time that shall elapse.
270  * @return
271  * True/false -- success
272  */
273  bool ExecuteTime(tpTime::Type time);
274 
275  /**
276  * Execute transition. Returns false if the transition
277  * is not enabled and hence cannot be executed at the current time
278  *
279  * @param event
280  * Indicate transition to execute
281  * @return
282  * True/false -- success
283  */
284  bool ExecuteEvent(Idx event);
285 
286  /**
287  * Set timed state. Returns false if state or clock values are invalid.
288  *
289  * @param tstate
290  * State to set.
291  *
292  * @return
293  * True/false -- success
294  */
295  bool CurrentTimedState(const TimedState& tstate);
296 
297  /**
298  * Get timed state.
299  *
300  * @return
301  * Current discrete state and clock values.
302  */
303  const TimedState& CurrentTimedState(void) const;
304 
305  /**
306  * Set discrete state. Returns false if state is not
307  * in state set.
308  *
309  * @param index
310  * State index
311  *
312  * @return
313  * True/false -- success
314  */
315  bool CurrentState(Idx index);
316 
317  /**
318  * Get discrete state.
319  *
320  * @return
321  * Discret state by index
322  */
323  Idx CurrentState(void) const;
324 
325  /**
326  * Set value of clock variable.
327  * Returns false if clock not in clockset.
328  *
329  * @param clock
330  * Index of clock variable to set
331  * @param time
332  * Time to set
333  * @return
334  * True/false -- success
335  */
336  bool CurrentClockValue(Idx clock, tpTime::Type time);
337 
338  /**
339  * Get value of clock
340  *
341  * @param clock
342  * Index of clock variable
343  * @return time
344  * Value of clock variable
345  */
346  tpTime::Type CurrentClockValue(Idx clock) const;
347 
348  /**
349  * Set current time.
350  *
351  * @param time
352  * New current time
353  */
354  void CurrentTime(tpTime::Type time);
355 
356  /**
357  * Get current time
358  *
359  * @return time
360  * Current time
361  */
362  tpTime::Type CurrentTime(void) const;
363 
364  /**
365  * Set logic time (# of steps)
366  *
367  * @param step
368  * New logic time
369  */
370  void CurrentStep(int step);
371 
372 
373  /**
374  * Get logic time ie numer of transitions so far.
375  *
376  */
377  int CurrentStep(void) const;
378 
379  /**
380  * Returns true if timed generator is in a deadlocked state.
381  *
382  * @return true/false
383  */
384  bool IsDeadlocked() const;
385 
386 
387  /**
388  * Check if Executor is valid.
389  * Not implemented, should check for determinism and consitency of current state and clock values.
390  *
391  * @return
392  * Success
393  */
394  virtual bool Valid(void) const {return true;};
395 
396 
397  /**
398  * Pretty printable string of current state
399  */
400  std::string CurrentTimedStateStr(void) const;
401 
402  /**
403  * Pretty printable string of timed state
404  */
405  std::string TSStr(const TimedState& tstate) const;
406 
407  /**
408  * Pretty printable string of timed event
409  */
410  std::string TEStr(const TimedEvent& tevent) const;
411 
412  /**
413  * Pretty printable string of clock name
414  */
415  std::string CStr(Idx idx) const;
416 
417  /**
418  * Pretty printable string of event
419  */
420  std::string EStr(Idx idx) const;
421 
422  /**
423  * Pretty printable string of state
424  */
425  std::string SStr(Idx idx) const;
426 
427  // std faudes type interface
428  using TimedGenerator::Read;
429  using TimedGenerator::Write;
430 
431  protected:
432 
433  /**
434  * Assignment method.
435  *
436  * @param rSrc
437  * Source to assign from
438  */
439  virtual void DoAssign(const Executor& rSrc);
440 
441  /**
442  * Reads configuration from TokenReader, see Typefor public wrappers.
443  *
444  * @param rTr
445  * TokenReader to read from
446  * @param rLabel
447  * Section to read
448  * @param pContext
449  * Read context to provide contextual information
450  *
451  * @exception Exception
452  * - IO error (id 1)
453  */
454  virtual void DoRead(TokenReader& rTr, const std::string& rLabel="", const Type* pContext=0);
455 
456  /**
457  * Writes configuration to TokenWriter, see Type for public wrappers.
458  *
459  * @param rTw
460  * TokenWriter to write to
461  * @param rLabel
462  * Section to write
463  * @param pContext
464  * Write context to provide contextual information
465  *
466  * @exception Exception
467  * - IO error (id 2)
468  */
469  virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
470 
471 
472 
473 
474  private:
475 
476  /** Current state incl clock values */
478 
479  /** Current clock time */
481 
482  /** Current logic time */
484 
485  /** Prepare internal data structurs from generator */
486  void Compile(void);
487 
488  /** Compute enabled events and enabled interval (fake const) */
489  void ComputeEnabled(void) const;
490 
491  /** Compute enabled core routine (non const) */
492  void ComputeEnabledNonConst(void);
493 
494  /** Record enabled time */
496 
497  /** Record enabled events */
499 
500  /** Record rime on shich mEEvents is constant */
502 
503  /** Record interval in which each guard is enabled */
504  std::map<Idx,TimeInterval> mEGuardInterval;
505 
506  /** Record disabled events */
508 
509  /** Record active events (ie regardles time) */
511 
512  /** Record active transitions (regardles time) */
514 
515  /** Validity flag for the above data */
516  bool mEValid;
517 
518  /** Compiled generator data: map transition to clock to interval constraint */
519  std::map<Transition, std::map<Idx,TimeInterval> > mTransClockIntervalMap;
520 
521  /** Compiled generator data: map state to clock to interval constraint */
522  std::map<Idx, std::map<Idx,TimeInterval> > mStateClockIntervalMap;
523 
524 }; // end class Executor
525 
526 
527 
528 } // namespace faudes
529 
530 
531 #endif
532 

libFAUDES 2.26g --- 2015.08.17 --- c++ api documentaion by doxygen