TAO/tao/ObjectKey_Table.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file ObjectKey_Table.h
   6  *
   7  *  @author Balachandran Natarajan <bala@dre.vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef TAO_OBJECTKEY_TABLE_H
  12 #define TAO_OBJECTKEY_TABLE_H
  13
  14 #include /**/ "ace/pre.h"
  15 #include "ace/RB_Tree.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Null_Mutex.h"
  22
  23 #include "tao/Object_KeyC.h"
  24 #include /**/ "tao/Versioned_Namespace.h"
  25
  26 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 // Forward declarations
  29 class TAO_ORB_Core;
  30
  31 namespace TAO
  32 {
  33   // Forward declarations within the namespace..
  34   class Refcounted_ObjectKey;
  35   class ObjectKey;
  36
  37   /**
  38    * @class Less_Than_ObjectKey
  39    *
  40    * @brief Compares the length and then the contents of ObjectKeys.
  41    *
  42    * Should have been a specialization of the functor
  43    * ACE_Less_Than<sequence<CORBA::Octet>>. But that will not work
  44    * so easily across bunch of stuff. Hence let us put up with this
  45    * for the time being.
  46    */
  47   class TAO_Export Less_Than_ObjectKey
  48   {
  49   public:
  50     bool operator () (const TAO::ObjectKey &lhs,
  51                       const TAO::ObjectKey &rhs) const;
  52   };
  53
  54   /**
  55    * @class ObjectKey_Table
  56    *
  57    * @brief Table that maintains the set of ObjectKey's seen by the
  58    * ORB.
  59    *
  60    * The ORB maintains one table for the whole ORB. ObjectKeys
  61    * generated by the ORB or the ones seen by the ORB from remote
  62    * ORB's are stored here. The ObjectKeys are stored through a
  63    * wrapper which encapsulates the reference count on them. This class
  64    * actually provides the synchronization mechanism for manipulating
  65    * the reference counts on the object keys provided by the wrapper
  66    * class.
  67    *
  68    * This class does not offer a find () call with a reason. The call
  69    * to bind () will return a pointer which is expected to be cached
  70    * by the client/caller and use the pointer in every invocation.
  71    *
  72    * @note This class uses the ACE_RB_Tree to maintain the table of
  73    * ObjectKeys. The RB_Tree has good insertion and lookup
  74    * properties. Its Iteration properties are not that good, but we
  75    * don't need to do much iteration unless we are closing down the
  76    * table.
  77    *
  78    * @note The reasons to use RB_Tree are its good dynamic
  79    * properties. We should try to strategize the class to use either a
  80    * Hash_Map or a RB_Tree based on some runtime option. For that we
  81    * need an adapter class in ACE, like an ACE_Lock_Adapter class. We
  82    * will do that if our instrumentation shows the need for it.
  83    *
  84    */
  85   class TAO_Export ObjectKey_Table
  86   {
  87   public:
  88     /// Default Constructor and destructor..
  89     ObjectKey_Table ();
  90
  91     ~ObjectKey_Table ();
  92
  93     /// Iterates and unbinds the contents of the table.
  94     int destroy ();
  95
  96     /// Bind the ObjectKey in the table.
  97     /**
  98      * Bind an ObjectKey in the table and return a pointer to the
  99      * Refcounted_ObjectKey which the client can use. If the ObjectKey
 100      * is already available in the table, this operation just
 101      * increments the refcount on the ObjectKey. If the ObjectKey is
 102      * new it is bounded to the table. Returns a 0 on success and a -1
 103      * on failure.
 104      */
 105     int bind (const ObjectKey &key, Refcounted_ObjectKey *&key_new);
 106
 107     /// Unbind an ObjectKey from the table.
 108     int unbind (TAO::Refcounted_ObjectKey *&key);
 109
 110   protected:
 111     /// Implementation for bind ().
 112     int bind_i (const ObjectKey &key, Refcounted_ObjectKey *&key_new);
 113
 114     /// Implementation for unbind ().
 115     int unbind_i (Refcounted_ObjectKey *&key);
 116
 117   private:
 118     ObjectKey_Table (const ObjectKey_Table &) = delete;
 119     ObjectKey_Table &operator= (const ObjectKey_Table &) = delete;
 120
 121     /// Some useful typedefs.
 122     typedef ACE_RB_Tree<TAO::ObjectKey,
 123                         TAO::Refcounted_ObjectKey *,
 124                         TAO::Less_Than_ObjectKey,
 125                         ACE_Null_Mutex> TABLE;
 126
 127     /// Lock for the table.
 128     TAO_SYNCH_MUTEX lock_;
 129
 130     /// Table that contains the data
 131     TABLE table_;
 132   };
 133 }
 134
 135 TAO_END_VERSIONED_NAMESPACE_DECL
 136
 137 #if defined (__ACE_INLINE__)
 138 # include "tao/ObjectKey_Table.inl"
 139 #endif /* __ACE_INLINE__ */
 140
 141 #include /**/ "ace/post.h"
 142
 143 #endif /*TAO_OBJECT_KEY_TABLE_H*/