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