tp_timeconstraint.h
Go to the documentation of this file.
1 /** @file tp_timeconstraint.h Classes ClockSet, ElemConstraint and TimeConstraint */
2 
3 
4 
5 /* Timeplugin for FAU Discrete Event Systems Library (libfaudes)
6 
7  Copyright (C) 2006 B Schlein
8  Copyright (C) 2007 Thomas Moor
9  Exclusive copyright is granted to Klaus Schmidt
10 
11 */
12 
13 #ifndef FAUDES_TP_TIMECONSTRAINT_H
14 #define FAUDES_TP_TIMECONSTRAINT_H
15 
16 #include "corefaudes.h"
17 #include "tp_timeinterval.h"
18 #include <list>
19 
20 
21 namespace faudes {
22 
23 
24 
25 /**
26  * Container class to model a set of clocks.
27  * Technically, this is a NameSet with a static SymbolTable to map
28  * symbolic clock names to clock indices. Thus, clock names are
29  * global similar to event names. Note that clocksets of individual
30  * TtGenerators are assumed to be disjoint.
31  *
32  * Todo: explicitely inherit other constructors (!)
33  *
34  * @ingroup TimedPlugin
35  *
36  */
37 
38 class ClockSet : public NameSet {
39 
41 
42  public:
43 
44  /**
45  * Constructor
46  */
47  ClockSet(void);
48 
49  /**
50  * Copy-constructor.
51  *
52  * @param rOtherSet
53  * Set to copy
54  */
55  ClockSet(const ClockSet& rOtherSet);
56 
57  /**
58  * Construct from file.
59  * Uses the NameSet's Read() function to scan a file for a
60  * specified clockset.
61  *
62  * @param rFilename
63  * File to read
64  * @param rLabel
65  * Section label for the clocks in the file; default value "Clocks"
66  */
67  ClockSet(const std::string& rFilename, const std::string& rLabel = "Clocks");
68 
69  /**
70  * Get pointer to static clock SymbolTable
71  *
72  * @return
73  * Pointer to static clock SymbolTable
74  */
75  static SymbolTable* StaticSymbolTablep(void);
76 
77  protected:
78 
79  /** Static global SymbolTable for clock names */
81 
82  /**
83  * Assign from other clock set.
84  *
85  * @param rSourceSet
86  * Destination to copy from
87  * @return
88  * ref to this set
89  */
90  virtual void DoAssign(const ClockSet& rSourceSet);
91 
92  /**
93  * Test equality with other clock set.
94  *
95  * @param rOtherSet
96  * Set to compare with
97  * @return
98  * True/false
99  */
100  virtual bool DoEqual(const ClockSet& rOtherSet) const;
101 
102 }; // end class ClockSet
103 
104 
105 
106 /**
107  * Model of an elementary clock constraint formula. The constraint consists of an index
108  * of a clock, a comperative operator and a constant time value.
109  * Semantically, an elementary contraint is satisfied at a time t if at that time
110  * the clock value compares true with the constant time.
111  * The clock index 0 is used to indicate an invalid contraint. It is only the
112  * context of the more general TimeContraint that provides
113  * a reference to a clock SymbolTable.
114  *
115  * @param mClock
116  * Clock index
117  *
118  * @param mCompOperator
119  * Symbolic integer value for comperative operator
120  *
121  * @param mTimeConstant
122  * Time constant for comparison
123  *
124  * @ingroup TimedPlugin
125  *
126  */
127 
129 
130  public:
131 
132  /**
133  * Typedef for comparison operators in elementary clock constraints
134  *
135  */
137 
138  /**
139  * Conversion from symbolic operator to string
140  */
141  static std::string OperatorName(Operator op);
142 
143  /**
144  * Construct an (invalid) elementary clock constraint (clockindex 0)
145  *
146  */
147  ElemConstraint(void);
148 
149  /**
150  * Construct an elementary clock constraint from values
151  *
152  * @param clockindex
153  * Clock by index.
154  * @param op
155  * Symbolic value for operator
156  * @param timeconst
157  * Value for time constant
158  */
159  ElemConstraint(Idx clockindex, Operator op, tpTime::Type timeconst);
160 
161  /**
162  * Set all values
163  *
164  * @param clockindex
165  * Clock by index.
166  * @param op
167  * Symbolic value for operator
168  * @param timeconst
169  * Value for time constant
170  */
171  void Set(Idx clockindex, Operator op, tpTime::Type timeconst);
172 
173  /**
174  * Set clock by index
175  */
176  Idx Clock(Idx newClock);
177 
178  /**
179  * Get clock by index
180  *
181  * @return clock index
182  */
183  Idx Clock(void) const;
184 
185  /**
186  * Set operator.
187  *
188  * @param newOp
189  * Symbolic value of new operator
190  */
191  void CompOperator(Operator newOp);
192 
193  /**
194  * Get operator
195  * @return Operator
196  */
197  Operator CompOperator(void) const;
198 
199  /**
200  * Set time constant.
201  *
202  * @param newTimeConst
203  * Value of new time constant
204  */
205  void TimeConstant(tpTime::Type newTimeConst);
206 
207  /**
208  * Get time constant
209  * @return Time constant
210  */
211  tpTime::Type TimeConstant(void) const;
212 
213  /**
214  * Writes ElemConstraint to std::string
215  *
216  * @return std::string
217  */
218  std::string Str(void) const;
219 
220  /**
221  * Test for equality.
222  *
223  * @param otherElemConstraint
224  * Other elementary constraint
225  * @return
226  * True if mClockIndex, mTimeConstant and mCompOperator are equal. Else false.
227  */
228  bool operator== (const ElemConstraint & otherElemConstraint) const;
229 
230  /**
231  * Test for equality.
232  *
233  * @param otherElemConstraint
234  * Other elementary constraint
235  * @return
236  * True if not equal; see operator==.
237  */
238  bool operator!= (const ElemConstraint & otherElemConstraint) const;
239 
240  /**
241  * Less operator for ordering in container classes
242  *
243  * @param otherElemConstraint
244  * Other ElemConstraint
245  *
246  * @return True when clock index of left constraint is less
247  * than the one of right constraint. Else false.
248  */
249  bool operator < (const ElemConstraint& otherElemConstraint) const;
250 
251 
252  protected:
253 
254  /** Index of clock. */
256 
257  /** Comparative operator */
259 
260  /** Time constant to compare with clock value */
262 
263 }; // ElemConstraint
264 
265 
266 
267 /**
268  * A TimeConstraint is a set of elementary clock constraints. Semantically,
269  * the elementary constraints are combibed by conjunction, ie the TimeConstraint is
270  * satisfied if all ElemConstraint s are satisfied. This implementation also maintains
271  * the clock symboltable to may cloc indices to symbolic names.
272  *
273  * @param ClockConstraints
274  * Set of elementary clock constraints
275  *
276  * @ingroup TimedPlugin
277  */
278 
280 
281  public:
282 
283  /** Iterator to access ElemConstraints */
284  typedef std::set<ElemConstraint>::const_iterator Iterator;
285 
286  /** Reverse iterator to access ElemConstraints */
287  typedef std::set<ElemConstraint>::const_reverse_iterator RIterator;
288 
289  /** Convenience typedef for operators */
291 
292  /**
293  * Construct an empty TimeConstraint (allways satisfied)
294  */
295  TimeConstraint(void);
296 
297  /**
298  * Copy constructor
299  *
300  * @param rOtherTimeConstraint
301  * Time constraint to copy
302  */
303  TimeConstraint(const TimeConstraint& rOtherTimeConstraint);
304 
305  /**
306  * Constructor from file.
307  *
308  * Uses Read() to scan a file for specified label to read the constraint.
309  *
310  * @param rFilename
311  * File to read
312  * @param rLabel
313  * Section label for the set in the file.
314  */
315  TimeConstraint(const std::string& rFilename, const std::string& rLabel = "TimeConstraint");
316 
317  /**
318  * Destructor
319  */
320  ~TimeConstraint(void);
321 
322 
323  /**
324  * Get Pointer to mpClockSymbolTable.
325  *
326  * @return
327  * Pointer to mpClockSymbolTable
328  */
329  SymbolTable* ClockSymbolTablep(void) const;
330 
331 
332  /**
333  * Set Pointer to mpClockSymbolTable.
334  *
335  */
336  void ClockSymbolTablep(SymbolTable* pSymTab);
337 
338  /**
339  * Write to console
340  */
341  void Write(void) const;
342 
343  /**
344  * Write to file with label (default: "TimeConstraint") and
345  * openmode (default: truncate file).
346  *
347  * @param rFileName
348  * Filename
349  * @param rLabel
350  * Label for set in file
351  * @param openmode
352  * std::ios::openmode
353  *
354  * @exception Exception
355  * If opening/writing fails an Exception object is thrown (id 2)
356  */
357  void Write(const std::string& rFileName, const std::string& rLabel = "TimeConstraint",
358  std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
359 
360 
361  /**
362  * Write to TokenWriter. The name of the constraint is used
363  * as the label in the file.
364  *
365  * @param tw
366  * Reference to TokenWriter
367  *
368  * @exception std::ios::failure
369  * Thrown on i/o error.
370  */
371  void Write(TokenWriter& tw) const;
372 
373  /**
374  * Write to TokenWriter with a given label
375  *
376  * @param tw
377  * Reference to TokenWriter
378  * @param rLabel
379  * Label for set in file
380  *
381  * @exception std::ios::failure
382  * Thrown on i/o error.
383  */
384  void Write(TokenWriter& tw, const std::string& rLabel) const;
385 
386  /**
387  * Write to a std::string
388  *
389  * @return
390  * String containing all elements
391  */
392  std::string ToString(void) const;
393 
394  /**
395  * Write NameSet to console, debug version
396  */
397  void DWrite(void) const;
398 
399  /** Write to TokenWriter, debug version
400  *
401  * @param tw
402  * Reference to TokenWriter
403  *
404  * @exception std::ios::failure
405  * Thrown on i/o error.
406  */
407  void DWrite(TokenWriter& tw) const;
408 
409  /**
410  * Read from file. Reads specified label by creating a tokenreader and
411  * calling read(tr)
412  *
413  * @param rFileName
414  * Filename
415  * @param rLabel
416  * token label to read from file
417  *
418  * @exception Exception
419  * If opening/reading fails an Exception object is thrown (id 1, 50, 51, 56)
420  */
421  void Read(const std::string& rFileName, const std::string& rLabel = "TimeConstraint");
422 
423 
424  /**
425  * Read from tokenreader. Clears before. It is an error
426  * if the file contains an index
427  *
428  * @param tr
429  * Reference to tokenreader
430  * @param rLabel
431  * Label to read
432  *
433  * @exception std::ios::failure
434  * Thrown on i/o error.
435  */
436  void Read(TokenReader& tr, const std::string& rLabel = "TimeConstraint");
437 
438 
439  /**
440  * Return name of Constraint
441  *
442  * @return
443  * Name
444  */
445  std::string Name(void) const { return mName;};
446 
447  /**
448  * Set name of Constraint
449  *
450  * @param rName
451  * BaseSet name
452  */
453  void Name(const std::string& rName) { mName=rName; };
454 
455 
456  /**
457  * Checks if TimeConstraint containts no ElemConstraints
458  *
459  * @return
460  * True if TimeConstraint is empty. Else false.
461  */
462  bool Empty(void) const;
463 
464  /**
465  * Returns number of ElemConstraint s.
466  *
467  * @return Number of ElemConstraint s.
468  */
469  Idx Size(void) const;
470 
471  /**
472  * Adds an elementary clock constraint to the time constraint.
473  *
474  * @param rElemConstr
475  * Elementary clock constraint that is to be added to time constraint
476  * @return
477  * iterator to new constraint
478  */
479  Iterator Insert(const ElemConstraint& rElemConstr);
480 
481  /**
482  * Adds an elementary clock constraint to the time constraint.
483  *
484  * @param clockname
485  * Clock for new ElemConstraint
486  * @param op
487  * Operator for new ElemConstraint
488  * @param timeconst
489  * Time constant for new ElemConstraint
490  * @return
491  * iterator to new constraint
492  */
493  Iterator Insert(const std::string clockname, Operator op, const tpTime::Type timeconst);
494 
495  /**
496  * Adds an elementary clock constraint to the time constraint.
497  *
498  * @param clockindex
499  * Clock for new ElemConstraint
500  * @param op
501  * Operator for new ElemConstraint
502  * @param timeconst
503  * Time constant for new ElemConstraint
504  * @return
505  * iterator to new constraint
506  */
507  Iterator Insert(Idx clockindex, Operator op, const tpTime::Type timeconst);
508 
509  /**
510  * Adds a list of elementary clock constraints to the time constraint.
511  *
512  * @param rNewConstraints
513  * Set of elementary clock constraints that is to be added to time constraint.
514  */
515  void Insert(const std::list<ElemConstraint>& rNewConstraints);
516 
517  /**
518  * Adds elementary clock constraints from other TimeConstant to the time constraint.
519  *
520  * @param rOtherTimeConstraint
521  * Time constraint whos clock constraints are to be added to time constraint.
522  */
523  void Insert(const TimeConstraint& rOtherTimeConstraint);
524 
525  /**
526  * Convenience operator to combine a TimeConstraint with another TimeConstraint.
527  *
528  * @param rOtherTimeConstraint
529  * other TimeConstraint
530  *
531  * @return TimeConstraint object containing all ElemConstraints of both TimeConstraints.
532  */
533  TimeConstraint& operator << (const TimeConstraint& rOtherTimeConstraint) {
534  this->Insert(rOtherTimeConstraint); return *this; };
535 
536  /**
537  * Convenience operator to combines a TimeConstraint with an elementary TimeConstraint.
538  *
539  * @param rElemConstr
540  * extra elemtary constraint
541  *
542  * @return TimeConstraint object containing all ElemConstraints of both TimeConstraints.
543  */
545  this->Insert(rElemConstr); return *this; };
546 
547  /**
548  * Returns copy of ClockConstraints
549  */
550  std::set<ElemConstraint> ClockConstraints(void) const;
551 
552  /**
553  * Advertise clock to ClockSymbolTable and retrive index
554  *
555  * @param rClockName
556  * symbolic name of clock
557  *
558  * @return
559  * index of clock
560  */
561  Idx InsClock(const std::string& rClockName) const;
562 
563  /**
564  * Lookup clock name
565  *
566  * @param clockindex
567  * index of clock
568  *
569  * @return
570  * name of clock
571  */
572  std::string ClockName(Idx clockindex) const;
573 
574  /**
575  * Lookup clock index
576  *
577  * @param rClockName
578  * Symbolic name of clock
579  *
580  * @return
581  * Index of clock
582  */
583  Idx ClockIndex(const std::string& rClockName) const;
584 
585  /**
586  * Pretty printable string of elem. constraint
587  *
588  * @param rElemConstr
589  * ref to elem constraint
590  *
591  * @return
592  * output string
593  */
594  std::string EStr(const ElemConstraint& rElemConstr) const;
595 
596  /**
597  * Removes all elementary clock constraints refering to a specified clock.
598  *
599  * @param clock
600  * Clock whos constraints are to be removed.
601  * @return
602  * True, if constraints(s) have been erased
603  */
604  bool EraseByClock(Idx clock);
605 
606  /**
607  * Calls std::set::erase(iterator). ElemConstraint refered by it is removed from constraint.
608  *
609  * @param it
610  * TimeConstraint::Iterator pointing to ElemConstraint that is removed.
611  *
612  * @return
613  * Iterator pointing to next ElemConstraint.
614  */
615  Iterator Erase(Iterator it);
616 
617  /**
618  * Removes elementary clock constraint.
619  *
620  * @param rElemConstr
621  * Constraint to be removed.
622  * @return
623  * True, if constraint has been removed
624  */
625  bool Erase(const ElemConstraint& rElemConstr);
626 
627  /**
628  * Removes elementary clock constraint.
629  *
630  * @param rClockName
631  * Clock
632  * @param op
633  * Operator
634  * @param timeconst
635  * Time constant
636  * @return
637  * True, if constraint has been removed
638  */
639  bool Erase(const std::string& rClockName, Operator op, const tpTime::Type timeconst);
640 
641  /**
642  * Removes elementary clock constraint.
643  *
644  * @param clockindex
645  * Clock
646  * @param op
647  * Operator
648  * @param timeconst
649  * Time constant
650  * @return
651  * True, if constraint has been removed
652  */
653  bool Erase(Idx clockindex, Operator op, const tpTime::Type timeconst);
654 
655  /**
656  * Clear all
657  */
658  void Clear(void);
659 
660 
661  /**
662  * Checks if elementary clock constraint is contained in constraint
663  *
664  * @param rElemConstr
665  * elementary constraint
666  */
667  bool Exists(const ElemConstraint& rElemConstr) const;
668 
669  /**
670  * Iterator to begin of set
671  *
672  * @return
673  * TimeConstraint::Iterator
674  */
675  Iterator Begin(void) const;
676 
677  /**
678  * Iterator to end of set
679  *
680  * @return
681  * TimeConstraint::Iterator
682  */
683  Iterator End(void) const;
684 
685  /**
686  * Reverse iterator that yields the ElemConstraints in reverse order starting at
687  * the last element and ending after the first. See set<...>::rbegin(void).
688  * Returns the "End".
689  *
690  * @return
691  * TimeConstraint::RIterator
692  */
693  RIterator RBegin(void) const;
694 
695  /**
696  * Reverse iterator that yields the ElemConstraints in reverse order starting at
697  * the last element and ending after the first. See set<...>::rend(void).
698  * Returns the "Begin".
699  *
700  * @return
701  * TimeConstraint::RIterator
702  */
703  RIterator REnd(void) const;
704 
705  /**
706  * Iterator to first constraint with specified clock
707  *
708  * @return
709  * TimeConstraint::iterator
710  */
711  Iterator Begin(Idx clock) const;
712 
713  /**
714  * Iterator to first constraint just behind specified clock
715  *
716  * @return
717  * TimeConstraint::Iterator
718  */
719  Iterator End(Idx clock) const;
720 
721  /**
722  * Returns a Clockset containing all clocks used
723  * by the TimeConstraint.
724  *
725  * @return Clockset containing all clocks used by the TimeConstraint.
726  */
727  ClockSet ActiveClocks(void) const;
728 
729  /**
730  * Given a clock, compute the timeinterval in which
731  * the constraint is satisfied
732  *
733  * @return TimeInterval
734  */
735  TimeInterval Interval(Idx clockindex) const;
736 
737  /**
738  * Given a clock, compute the timeinterval in which
739  * the constraint is satisfied
740  *
741  * @return TimeInterval
742  */
743  TimeInterval Interval(const std::string& clockname) const;
744 
745  /**
746  * Given a clock and an interval, set up the constraint such
747  * that it is valid in the given interval.
748  *
749  * @param clockindex
750  * specifies the clock
751  * @param rInterval
752  * reference to time interval
753  */
754  void Interval(Idx clockindex, const TimeInterval& rInterval);
755 
756 
757  /**
758  * Given a clock and an interval, set up the constraint such
759  * that it is valid in the given interval.
760  *
761  * @param rClockName
762  * specifies the clock
763  * @param rInterval
764  * reference to time interval
765  */
766  void Interval(const std::string& rClockName, const TimeInterval& rInterval);
767 
768  /**
769  * Minimize by eliminating redundant elementary constraints. The current implemantation
770  * retrieves the time constraints as intervals per clock and then converts back to
771  * a time constraint.
772  */
773  void Minimize(void);
774 
775 
776  /**
777  * Test for equality.
778  * The implementation converts both constraints to intervals and then
779  * performs the comparison.
780  *
781  * @param rOther
782  * Constraint to compare with.
783  * @return
784  * True if constraints are semantically identical.
785  */
786  bool operator== (const TimeConstraint& rOther) const;
787 
788  /**
789  * Test for equality.
790  *
791  * @param rOther
792  * Constraint to compare with.
793  * @return
794  * True if not equal; see operator==.
795  */
796  bool operator!= (const TimeConstraint & rOther) const;
797 
798  protected:
799 
800  /** My name */
801  std::string mName;
802 
803  /** Set of elementary clock constraints */
804  std::set<ElemConstraint> mClockConstraints;
805 
806  /** SymbolTable for clock names */
808 
809  /** nonconst iterator to access ElemConstraints */
810  typedef std::set<ElemConstraint>::iterator iterator;
811 
812 }; //TimeConstraint
813 
814 
815 } // namespace faudes
816 
817 
818 #endif
819 

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen