dep/ACE_wrappers/ace/Dump.h

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