tp_timeconstraint.h

Go to the documentation of this file.
00001 /** @file tp_timeconstraint.h  Classes ClockSet, ElemConstraint and TimeConstraint */
00002 
00003 
00004 
00005 /* Timeplugin for FAU Discrete Event Systems Library (libfaudes)
00006 
00007    Copyright (C) 2006  B Schlein
00008    Copyright (C) 2007  Thomas Moor
00009    Exclusive copyright is granted to Klaus Schmidt
00010 
00011 */
00012 
00013 #ifndef FAUDES_TP_TIMECONSTRAINT_H
00014 #define FAUDES_TP_TIMECONSTRAINT_H
00015 
00016 #include "corefaudes.h"
00017 #include "tp_timeinterval.h"
00018 #include <list>
00019 
00020 
00021 namespace faudes {
00022 
00023 
00024 
00025 /**
00026  * Container class to model a set of clocks. 
00027  * Technically, this is a NameSet with a static SymbolTable to map
00028  * symbolic clock names to clock indices. Thus, clock names are
00029  * global similar to event names. Note that clocksets of individual
00030  * TtGenerators are assumed to be disjoint. 
00031  *
00032  * Todo: explicitely inherit other constructors (!)
00033  *
00034  * @ingroup TimedPlugin 
00035  *
00036  */
00037 
00038 class ClockSet : public NameSet {
00039 
00040 FAUDES_TYPE_DECLARATION(ClockSet,ClockSet,NameSet)
00041 
00042   public:
00043 
00044   /**
00045    * Constructor 
00046    */
00047   ClockSet(void);
00048 
00049   /**
00050    * Copy-constructor.
00051    *
00052    * @param rOtherSet
00053    *   Set to copy
00054    */
00055   ClockSet(const ClockSet& rOtherSet);
00056 
00057     /**
00058      * Construct from file.
00059      * Uses the NameSet's Read() function to scan a file for a 
00060      * specified clockset.
00061      *
00062      * @param rFilename
00063      *   File to read
00064      * @param rLabel
00065      *   Section label for the clocks in the file; default value "Clocks"
00066      */
00067    ClockSet(const std::string& rFilename, const std::string& rLabel = "Clocks");
00068  
00069     /**
00070      * Get pointer to static clock SymbolTable
00071      *
00072      * @return
00073      *   Pointer to static clock SymbolTable
00074      */
00075     static SymbolTable* StaticSymbolTablep(void);
00076 
00077   protected:
00078 
00079   /** Static global SymbolTable for clock names */
00080   static SymbolTable msSymbolTable;
00081 
00082   /**
00083    * Assign from other clock set.
00084    *
00085    * @param rSourceSet
00086    *   Destination to copy from
00087    * @return
00088    *   ref to this set
00089    */
00090   virtual void DoAssign(const ClockSet& rSourceSet);
00091 
00092   /**
00093    * Test equality with other clock set.
00094    *
00095    * @param rOtherSet
00096    *   Set to compare with
00097    * @return
00098    *   True/false
00099    */
00100   virtual bool DoEqual(const ClockSet& rOtherSet) const;
00101 
00102 }; // end class ClockSet
00103 
00104 
00105 
00106 /**
00107  * Model of an elementary clock constraint formula.  The constraint consists of an index
00108  * of a clock, a comperative operator and a constant time value.
00109  * Semantically, an elementary contraint is satisfied at a time t if at that time
00110  * the clock value compares true with the constant time.
00111  * The clock index 0 is used to indicate an invalid contraint. It is only the 
00112  * context of the more general TimeContraint that provides
00113  * a reference to a clock SymbolTable.   
00114  * 
00115  * @param mClock
00116  *    Clock index
00117  *
00118  * @param mCompOperator
00119  *    Symbolic integer value for comperative operator
00120  *
00121  * @param mTimeConstant
00122  *    Time constant for comparison
00123  *
00124  * @ingroup TimedPlugin 
00125  *
00126  */
00127 
00128 class ElemConstraint {
00129 
00130   public:
00131 
00132     /**
00133      *  Typedef for comparison operators in elementary clock constraints
00134      * 
00135      */
00136     typedef enum {GreaterEqual, GreaterThan, LessThan, LessEqual} Operator;
00137 
00138     /**
00139      *  Conversion from symbolic operator to string
00140      */
00141     static std::string OperatorName(Operator op);
00142 
00143     /**
00144      * Construct an (invalid) elementary clock constraint (clockindex 0)
00145      * 
00146      */
00147     ElemConstraint(void);
00148 
00149     /**
00150      * Construct an elementary clock constraint from values 
00151      *
00152      * @param clockindex
00153      *    Clock by index.
00154      * @param op
00155      *    Symbolic value for operator
00156      * @param timeconst
00157      *    Value for time constant
00158      */
00159     ElemConstraint(Idx clockindex, Operator op, tpTime::Type timeconst);
00160 
00161     /**
00162      * Set all values
00163      *
00164      * @param clockindex
00165      *    Clock by index.
00166      * @param op
00167      *    Symbolic value for operator
00168      * @param timeconst
00169      *    Value for time constant
00170      */
00171     void Set(Idx clockindex, Operator op, tpTime::Type timeconst);
00172 
00173     /**
00174      * Set clock by index
00175      */
00176     Idx Clock(Idx newClock);
00177 
00178     /**
00179      * Get clock by index
00180      *
00181      * @return clock index
00182      */
00183     Idx Clock(void) const;
00184 
00185     /**
00186      * Set operator.
00187      *
00188      * @param newOp
00189      *    Symbolic value of new operator
00190      */
00191     void CompOperator(Operator newOp);
00192 
00193     /**
00194      * Get operator
00195      * @return Operator
00196      */
00197     Operator CompOperator(void) const;
00198 
00199     /**
00200      * Set time constant.
00201      *
00202      * @param newTimeConst
00203      *    Value of new time constant
00204      */
00205     void TimeConstant(tpTime::Type newTimeConst);
00206 
00207     /**
00208      * Get time constant
00209      * @return Time constant
00210      */
00211     tpTime::Type TimeConstant(void) const;
00212 
00213     /**
00214      * Writes ElemConstraint to std::string
00215      *
00216      * @return std::string
00217      */
00218     std::string Str(void) const;
00219 
00220     /**
00221      * Test for equality.
00222      *
00223      * @param otherElemConstraint
00224      *    Other elementary constraint
00225      * @return 
00226      *  True if mClockIndex, mTimeConstant and mCompOperator are equal. Else false.
00227      */
00228     bool operator== (const ElemConstraint & otherElemConstraint) const;
00229 
00230     /**
00231      * Test for equality.
00232      *
00233      * @param otherElemConstraint
00234      *    Other elementary constraint
00235      * @return 
00236      *  True if not equal; see operator==.
00237      */
00238     bool operator!= (const ElemConstraint & otherElemConstraint) const;
00239 
00240     /**
00241      * Less operator for ordering in container classes
00242      *
00243      * @param otherElemConstraint
00244      *   Other ElemConstraint
00245      *
00246      * @return True  when clock index of left constraint is less
00247      *   than the one of right constraint. Else false.
00248      */
00249     bool operator < (const ElemConstraint& otherElemConstraint) const;
00250 
00251 
00252   protected:
00253 
00254     /** Index of clock. */
00255     Idx mClockIndex;
00256 
00257     /** Comparative operator */
00258     Operator mCompOperator;
00259 
00260     /** Time constant to compare with clock value */
00261     tpTime::Type mTimeConstant;
00262 
00263 }; // ElemConstraint
00264 
00265 
00266 
00267 /**
00268  * A TimeConstraint is a set of elementary clock constraints. Semantically,
00269  * the elementary constraints are combibed by conjunction, ie the TimeConstraint is
00270  * satisfied if all ElemConstraint s are satisfied. This implementation also maintains
00271  * the clock symboltable to may cloc indices to symbolic names.
00272  *
00273  * @param ClockConstraints
00274  *    Set of elementary clock constraints
00275  *
00276  *  @ingroup TimedPlugin 
00277  */
00278 
00279 class TimeConstraint {
00280 
00281   public:
00282 
00283     /** Iterator to access ElemConstraints */
00284     typedef std::set<ElemConstraint>::const_iterator Iterator;
00285 
00286     /** Reverse iterator to access ElemConstraints */
00287     typedef std::set<ElemConstraint>::const_reverse_iterator RIterator;
00288 
00289     /** Convenience typedef for operators */
00290     typedef ElemConstraint::Operator Operator;
00291 
00292     /**
00293      * Construct an empty TimeConstraint (allways satisfied)
00294      */
00295     TimeConstraint(void);
00296 
00297     /**
00298      * Copy constructor
00299      *
00300      * @param rOtherTimeConstraint
00301      *    Time constraint to copy
00302      */
00303     TimeConstraint(const TimeConstraint& rOtherTimeConstraint);
00304 
00305     /**
00306      * Constructor from file.
00307      *
00308      * Uses Read() to scan a file for specified label to read the constraint. 
00309      *
00310      * @param rFilename
00311      *   File to read
00312      * @param rLabel
00313      *   Section label for the set in the file. 
00314      */
00315     TimeConstraint(const std::string& rFilename, const std::string& rLabel = "TimeConstraint");
00316 
00317     /**
00318      * Destructor
00319      */
00320     ~TimeConstraint(void);
00321 
00322 
00323     /**
00324      * Get Pointer to mpClockSymbolTable.
00325      *
00326      * @return
00327      *   Pointer to mpClockSymbolTable
00328      */
00329     SymbolTable* ClockSymbolTablep(void) const;
00330 
00331 
00332     /**
00333      * Set Pointer to mpClockSymbolTable.
00334      *
00335      */
00336     void ClockSymbolTablep(SymbolTable* pSymTab);
00337 
00338     /**
00339      * Write to console
00340      */
00341     void Write(void) const;
00342 
00343     /**
00344      * Write to file with label (default: "TimeConstraint") and 
00345      * openmode (default: truncate file).
00346      *
00347      * @param rFileName
00348      *   Filename
00349      * @param rLabel
00350      *   Label for set in file
00351      * @param openmode
00352      *   std::ios::openmode
00353      *
00354      * @exception Exception
00355      *   If opening/writing fails an Exception object is thrown (id 2)
00356      */
00357     void Write(const std::string& rFileName, const std::string& rLabel = "TimeConstraint",
00358          std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
00359 
00360 
00361     /**
00362      * Write to TokenWriter. The name of the constraint is used
00363      * as the label in the file.
00364      *
00365      * @param tw
00366      *   Reference to TokenWriter
00367      *
00368      * @exception std::ios::failure     
00369      *   Thrown on i/o error.
00370      */
00371     void Write(TokenWriter& tw) const;
00372         
00373     /**
00374      * Write to TokenWriter with a given label
00375      *
00376      * @param tw
00377      *   Reference to TokenWriter
00378      * @param rLabel
00379      *   Label for set in file
00380      *
00381      * @exception std::ios::failure
00382      *   Thrown on i/o error.
00383      */
00384     void Write(TokenWriter& tw, const std::string& rLabel) const;
00385         
00386     /**
00387      * Write to a std::string
00388      *
00389      * @return
00390      *   String containing all elements
00391      */
00392     std::string ToString(void) const;
00393 
00394     /**
00395      * Write NameSet to console, debug version
00396      */
00397     void DWrite(void) const;
00398 
00399     /** Write to TokenWriter, debug version
00400      *
00401      * @param tw
00402      *   Reference to TokenWriter
00403      *
00404      * @exception std::ios::failure
00405      *   Thrown on i/o error.
00406      */
00407     void DWrite(TokenWriter& tw) const;
00408 
00409     /**
00410      * Read from file. Reads specified label by creating a tokenreader and
00411      * calling read(tr)
00412      *
00413      * @param rFileName
00414      *   Filename
00415      * @param rLabel
00416      *   token label to read from file
00417      *
00418      * @exception Exception
00419      *   If opening/reading fails an Exception object is thrown (id 1, 50, 51, 56)
00420      */
00421     void Read(const std::string& rFileName, const std::string& rLabel = "TimeConstraint");
00422     
00423     
00424     /**
00425      * Read from tokenreader. Clears before. It is an error
00426      * if the file contains an index
00427      *
00428      * @param tr
00429      *   Reference to tokenreader
00430      * @param rLabel
00431      *   Label to read
00432      *
00433      * @exception std::ios::failure
00434      *   Thrown on i/o error.
00435      */
00436     void Read(TokenReader& tr, const std::string& rLabel = "TimeConstraint");
00437 
00438 
00439     /** 
00440      * Return name of Constraint 
00441      * 
00442      * @return
00443      *   Name 
00444      */
00445     std::string Name(void) const { return mName;};
00446         
00447     /**
00448      * Set name of Constraint
00449      *
00450      * @param rName
00451      *   BaseSet name
00452      */
00453     void Name(const std::string& rName) { mName=rName; };
00454 
00455 
00456     /**
00457      * Checks if TimeConstraint containts no ElemConstraints
00458      * 
00459      * @return
00460      *     True if TimeConstraint is empty. Else false.
00461      */
00462     bool Empty(void) const;
00463 
00464     /**
00465      * Returns number of ElemConstraint s.
00466      *
00467      * @return Number of ElemConstraint s.
00468      */
00469     Idx Size(void) const;
00470 
00471     /**
00472      * Adds an elementary clock constraint to the time constraint.
00473      *
00474      * @param rElemConstr
00475      *    Elementary clock constraint that is to be added to time constraint
00476      * @return
00477      *   iterator to new constraint
00478      */
00479     Iterator Insert(const ElemConstraint& rElemConstr);
00480 
00481     /**
00482      * Adds an elementary clock constraint to the time constraint.
00483      *
00484      * @param clockname
00485      *    Clock for new ElemConstraint
00486      * @param op
00487      *    Operator for new ElemConstraint
00488      * @param timeconst
00489      *    Time constant for new ElemConstraint
00490      * @return
00491      *   iterator to new constraint
00492      */
00493     Iterator Insert(const std::string clockname, Operator op, const tpTime::Type timeconst);
00494 
00495     /**
00496      * Adds an elementary clock constraint to the time constraint.
00497      *
00498      * @param clockindex
00499      *    Clock for new ElemConstraint
00500      * @param op
00501      *    Operator for new ElemConstraint
00502      * @param timeconst
00503      *    Time constant for new ElemConstraint
00504      * @return
00505      *   iterator to new constraint
00506      */
00507     Iterator Insert(Idx clockindex, Operator op, const tpTime::Type timeconst);
00508 
00509     /**
00510      * Adds a list of elementary clock constraints to the time constraint.
00511      *
00512      * @param rNewConstraints
00513      *    Set of elementary clock constraints that is to be added to time constraint.
00514      */
00515     void Insert(const std::list<ElemConstraint>& rNewConstraints);
00516 
00517     /**
00518      * Adds elementary clock constraints from other TimeConstant to the time constraint.
00519      *
00520      * @param rOtherTimeConstraint
00521      *    Time constraint whos clock constraints are to be added to time constraint.
00522      */
00523     void Insert(const TimeConstraint& rOtherTimeConstraint);
00524 
00525     /**
00526      * Convenience operator to combine a TimeConstraint with another TimeConstraint.
00527      *
00528      * @param rOtherTimeConstraint
00529      *   other TimeConstraint
00530      *
00531      * @return TimeConstraint object containing all ElemConstraints of both TimeConstraints.
00532      */
00533     TimeConstraint& operator << (const TimeConstraint& rOtherTimeConstraint) {
00534       this->Insert(rOtherTimeConstraint); return *this; };
00535 
00536     /**
00537      * Convenience operator to combines a TimeConstraint with an elementary TimeConstraint.
00538      *
00539      * @param rElemConstr
00540      *   extra elemtary constraint
00541      *
00542      * @return TimeConstraint object containing all ElemConstraints of both TimeConstraints.
00543      */
00544     TimeConstraint& operator << (const ElemConstraint& rElemConstr) {
00545       this->Insert(rElemConstr); return *this; };
00546 
00547     /**
00548      * Returns copy of ClockConstraints
00549      */
00550     std::set<ElemConstraint> ClockConstraints(void) const;
00551 
00552     /**
00553      * Advertise clock to ClockSymbolTable and retrive index
00554      *
00555      * @param rClockName
00556      *   symbolic name of clock
00557      *
00558      * @return
00559      *   index of clock
00560      */
00561     Idx InsClock(const std::string& rClockName) const;
00562 
00563     /**
00564      * Lookup clock name 
00565      *
00566      * @param clockindex
00567      *   index of clock
00568      *
00569      * @return
00570      *   name of clock
00571      */
00572     std::string ClockName(Idx clockindex) const;
00573 
00574     /**
00575      * Lookup clock index 
00576      *
00577      * @param rClockName
00578      *   Symbolic name of clock
00579      *
00580      * @return
00581      *   Index of clock
00582      */
00583     Idx ClockIndex(const std::string& rClockName) const;
00584 
00585     /**
00586      * Pretty printable string of elem. constraint
00587      *
00588      * @param rElemConstr
00589      *   ref to elem constraint
00590      *
00591      * @return
00592      *   output string
00593      */
00594     std::string EStr(const ElemConstraint& rElemConstr) const;
00595 
00596     /**
00597      * Removes all elementary clock constraints refering to a specified clock.
00598      *
00599      * @param clock 
00600      *   Clock whos constraints are to be removed.
00601      * @return
00602      *   True, if constraints(s) have been erased
00603      */
00604     bool EraseByClock(Idx clock);
00605 
00606     /**
00607      * Calls std::set::erase(iterator). ElemConstraint refered by it is removed from constraint.
00608      *
00609      * @param it
00610      *    TimeConstraint::Iterator pointing to ElemConstraint that is removed.
00611      *
00612      * @return 
00613      *   Iterator pointing to next ElemConstraint.
00614      */
00615     Iterator Erase(Iterator it);
00616 
00617     /**
00618      * Removes elementary clock constraint.
00619      *
00620      * @param rElemConstr
00621      *   Constraint to be removed.
00622      * @return
00623      *   True, if constraint has been removed
00624      */
00625     bool Erase(const ElemConstraint& rElemConstr);
00626 
00627     /**
00628      * Removes elementary clock constraint.
00629      *
00630      * @param rClockName
00631      *    Clock 
00632      * @param op
00633      *    Operator 
00634      * @param timeconst
00635      *    Time constant 
00636      * @return
00637      *   True, if constraint has been removed
00638      */
00639     bool Erase(const std::string& rClockName, Operator op, const tpTime::Type timeconst);
00640 
00641     /**
00642      * Removes elementary clock constraint.
00643      *
00644      * @param clockindex
00645      *    Clock 
00646      * @param op
00647      *    Operator 
00648      * @param timeconst
00649      *    Time constant 
00650      * @return
00651      *   True, if constraint has been removed
00652      */
00653     bool Erase(Idx clockindex, Operator op, const tpTime::Type timeconst);
00654 
00655     /**
00656      * Clear all
00657      */
00658     void Clear(void);
00659 
00660 
00661     /**
00662      * Checks if elementary clock constraint is contained in constraint
00663      *
00664      * @param rElemConstr
00665      *    elementary constraint
00666      */
00667     bool Exists(const ElemConstraint& rElemConstr) const;
00668 
00669     /** 
00670      * Iterator to begin of set 
00671      *
00672      * @return
00673      *   TimeConstraint::Iterator
00674      */
00675     Iterator Begin(void) const;
00676     
00677     /** 
00678      * Iterator to end of set
00679      *
00680      * @return
00681      *   TimeConstraint::Iterator
00682      */
00683     Iterator End(void) const;  
00684     
00685     /**
00686      * Reverse iterator that yields the ElemConstraints in reverse order starting at
00687      * the last element and ending after the first. See set<...>::rbegin(void).
00688      * Returns the "End". 
00689      *
00690      * @return
00691      *   TimeConstraint::RIterator
00692      */
00693     RIterator RBegin(void) const;
00694     
00695     /**
00696      * Reverse iterator that yields the ElemConstraints in reverse order starting at
00697      * the last element and ending after the first. See set<...>::rend(void).
00698      * Returns the "Begin".
00699      *
00700      * @return
00701      *   TimeConstraint::RIterator
00702      */
00703     RIterator REnd(void) const;
00704 
00705     /** 
00706      * Iterator to first constraint with specified clock 
00707      *
00708      * @return
00709      *   TimeConstraint::iterator
00710      */
00711     Iterator Begin(Idx clock) const;
00712     
00713     /** 
00714      * Iterator to first constraint just behind specified clock 
00715      *
00716      * @return
00717      *   TimeConstraint::Iterator
00718      */
00719     Iterator End(Idx clock) const;
00720 
00721     /**
00722      * Returns a Clockset containing all clocks used 
00723      * by the TimeConstraint.
00724      *
00725      * @return Clockset containing all clocks used by the TimeConstraint.
00726      */
00727     ClockSet ActiveClocks(void) const;
00728 
00729     /**
00730      * Given a clock, compute the timeinterval in which
00731      * the constraint is satisfied
00732      *
00733      * @return TimeInterval
00734      */
00735     TimeInterval Interval(Idx clockindex) const;
00736 
00737     /**
00738      * Given a clock, compute the timeinterval in which
00739      * the constraint is satisfied
00740      *
00741      * @return TimeInterval
00742      */
00743     TimeInterval Interval(const std::string& clockname) const;
00744 
00745     /**
00746      * Given a clock and an interval, set up the constraint such 
00747      * that it is valid in the given interval.  
00748      *
00749      * @param clockindex
00750      *    specifies the clock
00751      * @param rInterval
00752      *    reference to time interval
00753      */
00754     void Interval(Idx clockindex, const TimeInterval& rInterval);
00755 
00756 
00757     /**
00758      * Given a clock and an interval, set up the constraint such 
00759      * that it is valid in the given interval.  
00760      *
00761      * @param rClockName
00762      *    specifies the clock
00763      * @param rInterval
00764      *    reference to time interval
00765      */
00766     void Interval(const std::string& rClockName, const TimeInterval& rInterval);
00767 
00768     /**
00769      * Minimize by eliminating redundant elementary constraints. The current implemantation
00770      * retrieves the time constraints as intervals per clock and then converts back to 
00771      * a time constraint.
00772      */
00773     void Minimize(void);
00774 
00775 
00776     /**
00777      * Test for equality.
00778      * The implementation converts both constraints to intervals and then
00779      * performs the comparison.
00780      *
00781      * @param rOther
00782      *    Constraint to compare with.
00783      * @return 
00784      *  True if constraints are semantically identical.
00785      */
00786     bool operator== (const TimeConstraint& rOther) const;
00787 
00788     /**
00789      * Test for equality.
00790      *
00791      * @param rOther
00792      *    Constraint to compare with.
00793      * @return 
00794      *  True if not equal; see operator==.
00795      */
00796     bool operator!= (const TimeConstraint & rOther) const;
00797 
00798   protected:
00799 
00800     /** My name */
00801     std::string mName;
00802 
00803     /** Set of elementary clock constraints */
00804     std::set<ElemConstraint> mClockConstraints;
00805 
00806     /** SymbolTable for clock names */
00807     SymbolTable* mpClockSymbolTable;
00808 
00809     /** nonconst iterator to access ElemConstraints */
00810     typedef std::set<ElemConstraint>::iterator iterator;
00811 
00812 }; //TimeConstraint
00813 
00814 
00815 } // namespace faudes
00816 
00817 
00818 #endif 
00819 

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