libFAUDES

Sections

Index

cfl_functions.h

Go to the documentation of this file.
00001 /** @file cfl_functions.h Runtime interface, operations on faudes types */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2009 Ruediger Berndt
00006 Copyright (C) 2010 Thomas Moor
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00021 
00022 
00023 #ifndef FAUDES_RTIFNCTS_H
00024 #define FAUDES_RTIFNCTS_H
00025 
00026 // todo: fix/hide copy constructor
00027 
00028 #include "cfl_types.h"
00029 
00030 namespace faudes{
00031 
00032 /**
00033  * Structure to model a parameter type within the Signature of a 
00034  * Function.
00035  * A Parameter is made of a descriptive name, a faudes type and
00036  * an io-attribute. The latter specifies whether the parameter 
00037  * is a const argument (<tt>In</tt>), a result (<tt>Out</tt>) or a both-ways 
00038  * parameter (<tt>InOut</tt>). To support the code generators of the run-time-interface,
00039  * you may use the CReturn  flag to indicate that the parameter is implemented 
00040  * as the return value in the corresponding C function. The current version of the
00041  * code generators will handle this case for the elementary types Integer, Boolean and
00042  * String. They will, however, fail on any other faudes types. 
00043  */
00044 
00045 class Parameter {
00046 
00047  public:
00048 
00049   /**
00050    * A function parameter has has one out of four so called io-attrributes;
00051    */
00052   enum ParamAttr{
00053     In,    //// Input parameter, aka argument, remains constant while execution
00054     Out,   //// Output parameter, aka result, is generated during function execution
00055     InOut, //// InOut parameter, is interpreted and possibly altered during execution
00056     UnDef  //// UnDef parameter indicates unconfigured signature
00057   };
00058 
00059   /** Constructor, default */
00060   Parameter(void);
00061 
00062   /** Constructor, by member values */
00063   Parameter(const std::string& rName, const std::string& rTypeName, 
00064       ParamAttr attr=UnDef, bool cret=false);
00065 
00066   /** Desctructor */
00067   ~Parameter(void);
00068 
00069   /** 
00070    * Get name
00071    *
00072    * @return
00073    *   Name of parameter
00074    */
00075   const std::string& Name(void) const;
00076 
00077   /** 
00078    * Set name
00079    *
00080    * @param rName
00081    *   New name of parameter
00082    */
00083   void Name(const std::string& rName);
00084 
00085   /** 
00086    * Get type
00087    *
00088    * @return
00089    *   Faudes type  of parameter
00090    */
00091   const std::string& Type(void) const;
00092 
00093   /** 
00094    * Set type
00095    *
00096    * @param rTypeName
00097    *   New faudes type  of parameter
00098    */
00099   void Type(const std::string& rTypeName);
00100 
00101   /** 
00102    * Get Attribute
00103    *
00104    * @return
00105    *   In/Out/InOut attribute of parameter.
00106    */
00107   const ParamAttr& Attribute(void) const;
00108 
00109   /** 
00110    * Set Attribute
00111    *
00112    * @param rAttr
00113    *   In/Out/InOut attribute of parameter.
00114    */
00115   void Attribute(const ParamAttr& rAttr);
00116 
00117   /** 
00118    * Set Attribute by string.
00119    * Convenience method, defaults to UnDef.
00120    *
00121    * @param rAttrStr
00122    *   In/Out/InOut attribute of parameter.
00123    */
00124   void Attribute(const std::string& rAttrStr);
00125 
00126   /** 
00127    * Get C-Return flag.
00128    *
00129    * @return
00130    *   C-Return flag
00131    */
00132   bool CReturn(void) const;
00133 
00134   /** 
00135    * Set C-Return flag.
00136    *
00137    * @param cret
00138    *   New value of C-Return flag.
00139    */
00140   void CReturn(bool cret);
00141 
00142   /**
00143    * Convenience method to produce a textual representation of an io attribute.
00144    *
00145    * @param attr
00146    *  Enum value denoting the attribute.
00147    * @return
00148    *  Parameter IO attribute as std::string
00149    */
00150   static std::string AStr(Parameter::ParamAttr attr);
00151 
00152   /**
00153    * Convenience method to produce a textual representation of a parameter.
00154    *
00155    */
00156   std::string Str(void) const;
00157 
00158   /**
00159    * Set to "undefined"
00160    */
00161   void Clear();
00162 
00163   /**
00164    * Test equality
00165    *
00166    * @param rOther
00167    *   Other signature to compare with.
00168    */  
00169   bool operator==(const Parameter& rOther) const;
00170 
00171 protected:
00172 
00173   /** Name */
00174   std::string mName;
00175 
00176   /** Faudes type */
00177   std::string mTDName;
00178 
00179   /** IO-Attribute */
00180   ParamAttr mAttr;
00181 
00182   /** C-Return flag */
00183   bool mCReturn;
00184 
00185 }; // Parameter
00186 
00187 
00188 
00189 
00190 /**
00191  * Signature of a Function.
00192  * 
00193  * A Signature describes the faudes types of the positional
00194  * parameters. Tecnically, a Signature is a vector of Parameters.
00195  * Each Function may execute serveral variants indicated by setting
00196  * a particular Signature. A list of valid Signatures is maintained in 
00197  * the coresponding FunctionDefinition.
00198  *
00199  * Core members are
00200  * - mName: string to identify ths signature
00201  * - mParameters: vector of Paramters. 
00202  *
00203  * The Signature is formally derived from Type to inherit the std token io
00204  * interface. It is not meant to be registered as a faudes type.
00205  * The token io format is demonstrated by the following example:
00206  *
00207  * @code
00208  *  <Signature>
00209  *  "Sum of two integers"
00210  *  <Parameters>
00211  *    "arg1"        "Integer"     +InOut+
00212  *    "arg2"        "Integer"     +In+
00213  *    "result"      "String"      +Out+ +CReturn+
00214  *  </Parameters>
00215  *  </Signature>
00216  * @endcode
00217  *
00218  * Technical note: the variable parameter feature offered by FunctionDefinition is a purely
00219  * cosmetic hack implemented in FunctionDefinition:MergeDocumentation. It is superseeded
00220  * by vector parameters and will hence disappear in a future implementation.
00221  */
00222 
00223 class Signature : public Type {
00224 
00225   // std faudes type interface (cannot autoregister)
00226   FAUDES_TYPE_DECLARATION_NEW(Void,Signature,Type)
00227   FAUDES_TYPE_DECLARATION_COPY(Void,Signature,Type)
00228   FAUDES_TYPE_DECLARATION_CAST(Void,Signature,Type)
00229   FAUDES_TYPE_DECLARATION_ASSIGN(Void,Signature,Type)
00230   FAUDES_TYPE_DECLARATION_EQUAL(Void,Signature,Type)
00231 
00232 public:
00233 
00234   /** Constructor */
00235   Signature(void);
00236 
00237   /** Copy constructor */
00238   Signature(const Signature& rSrc);
00239 
00240   /** Destructor */
00241   ~Signature(void){};
00242 
00243   /**
00244    * Return signature name.
00245    *
00246    * @return
00247    *  Name
00248    */
00249   const std::string& Name(void) const;
00250 
00251   /**
00252    * Set signature name.
00253    *
00254    * @param
00255    *  rName
00256    */
00257   void Name(const std::string& rName);
00258 
00259   /**
00260    * Clear signature
00261    */
00262   void Clear(void);
00263 
00264   /**
00265    * Return number of parameters.
00266    *
00267    * @return
00268    *  int
00269    */
00270   int Size(void) const;
00271 
00272   /**
00273    * Get parameter type by position.
00274    *
00275    * @param n
00276    *  Position of patameter.
00277    *
00278    * @exception Exception
00279    *  - Index out of range
00280    */
00281   const Parameter& At(int n) const;
00282 
00283   /**
00284    * Set parameter type by position.
00285    *
00286    * @param n
00287    *  Position of patameter.
00288    * @param rParam
00289    *  Paraeter value
00290    *
00291    * @exception Exception
00292    *  - Index out of range
00293    */
00294   void At(int n,const Parameter& rParam);
00295 
00296   /**
00297    * Append positional parameter.
00298    *
00299    * @param rParam
00300    *  Parameter to append
00301    */
00302   void Append(const Parameter& rParam);
00303 
00304 
00305  protected:
00306 
00307   /**
00308    * Std faudes type interface: assignment.
00309    *
00310    * @param rSrc 
00311    *    Source to copy from
00312    * @return Reference to this object.
00313    */
00314   virtual void DoAssign(const Signature& rSrc);
00315 
00316   /**
00317    * Std faudes type interface: test equality
00318    * 
00319    * @param rOther 
00320    *    Other object to compare with.
00321    * @return 
00322    *   True on match.
00323    */
00324   virtual bool DoEqual(const Signature& rOther) const;
00325 
00326   /**
00327    * Read signature from from TokenReader.
00328    *
00329    * The section is hardcoded to "Signature", context is ignored.
00330    *
00331    * @param rTr
00332    *   TokenReader to read from
00333    * @param rLabel
00334    *   Section to read
00335    * @param pContext
00336    *   Read context to provide contextual information (ignored)
00337    *
00338    * @exception Exception
00339    *   - IO error (id 1)
00340    *   - Token mismatch (id 50, 51, 52)
00341    */
00342   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00343  
00344   /**
00345    * Write configuration data of this object to TokenWriter.
00346    *
00347    * The section is hardcoded to "Signature", context is ignored.
00348    *
00349    * @param rTw
00350    *   Reference to TokenWriter
00351    * @param rLabel
00352    *   Label of section to write
00353    * @param pContext
00354    *   Write context to provide contextual information
00355    *
00356    * @exception Exception 
00357    *   - IO errors (id 2)
00358    */
00359   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00360 
00361   /** Variable to store name */
00362   std::string mName;
00363 
00364   /** Vector of Parameter-objects */
00365   std::vector<Parameter> mParameters;
00366 
00367 }; // Signature
00368 
00369 
00370 
00371 // forward 
00372 class Function;
00373 
00374 
00375 /**
00376  * A FunctionDefinition defines the interface to a faudes-function.
00377  * The latter consists of a descriptive name to identify the function and 
00378  * a list of Signatures the function can operate on. 
00379  * Technically, the class FunctionDefinition is derived from Documentation and 
00380  * thereby inherits members for additional
00381  * documentation-data.
00382  *
00383  * Similar to Type and TypeDefinition, a FunctionDefinition uses a prototype object to
00384  * provide the method NewFunction() which instantiates the corresponding Function object.
00385  *
00386  * FunctionDefinition inherits the token io interface from Type, however, the class is
00387  * not intended to register as a faudes type. The token io format is demonstrated by the
00388  * following example:
00389  *
00390  * @code
00391  * <FunctionDefinition name="CoreFaudes::IntegerSum" ctype="faudes::IntegerSum">
00392  *
00393  * <Documentation ref="integersum.html">
00394  * Returns the sum of integer arguments. 
00395  * <Documentation/>
00396  *
00397  * <Keywords> "integer" "elemetary types" </Keywords>
00398  *
00399  * <VariantSignatures>
00400  *
00401  * <Signature name="Two arguments">
00402  * <Parameter name="Arg1" ftype="Integer" access="In">
00403  * <Parameter name="Arg2" ftype="Integer" access="In">
00404  * <Parameter name="Res"  ftype="Integer" access="Out" creturn="true">
00405  * </Signature>
00406  *
00407  * <Signature name="Three arguments">
00408  * <Parameter name="Arg1" ftype="Integer" access="In">
00409  * <Parameter name="Arg2" ftype="Integer" access="In">
00410  * <Parameter name="Arg3" ftype="Integer" access="In">
00411  * <Parameter name="Res"  ftype="Integer" access="Out" creturn="true">
00412  * </Signature>
00413  *
00414  * </VariantSignatures>
00415  *
00416  * </FunctionDefinition>
00417  * @endcode
00418  *
00419  *
00420  * @ingroup RunTimeInterface
00421  */
00422 
00423 class FunctionDefinition : public Documentation {
00424 
00425  // std faudes type interface (cannot autoregister)
00426  FAUDES_TYPE_DECLARATION_NEW(Void,FunctionDefinition,Documentation)
00427  FAUDES_TYPE_DECLARATION_COPY(Void,FunctionDefinition,Documentation)
00428  FAUDES_TYPE_DECLARATION_CAST(Void,FunctionDefinition,Documentation)
00429  FAUDES_TYPE_DECLARATION_ASSIGN(Void,FunctionDefinition,Documentation)
00430  FAUDES_TYPE_DECLARATION_EQUAL(Void,FunctionDefinition,Documentation)
00431 
00432 public:
00433 
00434   /** 
00435    * Constructor 
00436    *
00437    * The default constructor instantiates an invalid function definition
00438    * without prototype. To construct a valid function definition, use the static 
00439    * Constructor() template function.
00440    */
00441   FunctionDefinition(const std::string& name="");
00442 
00443   /** 
00444    * Copy Constructor 
00445    *
00446    * The copy constructor copies all members one-to-one, except for
00447    * the prototype object. The latter is re-created using its factory function.
00448    */
00449   FunctionDefinition(const FunctionDefinition& rSrc);
00450 
00451   /**
00452    * Destructor
00453    */
00454   virtual ~FunctionDefinition(){ Prototype(NULL);};
00455 
00456   /**
00457    * Construct empty FunctionDefinition object.
00458    * The given template parameter denotes a Function class.
00459    * Member variable (mpFunction) is set to a new instance of that class
00460    * whereas the name is set as specified. No further documentation
00461    * or signatures are recorded.
00462    *
00463    * @tparam T
00464    *   Actual function class, derived from Function
00465    * @param rFunctName
00466    *   Name to identify this faudes-function
00467    * @return
00468    *   Newly constructed function definition.
00469    */
00470   template<class T>
00471   static FunctionDefinition* Constructor(const std::string& rFunctName="");
00472 
00473   /**
00474    * Construct FunctionDefinition object and get name and docu from file.
00475    *
00476    * The member variable mpFunction is set to a new instance of class T.
00477    * which must be derived from Function. The function name, any documentation
00478    * as well as supported signatures are read from the specified file.
00479    *
00480    * @tparam T
00481    *   Actual function class, derived from Function
00482    * @param rFileName
00483    *   File to read documentation and signatures from.
00484    * @return
00485    *   Newly constructed function definition.
00486    */
00487   template<class T>
00488   static FunctionDefinition* FromFile(const std::string& rFileName);
00489 
00490   /**
00491    * Clear documentation-data and signature (keep prototype)
00492    */
00493   virtual void Clear(void);
00494 
00495 
00496   /**
00497    * Clear variants (keep docu and prototype)
00498    */
00499   virtual void ClearVariants(void);
00500 
00501   /**
00502    * Return pointer to function object prototype 
00503    *
00504    * Note: this method is meant for inspection only, control over
00505    * the prototype remains with the FunctionDefinition. Use
00506    * NewFunction() to instantiate a new function object.
00507    *
00508    * @return
00509    *  Reference to prototype function.
00510    */
00511   const Function* Prototype(void) const;
00512 
00513   /**
00514    * Construct function on heap.
00515    * Return pointer to new instance of assigned Function class.
00516    *
00517    * Note: If no prototype is installed, NULL is returned.
00518    *
00519    * @return
00520    *  Pointer to new Function instance.
00521    */
00522   Function* NewFunction() const;
00523 
00524 
00525   /**
00526    * Return number of supported Signature instances.
00527    *
00528    * @return
00529    *  Size of signature vector.
00530    */
00531   int VariantsSize(void) const;
00532 
00533   /**
00534    * Test existence of variant by its name.
00535    *
00536    * @return
00537    *  True if variant exists
00538    */
00539   bool ExistsVariant(const std::string& varname) const;
00540 
00541   /**
00542    * Return index of Signature by name.
00543    *
00544    * @param rName
00545    *  Name of signature to search.
00546    * @return
00547    *  Index of signature, or -1 if not existant
00548    */
00549   int VariantIndex(const std::string& rName) const;
00550 
00551   /**
00552    * Return reference to Signature by name.
00553    *
00554    * @param rName
00555    *  Name of signature to search.
00556    * @return
00557    *  Reference to Signature 
00558    * @exception Exception
00559    *  - No such signature (id 47)
00560    */
00561   const Signature& Variant(const std::string& rName) const;
00562 
00563   /**
00564    * Return reference to Signature by index.
00565    *
00566    * @param n
00567    *  Index to look up
00568    * @return
00569    *  Reference to Signature 
00570    * @exception Exception
00571    *  - Index out of range (id 47)
00572    */
00573   const Signature& Variant(int n) const;
00574 
00575   /**
00576    * Add Signature to function definition.
00577    *
00578    * @param pVar
00579    *  Signature to insert
00580    * @exception Exception 
00581    *   - Signature with same name exists (id 47)
00582    */
00583   void AppendVariant(const Signature& pVar);
00584 
00585 protected:
00586 
00587   /**
00588    * Std faudes type interface: assignment.
00589    *
00590    * @param rSrc 
00591    *    Source to copy from
00592    * @return Reference to this object.
00593    */
00594   virtual void DoAssign(const FunctionDefinition& rSrc);
00595 
00596   /**
00597    * Std faudes type interface: test equality
00598    * 
00599    * @param rOther 
00600    *    Other object to compare with.
00601    * @return 
00602    *   True on match.
00603    */
00604   virtual bool DoEqual(const FunctionDefinition& rOther) const;
00605 
00606   /**
00607    * Read configuration data of this object from TokenReader.
00608    * Actual reading is done by DoReadCore.
00609    *
00610    * The section defaults to "FunctionDefinition", context ignored.
00611    *
00612    * @param rTr
00613    *   TokenReader to read from
00614    * @param rLabel
00615    *   Section to read
00616    * @param pContext
00617    *   Read context to provide contextual information (ignored)
00618    *
00619    * @exception Exception
00620    *   - Token mismatch (id 50, 51, 52)
00621    *   - IO error (id 1)
00622    */
00623   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00624  
00625   /**
00626    * Read configuration data of this object from TokenReader.
00627    *
00628    * This method reads members only, it does not read the section.
00629    *
00630    * @param rTr
00631    *   TokenReader to read from
00632    *
00633    * @exception Exception
00634    *   - Token mismatch (id 50, 51, 52)
00635    *   - IO error (id 1)
00636    */
00637   virtual void DoReadCore(TokenReader& rTr);
00638  
00639   /**
00640    * Write configuration data of this object to TokenWriter.
00641    *
00642    * The section defaults to "FunctionDefinition", context ignored.
00643    *
00644    * @param rTw
00645    *   Reference to TokenWriter
00646    * @param rLabel
00647    *   Label of section to write
00648    * @param pContext
00649    *   Write context to provide contextual information
00650    *
00651    * @exception Exception 
00652    *   - IO errors (id 2)
00653    */
00654   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00655 
00656   /**
00657    * Write configuration data of this object to TokenWriter.
00658    *
00659    * This method writes plain member data, the section lables are not
00660    * written.
00661    *
00662    * @param rTw
00663    *   Reference to TokenWriter
00664    *
00665    * @exception Exception 
00666    *   - IO errors (id 2)
00667    */
00668   virtual void DoWriteCore(TokenWriter& rTw) const;
00669 
00670   /**
00671    * Assign prototype object
00672    *
00673    * @param pFunc
00674    *  Function instance
00675    *
00676    */
00677   virtual void Prototype(Function* pFunc);
00678 
00679   /** Prototype instance */
00680   Function* mpFunction;
00681 
00682   /** Vector containing all supported Signatures */
00683   std::vector<faudes::Signature> mVariants;
00684 
00685   /** Variant name to index map */
00686   std::map<std::string,int> mVariantIndexMap;
00687 
00688 }; // FunctionDefinition
00689 
00690 
00691 
00692 /**
00693  * A faudes-function hosts parameter values of some faudes type and provides 
00694  * a method to perform an operation on the specified paramters, e.g. the 
00695  * parallel composition on two generators. The class Function is the base
00696  * for all faudes-functions, which essenitally differ in the operation method.
00697  *
00698  * The base class provides an application interface to
00699  * - select a variant signature, see Variant(); 
00700  * - set and get parameter values of any faudes type, see ParamValue();
00701  * - type check the provided parameter values, see TypeCheck(); 
00702  * - perform the operation, see Execute().
00703  *
00704  * Derivates of the base class, that acually implement an operation,
00705  * are required to cast the parameter values to the corresponding c types and then
00706  * call the respective c function. To derive a class from Function, one will
00707  * reimplment three virtual functions:
00708  * - DoTypeCheck() to perform the cast
00709  * - DoExecute() to call the c function.
00710  * - the constructor New() to replicate the function object.
00711  *
00712  * See IntegerSum in the autogenerated ./include/rtiautoload.h" for a simple example 
00713  * of a derived faudes-function.
00714  * 
00715  *
00716  * Technichal note: In contrast to faudes objects (derivates from Type), a faudes-function
00717  * must be provided a reference to the corresponding FunctionDefinition. This is because
00718  * a function must be aware of its signature(s). You must not delete 
00719  * the FunctionDefinition object during the lifetime of a faudes-function.
00720  *
00721  *
00722  * @ingroup RunTimeInterface
00723  */  
00724 
00725 class Function : public Type {
00726 
00727  public:
00728   /** 
00729    * Constructor 
00730    * For the function to be operational, a valid reference to the corresponding 
00731    * FunctionDefinition is required. The only exception is the prototype function
00732    * object used in the FunctionDefinition itself. 
00733    */
00734   Function(const FunctionDefinition* fdef);
00735 
00736   /** Destructor */
00737   ~Function(){}
00738 
00739   /**
00740    * Construct on heap.
00741    * Create a new instance of this function class and return pointer.
00742    * The new instance will use the same function definition as this instance.
00743    *
00744    * @return
00745    *  Pointer to faudes::Function instance.
00746    *
00747    */
00748   virtual Function* New() const = 0;
00749 
00750 
00751   /**
00752    * Set function definition.
00753    * Normally, functions are provided with a function definition on construction.
00754    * The only exception are prototype objects used in function definitions themselfs 
00755    * and in the function registry.
00756    *
00757    * @param fdef
00758    *  Function definition to set.
00759    *
00760    */
00761   virtual void Definition(const FunctionDefinition* fdef);
00762 
00763 
00764   /**
00765    * Get function definition.
00766    *
00767    * @return 
00768    *  Function definition used by this function.
00769    *
00770    */
00771   const FunctionDefinition* Definition(void) const;
00772 
00773 
00774   /**
00775    * Return number of variants.
00776    *
00777    * @return
00778    *  Size of vector.
00779    */
00780   int VariantsSize(void) const;
00781 
00782   /**
00783    * Set signature from function definition.
00784    *
00785    * The index n refers this function's FunctionDefinition.
00786    * An exception is thrown if no such FunctionDefinition is set, as it
00787    * is the case for prototype instances.
00788    *
00789    * @param n
00790    *  Variant index 
00791    *
00792    * @exception Exception
00793    *  - No function definition available (id 47)
00794    */
00795   void Variant(int n);
00796 
00797 
00798   /**
00799    * Set signature from function definition.
00800    *
00801    * The name refers to this function's FunctionDefinition.
00802    * An exception is thrown if no such FunctionDefinition is set, as it
00803    * is the case for prototype instances.
00804    *
00805    * @param rVariantName
00806    *  Variant name
00807    *
00808    * @exception Exception
00809    *  - No function definition available (id 47)
00810    */
00811   void Variant(const std::string& rVariantName);
00812 
00813 
00814   /**
00815    * Return pointer to assigned faudes::Signature.
00816    *
00817    * @return
00818    *  Pointer to faudes::Signature.
00819    */
00820   const Signature* Variant(void) const;
00821 
00822 
00823   /**
00824    * Return number of parameters with current signature.
00825    *
00826    * @return
00827    *  Size of vector.
00828    */
00829   int ParamsSize(void) const;
00830 
00831   /**
00832    * Set parameter at certain position.
00833    *
00834    * Sets the internal refernce of the parameter value
00835    * at the spcefied index. The ownership of the value remains with
00836    * the caller, ie it will not be deleted in the destructor of the 
00837    * function object.
00838    * You may set the parameter value to any faudes type
00839    * (classes derived from Type). A type check will be performed before the function
00840    * is executed.
00841    *
00842    * @param n
00843    *  Position index of parameter 
00844    * @param param
00845    *  Pointer to faudes object.
00846    *
00847    * @exception Exception
00848    *  - Index out of range (id 47)
00849    *  - No variant set (id 47)
00850    */
00851   void ParamValue(int n, Type* param);
00852 
00853   /**
00854    * Get parameter value.
00855    * Returns a reference to the parameter value at the specified position.
00856    *
00857    * @param n
00858    *  Position index of parameter.
00859    *
00860    * @exception Exception
00861    *  - Index out of range (id 47)
00862    */
00863   Type* ParamValue(int n) const;
00864 
00865   /**
00866    * Construct parameter values.
00867    *
00868    * This is a convenience method to allocate faudes objects for 
00869    * parameter values with the type specified by the current signature.
00870    * Note that the function does not take ownetship of the parameter values and
00871    * it is the callers responsibility to delete them when no longer required.
00872    *
00873    */
00874   void AllocateValues(void);
00875   void AllocateValue(int i);
00876 
00877   /**
00878    * Destruct parameter values.
00879    *
00880    * This is a convenience method to delete the assigned paramer values.
00881    *
00882    */
00883   void FreeValues(void);
00884 
00885   /**
00886    * Perform a type check one parameter value.
00887    * 
00888    * The type check is based on c type cast and should accept any types
00889    * derived from the type given in the signature.
00890    *
00891    * @param n
00892    *   Position of parameter to check
00893    * @return
00894    *   True if type matches  
00895    *
00896    * @exception Exception
00897    *  - No variant specified (id 48)
00898    *  - Number of parameter is outside the specified signature (id 48)
00899    *
00900    */
00901   bool TypeCheck(int n);
00902 
00903   /**
00904    * Perform a type check on the list of current parameter values.
00905    * 
00906    * The type check is based on c type cast and should accept any types
00907    * derived from those given in the signature.
00908    *
00909    * @return
00910    *   True if all parameter types matche the signature
00911    *
00912    * @exception Exception
00913    *  - No variant specified (id 48)
00914    *  - Number of parameters does not match signature (id 48)
00915    *
00916    */
00917   bool TypeCheck(void);
00918 
00919   /**
00920    * Perform operation.
00921    *
00922    * Runs a type check and then the actual function.
00923    *
00924    * @exception Exception
00925    *  - No variant specified (id 48)
00926    *  - Parameter position out of range (id 48)
00927    *  - Type mismatch (id 48)
00928    *  - Any other exception thrown ba the actual function (id xxx)
00929    */
00930   void Execute(void);
00931 
00932 
00933  protected:
00934 
00935   /**
00936    * Helper: generate typed reference for parameter.
00937    *
00938    * @param n
00939    *   Parameter position to cast
00940    * @param rTypedRef
00941    *   Typed reference to generyte
00942    * @tparam T
00943    *   c type to use for cast
00944    * @return
00945    *   True if cast succeeded.
00946    * @exception Exception
00947    *  - No variant specified (id 48)
00948    *  - Parameter position out of range (id 48)
00949    */  
00950    template<class T>
00951    bool DoTypeCast(int n, T*& rTypedRef) {
00952     if(!Variant()) {
00953        std::stringstream err;
00954        err << "No variant specified";
00955        throw Exception("Function::DoTypeCast()", err.str(), 48);
00956     }
00957     if(n<0 || n >= ParamsSize()) {
00958        std::stringstream err;
00959        err << "Parameter position out of range";
00960        throw Exception("Function::DoTypeCast()", err.str(), 48);
00961     }
00962     rTypedRef=dynamic_cast<T*>(ParamValue(n));
00963     return rTypedRef!=NULL;
00964   }
00965 
00966   /**
00967    * Method to test the type of an assigned parameter with the
00968    * specified faudes::Signature (i.e. their TypeDefinition label).
00969    *
00970    * Note: this method is called by Function::Execute() before actual function 
00971    * execution via DoExecute(). It may be used to perform a dynamic cast in 
00972    * preparation of DoExecute(). The latter is only called, if all types match.
00973    * 
00974    * @param n
00975    *   Position of parameter to check
00976    * @return
00977    *   True if type matches signature.
00978    *
00979    * @exception Exception
00980    *  - Signature undefined (id 48)
00981    *  - Parameter number out of range (id 48)
00982    */
00983   virtual bool DoTypeCheck(int n) = 0;
00984 
00985   /**
00986    * Executes code of reimplemented method of child class(es).
00987    */
00988   virtual void DoExecute() = 0;
00989 
00990   /**
00991    * Write function-data (typeid-name of arguments) to TokenWriter.
00992    *
00993    * @param rTw
00994    *  Reference to Tokenwriter.
00995    * @param rLabel
00996    *  Label of section to write.
00997    * @param pContext
00998    *  Context pointer, ignored
00999    *
01000    * @exception Exception
01001    *  - IO Error
01002    */
01003   void DoWrite(TokenWriter& rTw, const std::string& rLabel = "", const Type* pContext=0) const;
01004 
01005   /** corresponding function definition */
01006   const FunctionDefinition* pFuncDef;
01007 
01008   /** current variant aka signature as index w.r.t. the function definition */
01009   int mVariantIndex;
01010 
01011   /** Vector of arguments. */
01012   std::vector<Type*> mParameterValues;
01013 
01014 }; // Function
01015 
01016 
01017 
01018 /**********************************************************************************************
01019 ***********************************************************************************************
01020 ***********************************************************************************************
01021 
01022 Implemention of template members functions
01023 
01024 ***********************************************************************************************
01025 ***********************************************************************************************
01026 **********************************************************************************************/
01027 
01028 
01029 // typedefinition constructor function
01030 template<class T>
01031 FunctionDefinition* FunctionDefinition::Constructor(const std::string& rFunctionName){
01032   FD_DRTI("FunctionDefinition::Construct<" << typeid(T).name() << ">()");
01033   // construct void definition
01034   FunctionDefinition* td = new FunctionDefinition();
01035   // set its prototype object (note the 0 param in the new constructor)
01036   td->Prototype(new T(0));
01037   // set minmum values ie the function name
01038   std::string name=rFunctionName;
01039   if(name=="") name=typeid(T).name();
01040   td->Name(name);
01041   FD_DRTI("FunctionDefinition::Constructor<" << typeid(T).name() << ">(): done");
01042   return(td);
01043 }
01044 
01045 
01046 // function definition constructor function
01047 template<class T>
01048 FunctionDefinition* FunctionDefinition::FromFile(const std::string& rFileName){
01049   FD_DRTI("FunctionDefinition::FromFile<" << typeid(T).name() << ">()");
01050   // construct with fallback name
01051   FunctionDefinition* td = Constructor<T>();
01052   // read docu, incl actual name
01053   td->Read(rFileName);
01054   // done
01055   FD_DRTI("FunctionDefinition::FromFile<" << typeid(T).name() << ">(): done");
01056   return(td);
01057 }
01058 
01059 
01060 } // namespace
01061 
01062 
01063 #endif /* FAUDES_FUNCTIONS_H */

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3