cfl_registry.h
Go to the documentation of this file.
1 /** @file cfl_registry.h Runtime interface, registry for faudes-types and functions */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5 Copyright (C) 2009 Ruediger Berndt
6 Copyright (C) 2009 Thomas Moor
7 
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Lesser General Public
10 License as published by the Free Software Foundation; either
11 version 2.1 of the License, or (at your option) any later version.
12 
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17 
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
21 
22 
23 #ifndef FAUDES_RTIREGISTRY_H
24 #define FAUDES_RTIREGISTRY_H
25 
26 #include "cfl_types.h"
27 #include "cfl_functions.h"
28 
29 namespace faudes{
30 
31 
32 /**
33  * The TypeRegistry registers faudes-types. A faudes-type may be
34  * any class derived from faudes::Type, e.g. EventSet and generator.
35  * The registry maintains a mapping from faudes-type names to registred
36  * faudes::TypeDefinition. It provides an interface to inspect
37  * TypeDefinitions or to construct faudes-type objects by their type name.
38  *
39  * Technical note: the class is implemented according to the \"Singleton\" design
40  * pattern, ie, only one global instance of the registry can exist.
41  *
42  *
43  * @ingroup RunTimeInterface
44  */
45 
46 
47 class TypeRegistry : public Type {
48 
49 public:
50 
51  /** Convenience typedef to access registry entries */
52  typedef std::map<std::string, TypeDefinition*>::const_iterator Iterator;
53 
54  /**
55  * Method to access the single global instance of the registry.
56  */
57  static TypeRegistry* G();
58 
59  /**
60  * Clear all registered type definitions. This will also delete the
61  * correponsing prototype objects. It will, however, not delete
62  * C++-autoregistered registry entries.
63  */
64  void Clear();
65 
66  /**
67  * Clear all registered type definitions. This will also delete the
68  * correponsing prototype objects. This version will also
69  * delete C++-autoregistered registry entries.
70  */
71  void ClearAll();
72 
73  /**
74  * Return number of registered type definitions.
75  *
76  * @return
77  * Size of map.
78  */
79  int Size() const;
80 
81  /**
82  * Test existence of a faudes-type by its name.
83  *
84  * @param rName
85  * Name of type to look up
86  *
87  * @return
88  * True, if a corresponding definition is registered.
89  */
90  bool Exists(const std::string& rName) const;
91 
92  /**
93  * Test existence of a faudes-type by faudes object
94  *
95  * @param rType
96  * Object of type to look up
97  *
98  * @return
99  * True, if a corresponding definition is registered.
100  */
101  bool Exists(const Type& rType) const;
102 
103  /**
104  * STL interator to the internal type-name map.
105  *
106  * @return
107  * Iterator to the first element.
108  */
109  Iterator Begin(void) const;
110 
111  /**
112  * STL interator to the internal type-name map.
113  *
114  * @return
115  * Iterator to the end of the map.
116  */
117  Iterator End(void) const;
118 
119  /**
120  * Add another type definition to the registry.
121  *
122  * The registry takes the ownership pf the provided
123  * type definition. It will be deleted either in Clear() or
124  * when the registry is destructed. The insertion of an allready registered
125  * type is ignored as long as the ctype matches. If the ctype
126  * fails to match, an exception is thrown.
127  *
128  * @param pTypeDef
129  * Type definition to insert
130  *
131  * @exception Exception
132  * - Identical name found (id 46)
133  */
134  void Insert(TypeDefinition* pTypeDef);
135 
136  /**
137  * Register a faudes-type with specified type name.
138  *
139  * This is a convenience function: it uses the template parameter to
140  * construct the new instance of TypeDefinition to be registered. However,
141  * no documentation is added. See also MergeDocumentation.
142  *
143  * @tparam T
144  * Template parameter to specify c++ type to register
145  * @param rTypeName
146  * Specify the faudes-type name
147  * @exception Exception
148  * - Identical name found (id 46)
149  */
150  template<class T>
151  void Insert(const std::string& rTypeName="") {
152  FD_DRTI("TypeRegistry::Insert<" << typeid(T).name() << ">(" << rTypeName << ")");
153  TypeDefinition* td = TypeDefinition::Constructor<T>(rTypeName);
154  Insert(td);
155  }
156 
157  /**
158  * Register a faudes-type with specified type name.
159  *
160  * This is a convenience function: it uses the specified object as a
161  * a prototype and registers it under the given name. The registry takes
162  * ownership of the prototype. However,
163  * no documentation is added. See also MergeDocumentation.
164  *
165  * @param pProto
166  * Prototype object
167  * @param rTypeName
168  * Specify the faudes-type name
169  * @exception Exception
170  * - Identical name found (id 46)
171  */
172  void Insert(Type* pProto, const std::string& rTypeName) {
173  FD_DRTI("TypeRegistry::Insert(prototype, " << rTypeName << ")");
174  TypeDefinition* td = TypeDefinition::Constructor(pProto, rTypeName);
175  Insert(td);
176  }
177 
178  /**
179  * Scan token input for type documentation.
180  * This function scans the entire token stream for sections
181  * with label "TypeDefinition". Any such section that refers to a type name
182  * which is known to the registry, will be applied to the corresponding
183  * registry entry. Typical invokation is as follows
184  *
185  * @code
186  * TypeRegistry::G()->Insert<EventSet>("EventSet");
187  * TypeRegistry::G()->Insert<Generator>("Generator");
188  * TypeRegistry::G()->MergeDocumentation("alldocufile.rti");
189  * @endcode
190  *
191  * @param rTr
192  * Token stream.
193  * @exception Exception
194  * - Token mismatch (id 50, 51, 52)
195  * - IO Error (id 1)
196  */
197  void MergeDocumentation(TokenReader& rTr);
198 
199  /**
200  * Scan file for type documentation.
201  * Convenience method, see also MergeDocumentation(TokenReader& rTr)
202  *
203  * @param rFileName
204  * Name of file to scan.
205  * @exception Exception
206  * - Token mismatch (id 50, 51, 52)
207  * - IO Error (id 1)
208  */
209  void MergeDocumentation(const std::string& rFileName);
210 
211 
212  /**
213  * Set Xml element tag for given faudes-type.
214  *
215  * Access to the XElementTag of a type definition. The latter is
216  * used for Xml token IO of sets and vectors.
217  * Unregistered types are silently ignored.
218  *
219  * @param rTypeName
220  * Name of faudes-type
221  * @param rTag
222  * New value of tag
223  */
224  void XElementTag(const std::string& rTypeName, const std::string& rTag);
225 
226  /**
227  * Get Xml element tag for given faudes-type.
228  *
229  * Access to the XElementTag of a type definition. The latter is
230  * used for Xml token IO of sets and vectors.
231  * Unregistered types return the empty string.
232  *
233  * @param rTypeName
234  * Name of faudes-type
235  * @return
236  * Xml element tag
237  */
238  const std::string& XElementTag(const std::string& rTypeName) const;
239 
240  /**
241  * Get AutoRegister flag for given faudes-type.
242  *
243  * Access the AutoRegister flag of a type definition.
244  * The flag is true for entries which were instantiated
245  * automatically by static constructor objects. AutoRegistered flags
246  * will not be cleared.
247  *
248  * @param rTypeName
249  * Name of faudes-type
250  * @return
251  * AutoRegister flag
252  */
253  bool AutoRegistered(const std::string& rTypeName) const;
254 
255  /**
256  * Set AutoRegistered flag for given faudes-type.
257  *
258  * Access the AutoRegister flag of a type definition.
259  * The flag is true for entries with were instantiated by
260  * automatically by static constructor objects. AutoRegistered flags
261  * will not be cleared.
262  *
263  * @param rTypeName
264  * Name of faudes-type
265  * @param flag
266  * New value of flag
267  */
268  void AutoRegistered(const std::string& rTypeName, bool flag);
269 
270  /**
271  * Construct a faudes object by type name
272  *
273  * Uses the internal prototype object to construct
274  * an object of the same c type on the heap.
275  *
276  * @param rTypeName
277  * Label of TypeDefinition to search for.
278  * @return
279  * Pointer to new faudes::Type instance
280  * @exception Exception
281  * - Unknown type (id 47)
282  */
283  Type* NewObject(const std::string& rTypeName) const;
284 
285  /**
286  * Construct a faudes object by prototype object.
287  *
288  * Depreciated: use new on the faudes object instead.
289  *
290  * @param rType
291  * Prototype object.
292  *
293  * @return
294  * Pointer to new faudes::Type instance
295  * @exception Exception
296  * - Unknown type (id 47)
297  */
298  Type* NewObject(const Type& rType) const;
299 
300 
301  /**
302  * Look up the type definition by faudes-type name
303  *
304  * @param rTypeName
305  * Faudes-tyep name to search for.
306  *
307  * @return
308  * Reference to faudes::TypeDefinition
309  *
310  * @exception Exception
311  * - Unknown type (id 46)
312  */
313  const TypeDefinition& Definition(const std::string& rTypeName) const;
314 
315  /**
316  * Look up the type definition by faudes object
317  *
318  * @param rType
319  * Reference to faudes::Type to search for.
320  *
321  * @return
322  * Reference to faudes::TypeDefinition
323  *
324  * @exception Exception
325  * - Unknown type (id 46)
326  */
327  const TypeDefinition& Definition(const Type& rType) const;
328 
329  /**
330  * Look up the type definition by faudes-type name
331  *
332  * @param rTypeName
333  * Faudes-tyep name to search for.
334  *
335  * @return
336  * Pointer to faudes::TypeDefinition, NULL for unknoen type.
337  *
338  */
339  const TypeDefinition* Definitionp(const std::string& rTypeName) const;
340 
341  /**
342  * Look up the type definition by faudes object
343  *
344  * @param rType
345  * Reference to faudes::Type to search for.
346  *
347  * @return
348  * Pointer to faudes::TypeDefinition, NULL for unknoen type.
349  *
350  */
351  const TypeDefinition* Definitionp(const Type& rType) const;
352 
353 
354  /**
355  * Look up the prototype object by faudes-type name
356  *
357  * @param rTypeName
358  * Label of faudes::TypeDefinition to search for.
359  *
360  * @return
361  * Reference to faudes::Type object, Null for unknown type
362  *
363  */
364  const Type* Prototype(const std::string& rTypeName) const;
365 
366  /**
367  * Look up the type name by faudes object
368  *
369  * @param rType
370  * Reference to faudes::Type to search for.
371  *
372  * @return
373  * Type name as string or "" if unknown.
374  *
375  */
376  const std::string& TypeName(const Type& rType) const;
377 
378  /**
379  * Test type compatibility.
380  * Test whether the provided object
381  * can be casted to the specified type name,
382  *
383  * @param rTypeName
384  * Faudes type name
385  * @param rObject
386  * Faudes object instance
387  * @return
388  * True, if object can be casted to specified faudes type.
389  *
390  */
391  bool TypeTest(const std::string& rTypeName, const Type& rObject) const;
392 
393 
394  protected:
395 
396  /**
397  * Write registry data of this to TokenWriter.
398  *
399  * Since the registry cannot reconfigure itself from a token stream,
400  * this output is informative only. However, MergeDocumentation will
401  * accept the format to extract documentation.
402  *
403  * @param rTw
404  * Reference to TokenWriter
405  * @param rLabel
406  * Label of section to write
407  * @param pContext
408  * Write context to provide contextual information
409  *
410  * @exception Exception
411  * - IO errors (id 2)
412  */
413  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
414 
415  /** Convenience typedef to access registry entries */
416  typedef std::map<std::string, TypeDefinition*>::iterator iterator;
417 
418  /** Singleton instance */
420 
421  /** Constructor */
423 
424  /** Destructor */
425  virtual ~TypeRegistry(){
426  Clear();
427  }
428 
429  /** Map to associate labels and faudes::TypeDefinitions. */
430  std::map<std::string, TypeDefinition*> mNameToTypeDef;
431  std::map<std::string, TypeDefinition*> mIdToTypeDef;
432 
433 }; // TypeRegistry
434 
435 
436 /**
437  * Auto register faudes-type with specified type name.
438  *
439  * This is a convenience class template to automize faudes type registration.
440  * It uses the Insert template of the type registry. If the type name
441  * is already registered, no registration will take place and the old
442  * configuration is maintained. Also registration with faudes-type name "Void"
443  * will be silently ignored.
444  * Type documentation is not supported but may
445  * be added via MergeDocumentation.
446  *
447  * @tparam T
448  * Template parameter to specify the C++ type to register
449  * @param rTypeName
450  * Specify the faudes-type name
451  */
452 template<class T>
454  public:
455  AutoRegisterType(const std::string& rTypeName="Void") {
456  if(rTypeName=="Void") return;
457  if(TypeRegistry::G()->Exists(rTypeName)) return;
458  FD_DREG("AutoRegisterType(" << rTypeName << "): by prototype template with " << typeid(T).name());
459  TypeRegistry::G()->Insert<T>(rTypeName);
460  TypeRegistry::G()->AutoRegistered(rTypeName,true);
461  };
462 };
463 
464 template<class T>
466  public:
467  AutoRegisterXElementTag(const std::string& rTypeName, const std::string& rTag) {
468  static AutoRegisterType<T> srego(rTypeName);
469  TypeRegistry::G()->XElementTag(rTypeName,rTag);
470  };
471 };
472 
473 
474 
475 
476 /**
477  * The FunctionRegistry registers faudes-functions. A faudes-functions
478  * operates on faudes objects, eg the parallel composition of two
479  * generators is available as faudes-function. The registry maintains a
480  * mapping between function names and a coresponding function::Definition.
481  * The latter provides signatures, ie parameter types the function can
482  * take. The registry provides an interface to inspect
483  * TypeDefinitions or to construct function objects by their type name.
484  *
485  * Technical note: the class is implemented according to the \"Singleton\" design
486  * pattern, ie, only one global instance of the registry can exist.
487  *
488  * @ingroup RunTimeInterface
489  */
490 
491 class FunctionRegistry : public Type {
492 
493 public:
494 
495  /** Convenience typedef to access registry entries */
496  typedef std::map<std::string, FunctionDefinition*>::const_iterator Iterator;
497 
498  /**
499  * Method to access the single global instance of the registry.
500  */
501  static FunctionRegistry* G();
502 
503  /**
504  * Clear all registered function definitions. This will also delete the
505  * correponsing prototype objects.
506  */
507  void Clear();
508 
509  /**
510  * Return number of registered function definitions.
511  *
512  * @return
513  * Size of map.
514  */
515  int Size() const;
516 
517  /**
518  * Test existence of a faudes-function by its name.
519  *
520  * @param rName
521  * Name of function to look up
522  *
523  * @return
524  * True, if a corresponding definition is registered.
525  */
526  bool Exists(const std::string& rName) const;
527 
528  /**
529  * Test existence of a faudes-function by faudes object
530  *
531  * @param rFunction
532  * Object of function to look up
533  *
534  * @return
535  * True, if a corresponding definition is registered.
536  */
537  bool Exists(const Function& rFunction) const;
538 
539  /**
540  * STL interator to the internal function-name map.
541  *
542  * @return
543  * Iterator to the first element.
544  */
545  Iterator Begin(void) const;
546 
547  /**
548  * STL interator to the internal function-name map.
549  *
550  * @return
551  * Iterator to the end of the map.
552  */
553  Iterator End(void) const;
554 
555  /**
556  * Add another function definition to the registry.
557  *
558  * The registry takes the ownership pf the provided
559  * function definition. It will be deleted either in Clear() or
560  * when the registry is destructed.
561  *
562  * @param pFunctionDef
563  * Function definition to insert
564  *
565  * @exception Exception
566  * - Identical name found (id 46)
567  */
568  void Insert(FunctionDefinition* pFunctionDef);
569 
570  /**
571  * Register a faudes-function with specified function name.
572  *
573  * This is a convenience function: it uses the template parameter to
574  * construct the new instance of FunctionDefinition to be registered. However,
575  * no documentation is added. See also MergeDocumentation.
576  *
577  * @tparam T
578  * Template parameter to specify c++ function to register
579  * @param rFunctionName
580  * Specify the faudes-function name
581  * @exception Exception
582  * - Identical name found (id 46)
583  */
584  template<class T>
585  void Insert(const std::string& rFunctionName="") {
586  FD_DRTI("FunctionRegistry::Insert<>(" << rFunctionName << ")");
587  FunctionDefinition* td = FunctionDefinition::Constructor<T>(rFunctionName);
588  Insert(td);
589  }
590 
591  /**
592  * Scan token input for function documentation.
593  * This function scans the entire token stream for sections
594  * with label "FunctionDefinition". Any such section that refers to a function name
595  * which is known to the registry, will be applied to the corresponding
596  * registry entry.
597  *
598  *
599  * @param rTr
600  * Token stream.
601  * @exception Exception
602  * - Token mismatch (id 50, 51, 52)
603  * - IO Error (id 1)
604  */
605  void MergeDocumentation(TokenReader& rTr);
606 
607  /**
608  * Scan file for function documentation.
609  * Convenience method, see also MergeDocumentation(TokenReader& rTr)
610  *
611  * @param rFileName
612  * Name of file to scan.
613  * @exception Exception
614  * - Token mismatch (id 50, 51, 52)
615  * - IO Error (id 1)
616  */
617  void MergeDocumentation(const std::string& rFileName);
618 
619  /**
620  * Construct a faudes object by function name
621  *
622  * Uses the internal prototype object to construct
623  * an object of the same c function on the heap.
624  *
625  * @param rFunctionName
626  * Label of FunctionDefinition to search for.
627  * @return
628  * Pointer to new faudes::Function instance
629  * @exception Exception
630  * - Unknown function (id 47)
631  */
632  Function* NewFunction(const std::string& rFunctionName) const;
633 
634  /**
635  * Construct a faudes object by protofunction object.
636  *
637  * Depreciated: use new on the faudes object instead.
638  *
639  * @param rFunction
640  * Protofunction object.
641  *
642  * @return
643  * Pointer to new faudes::Function instance
644  * @exception Exception
645  * - Unknown function (id 47)
646  */
647  Function* NewFunction(const Function& rFunction) const;
648 
649 
650  /**
651  * Look up the function definition by faudes-function name
652  *
653  * @param rFunctionName
654  * Label of faudes::FunctionDefinition to search for.
655  *
656  * @return
657  * Reference to faudes::FunctionDefinition
658  *
659  * @exception Exception
660  * - Unknown function (id 46)
661  */
662  const FunctionDefinition& Definition(const std::string& rFunctionName) const;
663 
664  /**
665  * Look up the function definition by faudes object
666  *
667  * Techcal note: this implementation is slow, we should
668  * use a function id map.
669  *
670  * @param rFunction
671  * Reference to faudes::Function to search for.
672  *
673  * @return
674  * Reference to faudes::FunctionDefinition
675  *
676  * @exception Exception
677  * - Unknown function (id 46)
678  */
679  const FunctionDefinition& Definition(const Function& rFunction) const;
680 
681  /**
682  * Look up the function name by faudes object
683  *
684  * @param rFunction
685  * Reference to faudes::Function to search for.
686  *
687  * @return
688  * Function name as string or "" if unknown.
689  *
690  */
691  const std::string& FunctionName(const Function& rFunction) const;
692 
693  protected:
694 
695  /**
696  * Write registry data of this to TokenWriter.
697  *
698  * Since the registry cannot reconfigure itself from a token stream,
699  * this output is informative only. However, MergeDocumentation will
700  * accept the format to insert/extract documentation.
701  *
702  * @param rTw
703  * Reference to TokenWriter
704  * @param rLabel
705  * Label of section to write
706  * @param pContext
707  * Write context to provide contextual information
708  *
709  * @exception Exception
710  * - IO errors (id 2)
711  */
712  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
713 
714  /** Convenience typedef to access registry entries */
715  typedef std::map<std::string, FunctionDefinition*>::iterator iterator;
716 
717  /** Singleton instance */
719 
720  /** Constructor */
722 
723  /** Destructor */
724  virtual ~FunctionRegistry(){
725  Clear();
726  }
727 
728  /** Map to associate labels and faudes::FunctionDefinitions. */
729  std::map<std::string, FunctionDefinition*> mNameToFunctionDef;
730  std::map<std::string, FunctionDefinition*> mIdToFunctionDef;
731 
732 }; // FunctionRegistry
733 
734 
735 /**
736  * Load all registered types and functions.
737  *
738  * The default file is some not so educated guess, so you
739  * should specify it explicitely.
740  *
741  * @param rPath
742  * Source file
743  *
744  * @ingroup RunTimeInterface
745  */
746 
747 void LoadRegistry(const std::string& rPath="");
748 
749 
750 /**
751  * Dump all registered types and functions
752  *
753  * The destinations defaults to stdout.
754  *
755  * @param rPath
756  * Destination file
757  *
758  * @ingroup RunTimeInterface
759  */
760 
761 void SaveRegistry(const std::string& rPath="");
762 
763 
764 /**
765  * Clear all registry
766  *
767  * @ingroup RunTimeInterface
768  */
769 
770 void ClearRegistry(void);
771 
772 
773 /**
774  * Instantiate faudes typed objects by type name.
775  * Convenience function to access registry singleton.
776  *
777  * @param rTypeName
778  * Type to instantiate
779  *
780  * @ingroup RunTimeInterface
781  */
782 
783 Type* NewFaudesObject(const std::string& rTypeName);
784 
785 /**
786  * Query type name.
787  * Convenience function to access registry singleton.
788  *
789  * @param rObject
790  * Faudes object instance
791  * @return
792  * Faudes type name or "" if unkown.
793  *
794  * @ingroup RunTimeInterface
795  */
796 
797 const std::string& FaudesTypeName(const Type& rObject);
798 
799 
800 /**
801  * Test type compatibility.
802  * Convenience function to access registry singleton.
803  *
804  * @param rTypeName
805  * Faudes type name
806  * @param rObject
807  * Faudes object instance
808  * @return
809  * True, if object can be casted to specified faudes type.
810  *
811  * @ingroup RunTimeInterface
812  */
813 bool FaudesTypeTest(const std::string& rTypeName, const Type& rObject);
814 
815 
816 /**
817  * Instantiate faudes function objects by function name.
818  * Convenience function to access registry singleton.
819  *
820  * @param rFunctName
821  * Function to instantiate
822  *
823  * @ingroup RunTimeInterface
824  */
825 
826 Function* NewFaudesFunction(const std::string& rFunctName);
827 
828 /**
829  * Query function name.
830  * Convenience function to access registry singleton.
831  *
832  * @param rObject
833  * Faudes object instance
834  * @return
835  * Faudes function name or "" if unkown.
836  *
837  * @ingroup RunTimeInterface
838  */
839 
840 const std::string& FaudesFunctionName(const Type& rObject);
841 
842 
843 
844 /**********************************************************************************************
845 ***********************************************************************************************
846 ***********************************************************************************************
847 
848 Implemention of template members functions
849 
850 ***********************************************************************************************
851 ***********************************************************************************************
852 **********************************************************************************************/
853 
854 
855 
856 
857 
858 } // namespace
859 
860 #endif /* FAUDES_RTIREGISTRY_H */

libFAUDES 2.26g --- 2015.08.17 --- c++ api documentaion by doxygen