libFAUDES

Sections

Index

cfl_registry.h

Go to the documentation of this file.
00001 /** @file cfl_registry.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 "cfl_types.h"
00027 #include "cfl_functions.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 prototype object by faudes-type name
00248    *
00249    * @param rTypeName
00250    *  Label of faudes::TypeDefinition to search for.
00251    *
00252    * @return
00253    *  Reference to faudes::Type object, Null for unknown type
00254    *
00255    */
00256   const Type* Prototype(const std::string& rTypeName) const;
00257 
00258   /**
00259    * Look up the type definition by faudes object
00260    *
00261    * Techcal note: this implementation is slow, we should
00262    * use a type id map. 
00263    *
00264    * @param rType
00265    *  Reference to faudes::Type to search for.
00266    *
00267    * @return
00268    *  Reference to faudes::TypeDefinition
00269    *
00270    * @exception Exception
00271    *  - Unknown type (id 46)
00272    */
00273   const TypeDefinition& Definition(const Type& rType) const;
00274 
00275   /**
00276    * Look up the type name by faudes object
00277    *
00278    * @param rType
00279    *  Reference to faudes::Type to search for.
00280    *
00281    * @return
00282    *  Type name as string or "" if unknown.
00283    *
00284    */
00285   const std::string& TypeName(const Type& rType) const;
00286 
00287  protected:
00288 
00289   /**
00290    * Write registry data of this to TokenWriter.
00291    *
00292    * Since the registry cannot reconfigure itself from a token stream,
00293    * this output is informative only. However, MergeDocumentation will 
00294    * accept the format to extract documentation.
00295    *
00296    * @param rTw
00297    *   Reference to TokenWriter
00298    * @param rLabel
00299    *   Label of section to write
00300    * @param pContext
00301    *   Write context to provide contextual information
00302    *
00303    * @exception Exception 
00304    *   - IO errors (id 2)
00305    */
00306   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00307 
00308   /** Convenience typedef to access registry entries */     
00309   typedef std::map<std::string, TypeDefinition*>::iterator iterator;
00310 
00311   /** Singleton instance */
00312   static TypeRegistry* mpInstance;
00313 
00314   /** Constructor */
00315   TypeRegistry(){}
00316 
00317   /** Destructor */
00318   virtual ~TypeRegistry(){
00319     Clear();
00320   }
00321 
00322   /** Map to associate labels and faudes::TypeDefinitions. */
00323   std::map<std::string, TypeDefinition*> mNameToTypeDef;
00324   std::map<std::string, TypeDefinition*> mIdToTypeDef;
00325 
00326 }; // TypeRegistry
00327 
00328 
00329 
00330 
00331 
00332 /**
00333  * The FunctionRegistry registers faudes-functions. A faudes-functions
00334  * operates on faudes objects, eg the parallel composition of two 
00335  * generators is available as faudes-function. The registry maintains a
00336  * mapping between function names and a coresponding function::Definition.
00337  * The latter provides signatures, ie parameter types the function can 
00338  * take. The registry provides an interface to inspect 
00339  * TypeDefinitions or to construct function objects by their type name. 
00340  *
00341  * Technical note: the class is implemented according to the \"Singleton\" design 
00342  * pattern, ie, only one global instance of the registry can exist.
00343  *
00344  * @ingroup RunTimeInterface
00345  */
00346 
00347 class FunctionRegistry : public Type {
00348 
00349 public:
00350 
00351   /** Convenience typedef to access registry entries */     
00352   typedef std::map<std::string, FunctionDefinition*>::const_iterator Iterator;
00353 
00354   /**
00355    * Method to access the single global instance of the registry.
00356    */
00357   static FunctionRegistry* G();
00358 
00359   /** 
00360    * Clear all registered function definitions. This will also delete the
00361    * correponsing prototype objects.
00362    */
00363   void Clear();
00364 
00365   /**
00366    * Return number of registered function definitions.
00367    *
00368    * @return
00369    *  Size of map.
00370    */
00371   int Size() const;
00372 
00373   /**
00374    * Test existence of a faudes-function by its name.
00375    *
00376    * @param rName
00377    *  Name of function to look up
00378    *
00379    * @return
00380    *  True, if a corresponding definition is registered.
00381    */
00382   bool Exists(const std::string& rName) const;
00383 
00384   /**
00385    * Test existence of a faudes-function by faudes object
00386    *
00387    * @param rFunction
00388    *  Object of function to look up
00389    *
00390    * @return
00391    *  True, if a corresponding definition is registered.
00392    */
00393   bool Exists(const Function& rFunction) const;
00394 
00395   /**
00396    * STL interator to the internal function-name map.
00397    *
00398    * @return
00399    *  Iterator to the first element.
00400    */
00401   Iterator Begin(void) const;
00402 
00403   /**
00404    * STL interator to the internal function-name map.
00405    *
00406    * @return
00407    *  Iterator to the end of the map.
00408    */
00409   Iterator End(void) const;
00410 
00411   /**
00412    * Add another function definition to the registry.
00413    *
00414    * The registry takes the ownership pf the provided
00415    * function definition. It will be deleted either in Clear() or 
00416    * when the registry is destructed.
00417    *
00418    * @param pFunctionDef
00419    *  Function definition to insert
00420    *
00421    * @exception Exception
00422    *  - Identical name found (id 46)
00423    */
00424   void Insert(FunctionDefinition* pFunctionDef);
00425 
00426   /**
00427    * Register a faudes-function with specified function name.
00428    *
00429    * This is a convenience function: it uses the template parameter to
00430    * construct the new instance of FunctionDefinition to be registered. However,
00431    * no documentation is added. See also MergeDocumentation.
00432    *
00433    * @tparam T
00434    *   Template parameter to specify c++ function to register
00435    * @param rFunctionName
00436    *   Specify the faudes-function name 
00437    * @exception Exception
00438    *  - Identical name found (id 46)
00439    */
00440   template<class T>
00441   void Insert(const std::string& rFunctionName="") {
00442     FD_DRTI("FunctionRegistry::Insert<>(" << rFunctionName << ")");
00443     FunctionDefinition* td = FunctionDefinition::Constructor<T>(rFunctionName);
00444     Insert(td);
00445   }
00446 
00447   /**
00448    * Scan token input for function documentation.
00449    * This function scans the entire token stream for sections
00450    * with label "FunctionDefinition". Any such section that refers to a function name
00451    * which is known to the registry, will be applied to the corresponding 
00452    * registry entry.
00453    *
00454    *
00455    * @param rTr
00456    *  Token stream.
00457    * @exception Exception
00458    *  - Token mismatch (id 50, 51, 52)
00459    *  - IO Error (id 1)
00460    */
00461   void MergeDocumentation(TokenReader& rTr);
00462 
00463   /**
00464    * Scan file for function documentation.
00465    * Convenience method, see also MergeDocumentation(TokenReader& rTr)
00466    *
00467    * @param rFileName
00468    *  Name of file to scan.
00469    * @exception Exception
00470    *  - Token mismatch (id 50, 51, 52)
00471    *  - IO Error (id 1)
00472    */
00473   void MergeDocumentation(const std::string& rFileName);
00474 
00475   /**
00476    * Construct a faudes object by function name
00477    *
00478    * Uses the internal prototype object to construct
00479    * an object of the same c function on the heap. 
00480    *
00481    * @param rFunctionName
00482    *  Label of FunctionDefinition to search for.
00483    * @return
00484    *  Pointer to new faudes::Function instance 
00485    * @exception Exception
00486    *  - Unknown function (id 47)
00487    */
00488   Function* NewFunction(const std::string& rFunctionName) const;
00489 
00490   /**
00491    * Construct a faudes object by protofunction object.
00492    *
00493    * Depreciated: use new on the faudes object instead.
00494    *
00495    * @param rFunction
00496    *  Protofunction object.
00497    *
00498    * @return
00499    *  Pointer to new faudes::Function instance 
00500    * @exception Exception
00501    *  - Unknown function (id 47)
00502    */
00503   Function* NewFunction(const Function& rFunction) const;
00504 
00505 
00506   /**
00507    * Look up the function definition by faudes-function name
00508    *
00509    * @param rFunctionName
00510    *  Label of faudes::FunctionDefinition to search for.
00511    *
00512    * @return
00513    *  Reference to faudes::FunctionDefinition
00514    *
00515    * @exception Exception
00516    *  - Unknown function (id 46)
00517    */
00518   const FunctionDefinition& Definition(const std::string& rFunctionName) const;
00519 
00520   /**
00521    * Look up the function definition by faudes object
00522    *
00523    * Techcal note: this implementation is slow, we should
00524    * use a function id map. 
00525    *
00526    * @param rFunction
00527    *  Reference to faudes::Function to search for.
00528    *
00529    * @return
00530    *  Reference to faudes::FunctionDefinition
00531    *
00532    * @exception Exception
00533    *  - Unknown function (id 46)
00534    */
00535   const FunctionDefinition& Definition(const Function& rFunction) const;
00536 
00537  protected:
00538 
00539   /**
00540    * Write registry data of this to TokenWriter.
00541    *
00542    * Since the registry cannot reconfigure itself from a token stream,
00543    * this output is informative only. However, MergeDocumentation will 
00544    * accept the format to extract documentation.
00545    *
00546    * @param rTw
00547    *   Reference to TokenWriter
00548    * @param rLabel
00549    *   Label of section to write
00550    * @param pContext
00551    *   Write context to provide contextual information
00552    *
00553    * @exception Exception 
00554    *   - IO errors (id 2)
00555    */
00556   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00557 
00558   /** Convenience typedef to access registry entries */     
00559   typedef std::map<std::string, FunctionDefinition*>::iterator iterator;
00560 
00561   /** Singleton instance */
00562   static FunctionRegistry* mpInstance;
00563 
00564   /** Constructor */
00565   FunctionRegistry(){}
00566 
00567   /** Destructor */
00568   virtual ~FunctionRegistry(){
00569     Clear();
00570   }
00571 
00572   /** Map to associate labels and faudes::FunctionDefinitions. */
00573   std::map<std::string, FunctionDefinition*> mNameToFunctionDef;
00574   std::map<std::string, FunctionDefinition*> mIdToFunctionDef;
00575 
00576 }; // FunctionRegistry
00577 
00578 
00579 /** 
00580  * Load all registered types and functions
00581  *
00582  * @ingroup RunTimeInterface
00583  */
00584 
00585 void LoadRegistry(const std::string& rPath="");
00586 
00587 
00588 /** 
00589  * Clear all registry
00590  *
00591  * @ingroup RunTimeInterface
00592  */
00593 
00594 void ClearRegistry(void);
00595 
00596 
00597 /** 
00598  * Convenience function to access registry singleton
00599  * 
00600  * @param rTypeName
00601  *  Type to instantiate
00602  *
00603  * @ingroup RunTimeInterface
00604  */
00605 
00606 Type* NewObject(const std::string& rTypeName);
00607 
00608 /** 
00609  * Convenience function to access registry singleton
00610  * 
00611  * @param rObject
00612  *  Faudes object instance
00613  * @return
00614  *  Faudes type name or "" if unkown.
00615  *
00616  * @ingroup RunTimeInterface
00617  */
00618 
00619 const std::string& TypeName(const Type& rObject);
00620 
00621 /** 
00622  * Convenience function to access registry singleton
00623  *
00624  * @param rFunctName
00625  *  Function to instantiate
00626  *
00627  * @ingroup RunTimeInterface
00628  */
00629 
00630 Function* NewFunction(const std::string& rFunctName);
00631 
00632 
00633 
00634 /**********************************************************************************************
00635 ***********************************************************************************************
00636 ***********************************************************************************************
00637 
00638 Implemention of template members functions
00639 
00640 ***********************************************************************************************
00641 ***********************************************************************************************
00642 **********************************************************************************************/
00643 
00644 
00645 
00646 
00647 
00648 } // namespace
00649 
00650 #endif /* FAUDES_RTIREGISTRY_H */

libFAUDES 2.16b --- 2010-9-8 --- c++ source docu by doxygen 1.6.3