ACE/ace/Dump.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Dump.h
   6  *
   7  * A prototype mechanism that allow all ACE objects to be registered
   8  * with a central in-memory "database" that can dump the state of all
   9  * live ACE objects (e.g., from within a debugger).
  10  *
  11  * The macros which allow easy registration and removal of objects to be
  12  * dumped (ACE_REGISTER_OBJECT and ACE_REMOVE_OBJECT) are turned into
  13  * no-ops by compiling with the ACE_NDEBUG macro defined. This allows
  14  * usage to be removed in "release mode" builds without changing code.
  15  *
  16  * There are several interesting aspects to this design:
  17  *
  18  * 1. It uses the External Polymorphism pattern to avoid having to
  19  *  derive all ACE classes from a common base class that has virtual
  20  *  methods (this is crucial to avoid unnecessary overhead).  In
  21  *  addition, there is no additional space added to ACE objects
  22  *  (this is crucial to maintain binary layout compatibility).
  23  *
  24  * 2. This mechanism can be conditionally compiled in order to
  25  *  completely disable this feature entirely.  Moreover, by
  26  *  using macros there are relatively few changes to ACE code.
  27  *
  28  * 3. This mechanism copes with single-inheritance hierarchies of
  29  *  dumpable classes.  In such cases we typically want only one
  30  *  dump, corresponding to the most derived instance.  Thanks to
  31  *  Christian Millour (chris@etca.fr) for illustrating how to do
  32  *  this.  Note, however, that this scheme doesn't generalize to
  33  *  work with multiple-inheritance or virtual base classes.
  34  *
  35  * Future work includes:
  36  *
  37  * 1. Using a dynamic object table rather than a static table
  38  *
  39  * 2. Adding support to allow particular classes of objects to
  40  *  be selectively dumped.
  41  *
  42  *  @author Doug Schmidt
  43  */
  44 //=============================================================================
  45
  46
  47 #ifndef ACE_DUMP_H
  48 #define ACE_DUMP_H
  49 #include /**/ "ace/pre.h"
  50
  51 #include /**/ "ace/ACE_export.h"
  52
  53 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  54 # pragma once
  55 #endif /* ACE_LACKS_PRAGMA_ONCE */
  56
  57 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  58
  59 /**
  60  * @class ACE_Dumpable
  61  *
  62  * @brief Base class that defines a uniform interface for all object
  63  * dumping.
  64  */
  65 class ACE_Export ACE_Dumpable
  66 {
  67 public:
  68   friend class ACE_ODB;
  69   friend class ACE_Dumpable_Ptr;
  70
  71   /// Constructor.
  72   ACE_Dumpable (const void *);
  73
  74   /// This pure virtual method must be filled in by a subclass.
  75   virtual void dump (void) const = 0;
  76
  77 protected:
  78   virtual ~ACE_Dumpable (void);
  79
  80 private:
  81   /// Pointer to the object that is being stored.
  82   const void *this_;
  83 };
  84
  85 /**
  86  * @class ACE_Dumpable_Ptr
  87  *
  88  * @brief A smart pointer stored in the in-memory object database
  89  * ACE_ODB.  The pointee (if any) is deleted when reassigned.
  90  */
  91 class ACE_Export ACE_Dumpable_Ptr
  92 {
  93 public:
  94   ACE_Dumpable_Ptr (const ACE_Dumpable *dumper = 0);
  95   const ACE_Dumpable *operator->() const;
  96   void operator= (const ACE_Dumpable *dumper) const;
  97
  98 private:
  99   /// "Real" pointer to the underlying abstract base class
 100   /// pointer that does the real work.
 101   const ACE_Dumpable *dumper_;
 102 };
 103
 104 /**
 105  * @class ACE_ODB
 106  *
 107  * @brief This is the object database (ODB) that keeps track of all
 108  * live ACE objects.
 109  */
 110 class ACE_Export ACE_ODB
 111 {
 112 public:
 113   /// @todo This is clearly inadequate and should be dynamic...
 114   enum {MAX_TABLE_SIZE = 100000};
 115
 116   /// Iterates through the entire set of registered objects and
 117   /// dumps their state.
 118   void dump_objects (void);
 119
 120   /// Add the tuple <dumper, this_> to the list of registered ACE objects.
 121   void register_object (const ACE_Dumpable *dumper);
 122
 123   /// Use <this_> to locate and remove the associated <dumper> from the
 124   /// list of registered ACE objects.
 125   void remove_object (const void *this_);
 126
 127   /// Interface to the Singleton instance of the object database.
 128   static ACE_ODB *instance (void);
 129
 130   ACE_ALLOC_HOOK_DECLARE;
 131
 132 private:
 133   ACE_ODB (void); // Ensure we have a Singleton...
 134
 135   struct Tuple
 136   {
 137     /// Pointer to the object that is registered.
 138     const void *this_;
 139
 140     /// Smart pointer to the ACE_Dumpable object associated with this_.
 141     /// This uses an ACE_Dumpable_Ptr, instead of a bare pointer, to
 142     /// cope with hierarchies of dumpable classes.  In such cases we
 143     /// typically want only one dump, corresponding to the most derived
 144     /// instance. To achieve this, the handle registered for the
 145     /// subobject corresponding to the base class is destroyed (hence
 146     /// on destruction of the subobject its handle won't exist anymore
 147     /// and we'll have to check for that).
 148     const ACE_Dumpable_Ptr dumper_;
 149
 150     Tuple (void) : this_ (0), dumper_(0) {}
 151   };
 152
 153   /// Singleton instance of this class.
 154   static ACE_ODB *instance_;
 155
 156   /// The current implementation is very simple-minded and will be
 157   /// changed to be dynamic.
 158   Tuple object_table_[ACE_ODB::MAX_TABLE_SIZE];
 159
 160   /// Current size of <object_table_>.
 161   int current_size_;
 162 };
 163
 164 ACE_END_VERSIONED_NAMESPACE_DECL
 165
 166 // Include the templates classes at this point.
 167 #include "ace/Dump_T.h"
 168
 169 #include /**/ "ace/post.h"
 170 #endif /* ACE_DUMP_H */