diff options
Diffstat (limited to 'ace/Dump.h')
| -rw-r--r-- | ace/Dump.h | 153 |
1 files changed, 80 insertions, 73 deletions
diff --git a/ace/Dump.h b/ace/Dump.h index 5c1ea0f357d..742e2c649e9 100644 --- a/ace/Dump.h +++ b/ace/Dump.h @@ -1,52 +1,49 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Dump.h -// -// = DESCRIPTION -// -// A prototype mechanism that allow all ACE objects to be registered -// with a central in-memory "database" that can dump the state of all -// live ACE objects (e.g., from within a debugger). -// -// To turn on this feature simply compile with -DACE_NDEBUG -// -// There are several interesting aspects to this design: -// -// 1. It uses the External Polymorphism pattern to avoid having to -// derive all ACE classes from a common base class that has virtual -// methods (this is crucial to avoid unnecessary overhead). In -// addition, there is no additional space added to ACE objects -// (this is crucial to maintain binary layout compatibility). -// -// 2. This mechanism can be conditionally compiled in order to -// completely disable this feature entirely. Moreover, by -// using macros there are relatively few changes to ACE code. -// -// 3. This mechanism copes with single-inheritance hierarchies of -// dumpable classes. In such cases we typically want only one -// dump, corresponding to the most derived instance. Thanks to -// Christian Millour (chris@etca.fr) for illustrating how to do -// this. Note, however, that this scheme doesn't generalize to -// work with multiple-inheritance or virtual base classes. -// -// Future work includes: -// -// 1. Using a dynamic object table rather than a static table -// -// 2. Adding support to allow particular classes of objects to -// be selectively dumped. -// -// = AUTHOR -// Doug Schmidt -// -// ============================================================================ + +//============================================================================= +/** + * @file Dump.h + * + * $Id$ + * + * + * A prototype mechanism that allow all ACE objects to be registered + * with a central in-memory "database" that can dump the state of all + * live ACE objects (e.g., from within a debugger). + * + * To turn on this feature simply compile with -DACE_NDEBUG + * + * There are several interesting aspects to this design: + * + * 1. It uses the External Polymorphism pattern to avoid having to + * derive all ACE classes from a common base class that has virtual + * methods (this is crucial to avoid unnecessary overhead). In + * addition, there is no additional space added to ACE objects + * (this is crucial to maintain binary layout compatibility). + * + * 2. This mechanism can be conditionally compiled in order to + * completely disable this feature entirely. Moreover, by + * using macros there are relatively few changes to ACE code. + * + * 3. This mechanism copes with single-inheritance hierarchies of + * dumpable classes. In such cases we typically want only one + * dump, corresponding to the most derived instance. Thanks to + * Christian Millour (chris@etca.fr) for illustrating how to do + * this. Note, however, that this scheme doesn't generalize to + * work with multiple-inheritance or virtual base classes. + * + * Future work includes: + * + * 1. Using a dynamic object table rather than a static table + * + * 2. Adding support to allow particular classes of objects to + * be selectively dumped. + * + * + * @author Doug Schmidt + */ +//============================================================================= + #ifndef ACE_DUMP_H #define ACE_DUMP_H @@ -58,66 +55,76 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class ACE_Dumpable + * + * @brief Base class that defines a uniform interface for all object + * dumping. + */ class ACE_Export ACE_Dumpable { - // = TITLE - // Base class that defines a uniform interface for all object - // dumping. public: friend class ACE_ODB; friend class ACE_Dumpable_Ptr; + /// Constructor. ACE_Dumpable (const void *); - // Constructor. + /// This pure virtual method must be filled in by a subclass. virtual void dump (void) const = 0; - // This pure virtual method must be filled in by a subclass. protected: virtual ~ACE_Dumpable (void); private: + /// Pointer to the object that is being stored. const void *this_; - // Pointer to the object that is being stored. }; +/** + * @class ACE_Dumpable_Ptr + * + * @brief A smart pointer stored in the in-memory object database + * ACE_ODB. The pointee (if any) is deleted when reassigned. + */ class ACE_Export ACE_Dumpable_Ptr { - // = TITLE - // A smart pointer stored in the in-memory object database - // ACE_ODB. The pointee (if any) is deleted when reassigned. public: ACE_Dumpable_Ptr (const ACE_Dumpable *dumper = 0); const ACE_Dumpable *operator->() const; void operator= (const ACE_Dumpable *dumper) const; private: + /// "Real" pointer to the underlying abstract base class + /// pointer that does the real work. const ACE_Dumpable *dumper_; - // "Real" pointer to the underlying abstract base class - // pointer that does the real work. }; +/** + * @class ACE_ODB + * + * @brief This is the object database (ODB) that keeps track of all + * live ACE objects. + */ class ACE_Export ACE_ODB { - // = TITLE - // This is the object database (ODB) that keeps track of all - // live ACE objects. public: - enum {MAX_TABLE_SIZE = 100000}; // This is clearly inadequate and should be dynamic... + /// @todo This is clearly inadequate and should be dynamic... + enum {MAX_TABLE_SIZE = 100000}; + /// Iterates through the entire set of registered objects and + /// dumps their state. void dump_objects (void); - // Iterates through the entire set of registered objects and - // dumps their state. + /// Add the tuple <dumper, this_> to the list of registered ACE objects. void register_object (const ACE_Dumpable *dumper); - // Add the tuple <dumper, this_> to the list of registered ACE objects. + /// Use <this_> to locate and remove the associated <dumper> from the + /// list of registered ACE objects. void remove_object (const void *this_); - // Use <this_> to locate and remove the associated <dumper> from the - // list of registered ACE objects. + /// Interface to the Singleton instance of the object database. static ACE_ODB *instance (void); - // Interface to the Singleton instance of the object database. private: ACE_ODB (void); // Ensure we have a Singleton... @@ -140,15 +147,15 @@ private: Tuple (void) : dumper_(0) {} }; + /// Singleton instance of this class. static ACE_ODB *instance_; - // Singleton instance of this class. + /// The current implementation is very simple-minded and will be + /// changed to be dynamic. Tuple object_table_[ACE_ODB::MAX_TABLE_SIZE]; - // The current implementation is very simple-minded and will be - // changed to be dynamic. + /// Current size of <object_table_>. int current_size_; - // Current size of <object_table_>. }; // Include the templates classes at this point. |