|
libFAUDES
Sections
Index
|
cfl_registry.hGo 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