libFAUDES

Sections

Index

rtiregistry.h

Go to the documentation of this file.
00001 /** @file rtiregistry.h Runtime interface, registry for faudes-types and functions */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2009 Ruediger Berndt
00006 Copyright (C) 2009 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_RTIREGISTRY_H
00024 #define FAUDES_RTIREGISTRY_H
00025 
00026 #include "rtitypes.h"
00027 #include "rtifncts.h"
00028  
00029 namespace faudes{
00030 
00031 
00032 /**
00033  * The TypeRegistry registers faudes-types. A faudes-type may be
00034  * any class derived from faudes::Type, e.g. EventSet and generator.
00035  * The registry maintains a mapping from faudes-type names to registred 
00036  * faudes::TypeDefinition. It provides an interface to inspect 
00037  * TypeDefinitions or to construct faudes-type objects by their type name. 
00038  *
00039  * Technical note: the class is implemented according to the \"Singleton\" design 
00040  * pattern, ie, only one global instance of the registry can exist.
00041  *
00042  *
00043  * @ingroup RunTimeInterface
00044  */
00045 
00046 
00047 class TypeRegistry : public Type {
00048 
00049 public:
00050 
00051   /** Convenience typedef to access registry entries */     
00052   typedef std::map<std::string, TypeDefinition*>::const_iterator Iterator;
00053 
00054   /**
00055    * Method to access the single global instance of the registry.
00056    */
00057   static TypeRegistry* G();
00058 
00059   /** 
00060    * Clear all registered type definitions. This will also delete the
00061    * correponsing prototype objects.
00062    */
00063   void Clear();
00064 
00065   /**
00066    * Return number of registered type definitions.
00067    *
00068    * @return
00069    *  Size of map.
00070    */
00071   int Size() const;
00072 
00073   /**
00074    * Test existence of a faudes-type by its name.
00075    *
00076    * @param rName
00077    *  Name of type to look up
00078    *
00079    * @return
00080    *  True, if a corresponding definition is registered.
00081    */
00082   bool Exists(const std::string& rName) const;
00083 
00084   /**
00085    * Test existence of a faudes-type by faudes object
00086    *
00087    * @param rType
00088    *  Object of type to look up
00089    *
00090    * @return
00091    *  True, if a corresponding definition is registered.
00092    */
00093   bool Exists(const Type& rType) const;
00094 
00095   /**
00096    * STL interator to the internal type-name map.
00097    *
00098    * @return
00099    *  Iterator to the first element.
00100    */
00101   Iterator Begin(void) const;
00102 
00103   /**
00104    * STL interator to the internal type-name map.
00105    *
00106    * @return
00107    *  Iterator to the end of the map.
00108    */
00109   Iterator End(void) const;
00110 
00111   /**
00112    * Add another type definition to the registry.
00113    *
00114    * The registry takes the ownership pf the provided
00115    * type definition. It will be deleted either in Clear() or 
00116    * when the registry is destructed.
00117    *
00118    * @param pTypeDef
00119    *  Type definition to insert
00120    *
00121    * @exception Exception
00122    *  - Identical name found (id 46)
00123    */
00124   void Insert(TypeDefinition* pTypeDef);
00125 
00126   /**
00127    * Register a faudes-type with specified type name.
00128    *
00129    * This is a convenience function: it uses the template parameter to
00130    * construct the new instance of TypeDefinition to be registered. However,
00131    * no documentation is added. See also MergeDocumentation.
00132    *
00133    * @tparam T
00134    *   Template parameter to specify c++ type to register
00135    * @param rTypeName
00136    *   Specify the faudes-type name 
00137    * @exception Exception
00138    *  - Identical name found (id 46)
00139    */
00140   template<class T>
00141   void Insert(const std::string& rTypeName="") {
00142     FD_DRTI("TypeRegistry::Insert<>(" << rTypeName << ")");
00143     TypeDefinition* td = TypeDefinition::Constructor<T>(rTypeName);
00144     Insert(td);
00145   }
00146 
00147   /**
00148    * Register a faudes-type with specified type name.
00149    *
00150    * This is a convenience function: it uses the specified object as a
00151    * a prototype and registers it under the given name. The registry takes 
00152    * ownership of the prototype. However,
00153    * no documentation is added. See also MergeDocumentation.
00154    *
00155    * @param pProto
00156    *   Prototype object
00157    * @param rTypeName
00158    *   Specify the faudes-type name 
00159    * @exception Exception
00160    *  - Identical name found (id 46)
00161    */
00162   void Insert(Type* pProto, const std::string& rTypeName) {
00163     FD_DRTI("TypeRegistry::Insert(prototype, " << rTypeName << ")");
00164     TypeDefinition* td = TypeDefinition::Constructor(pProto, rTypeName);
00165     Insert(td);
00166   }
00167 
00168   /**
00169    * Scan token input for type documentation.
00170    * This function scans the entire token stream for sections
00171    * with label "TypeDefinition". Any such section that refers to a type name
00172    * which is known to the registry, will be applied to the corresponding 
00173    * registry entry. Typical invokation is as follows
00174    *
00175    * @code
00176    * TypeRegistry::G()->Insert<EventSet>("EventSet");
00177    * TypeRegistry::G()->Insert<Generator>("Generator");
00178    * TypeRegistry::G()->MergeDocumentation("alldocufile.rti");
00179    * @endcode
00180    *
00181    * @param rTr
00182    *  Token stream.
00183    * @exception Exception
00184    *  - Token mismatch (id 50, 51, 52)
00185    *  - IO Error (id 1)
00186    */
00187   void MergeDocumentation(TokenReader& rTr);
00188 
00189   /**
00190    * Scan file for type documentation.
00191    * Convenience method, see also MergeDocumentation(TokenReader& rTr)
00192    *
00193    * @param rFileName
00194    *  Name of file to scan.
00195    * @exception Exception
00196    *  - Token mismatch (id 50, 51, 52)
00197    *  - IO Error (id 1)
00198    */
00199   void MergeDocumentation(const std::string& rFileName);
00200 
00201   /**
00202    * Construct a faudes object by type name
00203    *
00204    * Uses the internal prototype object to construct
00205    * an object of the same c type on the heap. 
00206    *
00207    * @param rTypeName
00208    *  Label of TypeDefinition to search for.
00209    * @return
00210    *  Pointer to new faudes::Type instance 
00211    * @exception Exception
00212    *  - Unknown type (id 47)
00213    */
00214   Type* NewObject(const std::string& rTypeName) const;
00215 
00216   /**
00217    * Construct a faudes object by prototype object.
00218    *
00219    * Depreciated: use new on the faudes object instead.
00220    *
00221    * @param rType
00222    *  Prototype object.
00223    *
00224    * @return
00225    *  Pointer to new faudes::Type instance
00226    * @exception Exception
00227    *  - Unknown type (id 47)
00228    */
00229   Type* NewObject(const Type& rType) const;
00230 
00231 
00232   /**
00233    * Look up the type definition by faudes-type name
00234    *
00235    * @param rTypeName
00236    *  Label of faudes::TypeDefinition to search for.
00237    *
00238    * @return
00239    *  Reference to faudes::TypeDefinition
00240    *
00241    * @exception Exception
00242    *  - Unknown type (id 46)
00243    */
00244   const TypeDefinition& Definition(const std::string& rTypeName) const;
00245 
00246   /**
00247    * Look up the type definition by faudes object
00248    *
00249    * Techcal note: this implementation is slow, we should
00250    * use a type id map. 
00251    *
00252    * @param rType
00253    *  Reference to faudes::Type to search for.
00254    *
00255    * @return
00256    *  Reference to faudes::TypeDefinition
00257    *
00258    * @exception Exception
00259    *  - Unknown type (id 46)
00260    */
00261   const TypeDefinition& Definition(const Type& rType) const;
00262 
00263   /**
00264    * Look up the type name by faudes object
00265    *
00266    * @param rType
00267    *  Reference to faudes::Type to search for.
00268    *
00269    * @return
00270    *  Type name as string or "" if unknown.
00271    *
00272    */
00273   const std::string& TypeName(const Type& rType) const;
00274 
00275  protected:
00276 
00277   /**
00278    * Write registry data of this to TokenWriter.
00279    *
00280    * Since the registry cannot reconfigure itself from a token stream,
00281    * this output is informative only. However, MergeDocumentation will 
00282    * accept the format to extract documentation.
00283    *
00284    * @param rTw
00285    *   Reference to TokenWriter
00286    * @param rLabel
00287    *   Label of section to write
00288    * @param pContext
00289    *   Write context to provide contextual information
00290    *
00291    * @exception Exception 
00292    *   - IO errors (id 2)
00293    */
00294   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00295 
00296   /** Convenience typedef to access registry entries */     
00297   typedef std::map<std::string, TypeDefinition*>::iterator iterator;
00298 
00299   /** Singleton instance */
00300   static TypeRegistry* mpInstance;
00301 
00302   /** Constructor */
00303   TypeRegistry(){}
00304 
00305   /** Destructor */
00306   virtual ~TypeRegistry(){
00307     Clear();
00308   }
00309 
00310   /** Map to associate labels and faudes::TypeDefinitions. */
00311   std::map<std::string, TypeDefinition*> mNameToTypeDef;
00312   std::map<std::string, TypeDefinition*> mIdToTypeDef;
00313 
00314 }; // TypeRegistry
00315 
00316 
00317 
00318 
00319 
00320 /**
00321  * The FunctionRegistry registers faudes-functions. A faudes-functions
00322  * operates on faudes objects, eg the parallel composition of two 
00323  * generators is available as faudes-function. The registry maintains a
00324  * mapping between function names and a coresponding function::Definition.
00325  * The latter provides signatures, ie parameter types the function can 
00326  * take. The registry provides an interface to inspect 
00327  * TypeDefinitions or to construct function objects by their type name. 
00328  *
00329  * Technical note: the class is implemented according to the \"Singleton\" design 
00330  * pattern, ie, only one global instance of the registry can exist.
00331  *
00332  * @ingroup RunTimeInterface
00333  */
00334 
00335 class FunctionRegistry : public Type {
00336 
00337 public:
00338 
00339   /** Convenience typedef to access registry entries */     
00340   typedef std::map<std::string, FunctionDefinition*>::const_iterator Iterator;
00341 
00342   /**
00343    * Method to access the single global instance of the registry.
00344    */
00345   static FunctionRegistry* G();
00346 
00347   /** 
00348    * Clear all registered function definitions. This will also delete the
00349    * correponsing prototype objects.
00350    */
00351   void Clear();
00352 
00353   /**
00354    * Return number of registered function definitions.
00355    *
00356    * @return
00357    *  Size of map.
00358    */
00359   int Size() const;
00360 
00361   /**
00362    * Test existence of a faudes-function by its name.
00363    *
00364    * @param rName
00365    *  Name of function to look up
00366    *
00367    * @return
00368    *  True, if a corresponding definition is registered.
00369    */
00370   bool Exists(const std::string& rName) const;
00371 
00372   /**
00373    * Test existence of a faudes-function by faudes object
00374    *
00375    * @param rFunction
00376    *  Object of function to look up
00377    *
00378    * @return
00379    *  True, if a corresponding definition is registered.
00380    */
00381   bool Exists(const Function& rFunction) const;
00382 
00383   /**
00384    * STL interator to the internal function-name map.
00385    *
00386    * @return
00387    *  Iterator to the first element.
00388    */
00389   Iterator Begin(void) const;
00390 
00391   /**
00392    * STL interator to the internal function-name map.
00393    *
00394    * @return
00395    *  Iterator to the end of the map.
00396    */
00397   Iterator End(void) const;
00398 
00399   /**
00400    * Add another function definition to the registry.
00401    *
00402    * The registry takes the ownership pf the provided
00403    * function definition. It will be deleted either in Clear() or 
00404    * when the registry is destructed.
00405    *
00406    * @param pFunctionDef
00407    *  Function definition to insert
00408    *
00409    * @exception Exception
00410    *  - Identical name found (id 46)
00411    */
00412   void Insert(FunctionDefinition* pFunctionDef);
00413 
00414   /**
00415    * Register a faudes-function with specified function name.
00416    *
00417    * This is a convenience function: it uses the template parameter to
00418    * construct the new instance of FunctionDefinition to be registered. However,
00419    * no documentation is added. See also MergeDocumentation.
00420    *
00421    * @tparam T
00422    *   Template parameter to specify c++ function to register
00423    * @param rFunctionName
00424    *   Specify the faudes-function name 
00425    * @exception Exception
00426    *  - Identical name found (id 46)
00427    */
00428   template<class T>
00429   void Insert(const std::string& rFunctionName="") {
00430     FD_DRTI("FunctionRegistry::Insert<>(" << rFunctionName << ")");
00431     FunctionDefinition* td = FunctionDefinition::Constructor<T>(rFunctionName);
00432     Insert(td);
00433   }
00434 
00435   /**
00436    * Scan token input for function documentation.
00437    * This function scans the entire token stream for sections
00438    * with label "FunctionDefinition". Any such section that refers to a function name
00439    * which is known to the registry, will be applied to the corresponding 
00440    * registry entry.
00441    *
00442    *
00443    * @param rTr
00444    *  Token stream.
00445    * @exception Exception
00446    *  - Token mismatch (id 50, 51, 52)
00447    *  - IO Error (id 1)
00448    */
00449   void MergeDocumentation(TokenReader& rTr);
00450 
00451   /**
00452    * Scan file for function documentation.
00453    * Convenience method, see also MergeDocumentation(TokenReader& rTr)
00454    *
00455    * @param rFileName
00456    *  Name of file to scan.
00457    * @exception Exception
00458    *  - Token mismatch (id 50, 51, 52)
00459    *  - IO Error (id 1)
00460    */
00461   void MergeDocumentation(const std::string& rFileName);
00462 
00463   /**
00464    * Construct a faudes object by function name
00465    *
00466    * Uses the internal prototype object to construct
00467    * an object of the same c function on the heap. 
00468    *
00469    * @param rFunctionName
00470    *  Label of FunctionDefinition to search for.
00471    * @return
00472    *  Pointer to new faudes::Function instance 
00473    * @exception Exception
00474    *  - Unknown function (id 47)
00475    */
00476   Function* NewFunction(const std::string& rFunctionName) const;
00477 
00478   /**
00479    * Construct a faudes object by protofunction object.
00480    *
00481    * Depreciated: use new on the faudes object instead.
00482    *
00483    * @param rFunction
00484    *  Protofunction object.
00485    *
00486    * @return
00487    *  Pointer to new faudes::Function instance 
00488    * @exception Exception
00489    *  - Unknown function (id 47)
00490    */
00491   Function* NewFunction(const Function& rFunction) const;
00492 
00493 
00494   /**
00495    * Look up the function definition by faudes-function name
00496    *
00497    * @param rFunctionName
00498    *  Label of faudes::FunctionDefinition to search for.
00499    *
00500    * @return
00501    *  Reference to faudes::FunctionDefinition
00502    *
00503    * @exception Exception
00504    *  - Unknown function (id 46)
00505    */
00506   const FunctionDefinition& Definition(const std::string& rFunctionName) const;
00507 
00508   /**
00509    * Look up the function definition by faudes object
00510    *
00511    * Techcal note: this implementation is slow, we should
00512    * use a function id map. 
00513    *
00514    * @param rFunction
00515    *  Reference to faudes::Function to search for.
00516    *
00517    * @return
00518    *  Reference to faudes::FunctionDefinition
00519    *
00520    * @exception Exception
00521    *  - Unknown function (id 46)
00522    */
00523   const FunctionDefinition& Definition(const Function& rFunction) const;
00524 
00525  protected:
00526 
00527   /**
00528    * Write registry data of this to TokenWriter.
00529    *
00530    * Since the registry cannot reconfigure itself from a token stream,
00531    * this output is informative only. However, MergeDocumentation will 
00532    * accept the format to extract documentation.
00533    *
00534    * @param rTw
00535    *   Reference to TokenWriter
00536    * @param rLabel
00537    *   Label of section to write
00538    * @param pContext
00539    *   Write context to provide contextual information
00540    *
00541    * @exception Exception 
00542    *   - IO errors (id 2)
00543    */
00544   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00545 
00546   /** Convenience typedef to access registry entries */     
00547   typedef std::map<std::string, FunctionDefinition*>::iterator iterator;
00548 
00549   /** Singleton instance */
00550   static FunctionRegistry* mpInstance;
00551 
00552   /** Constructor */
00553   FunctionRegistry(){}
00554 
00555   /** Destructor */
00556   virtual ~FunctionRegistry(){
00557     Clear();
00558   }
00559 
00560   /** Map to associate labels and faudes::FunctionDefinitions. */
00561   std::map<std::string, FunctionDefinition*> mNameToFunctionDef;
00562   std::map<std::string, FunctionDefinition*> mIdToFunctionDef;
00563 
00564 }; // FunctionRegistry
00565 
00566 
00567 /** 
00568  * Load all registered types and functions
00569  *
00570  * @ingroup RunTimeInterface
00571  */
00572 
00573 void LoadRegistry(const std::string& rPath="");
00574 
00575 
00576 /** 
00577  * Clear all registry
00578  *
00579  * @ingroup RunTimeInterface
00580  */
00581 
00582 void ClearRegistry(void);
00583 
00584 
00585 /** 
00586  * Convenience function to access registry singleton
00587  * 
00588  * @param rTypeName
00589  *  Type to instantiate
00590  *
00591  * @ingroup RunTimeInterface
00592  */
00593 
00594 Type* NewObject(const std::string& rTypeName);
00595 
00596 /** 
00597  * Convenience function to access registry singleton
00598  * 
00599  * @param rObject
00600  *  Faudes object instance
00601  * @return
00602  *  Faudes type name or "" if unkown.
00603  *
00604  * @ingroup RunTimeInterface
00605  */
00606 
00607 const std::string& TypeName(const Type& rObject);
00608 
00609 /** 
00610  * Convenience function to access registry singleton
00611  *
00612  * @param rFunctName
00613  *  Function to instantiate
00614  *
00615  * @ingroup RunTimeInterface
00616  */
00617 
00618 Function* NewFunction(const std::string& rFunctName);
00619 
00620 
00621 
00622 /**********************************************************************************************
00623 ***********************************************************************************************
00624 ***********************************************************************************************
00625 
00626 Implemention of template members functions
00627 
00628 ***********************************************************************************************
00629 ***********************************************************************************************
00630 **********************************************************************************************/
00631 
00632 
00633 
00634 
00635 
00636 } // namespace
00637 
00638 #endif /* FAUDES_RTIREGISTRY_H */

libFAUDES 2.14g --- 2009-12-3 --- c++ source docu by doxygen 1.5.6