ACE/ace/Active_Map_Manager_T.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Active_Map_Manager_T.h
   6  *
   7  *  @author Irfan Pyarali
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_ACTIVE_MAP_MANAGER_T_H
  12 #define ACE_ACTIVE_MAP_MANAGER_T_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/Map_Manager.h"
  16 #include "ace/Active_Map_Manager.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Null_Mutex.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class ACE_Active_Map_Manager
  28  *
  29  * @brief Define a map abstraction that associates system generated
  30  * keys with user specified values.
  31  *
  32  * Since the key is system generated, searches are very fast and
  33  * take a constant amount of time.
  34  */
  35 template <class T>
  36 class ACE_Active_Map_Manager : public ACE_Map_Manager<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex>
  37 {
  38 public:
  39   // = Traits.
  40   typedef ACE_Active_Map_Manager_Key key_type;
  41   typedef T mapped_type;
  42
  43   typedef ACE_Map_Entry<ACE_Active_Map_Manager_Key, T> ENTRY;
  44   typedef ACE_Map_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> ITERATOR;
  45   typedef ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> REVERSE_ITERATOR;
  46
  47   typedef ENTRY entry;
  48   typedef ITERATOR iterator;
  49   typedef REVERSE_ITERATOR reverse_iterator;
  50
  51   /// Initialize a Active_Map_Manager with the ACE_DEFAULT_MAP_SIZE.
  52   ACE_Active_Map_Manager (ACE_Allocator *alloc = nullptr);
  53
  54   /// Initialize a Active_Map_Manager with @a size entries.
  55   ACE_Active_Map_Manager (size_t size,
  56                           ACE_Allocator *alloc = nullptr);
  57
  58   /// Close down a Active_Map_Manager and release dynamically
  59   /// allocated resources.
  60   ~ACE_Active_Map_Manager () = default;
  61
  62   /// Initialize a Active_Map_Manager with size @a length.
  63   int open (size_t length = ACE_DEFAULT_MAP_SIZE,
  64             ACE_Allocator *alloc = nullptr);
  65
  66   /// Close down a Active_Map_Manager and release dynamically
  67   /// allocated resources.
  68   int close ();
  69
  70   /// Add @a value to the map, and the corresponding key produced by the
  71   /// Active_Map_Manager is returned through @a key.
  72   int bind (const T &value,
  73             ACE_Active_Map_Manager_Key &key);
  74
  75   /// Add @a value to the map.  The user does not care about the
  76   /// corresponding key produced by the Active_Map_Manager.
  77   int bind (const T &value);
  78
  79   /**
  80    * Reserves a slot in the internal structure and returns the key and
  81    * a pointer to the value.  User should place their @a value into
  82    * @a internal_value.  This method is useful in reducing the number
  83    * of copies required in some cases.  Note that @a internal_value is
  84    * only a temporary pointer and will change when the map resizes.
  85    * Therefore, the user should use the pointer immediately and not
  86    * hold on to it.
  87    */
  88   int bind (ACE_Active_Map_Manager_Key &key,
  89             T *&internal_value);
  90
  91   /// Reassociate @a key with @a value. The function fails if @a key is
  92   /// not in the map.
  93   int rebind (const ACE_Active_Map_Manager_Key &key,
  94               const T &value);
  95
  96   /**
  97    * Reassociate @a key with @a value, storing the old value into the
  98    * "out" parameter @a old_value.  The function fails if @a key is not
  99    * in the map.
 100    */
 101   int rebind (const ACE_Active_Map_Manager_Key &key,
 102               const T &value,
 103               T &old_value);
 104
 105   /**
 106    * Reassociate @a key with @a value, storing the old key and value
 107    * into the "out" parameter @a old_key and @a old_value.  The function
 108    * fails if @a key is not in the map.
 109    */
 110   int rebind (const ACE_Active_Map_Manager_Key &key,
 111               const T &value,
 112               ACE_Active_Map_Manager_Key &old_key,
 113               T &old_value);
 114
 115   /// Locate @a value associated with @a key.
 116   int find (const ACE_Active_Map_Manager_Key &key,
 117             T &value) const;
 118
 119   /// Is @a key in the map?
 120   int find (const ACE_Active_Map_Manager_Key &key) const;
 121
 122   /**
 123    * Locate @a value associated with @a key.  The value is returned via
 124    * @a internal_value and hence a copy is saved.  Note that
 125    * @a internal_value is only a temporary pointer and will change when
 126    * the map resizes.  Therefore, the user should use the pointer
 127    * immediately and not hold on to it.
 128    */
 129   int find (const ACE_Active_Map_Manager_Key &key,
 130             T *&internal_value) const;
 131
 132   // Creates a key.  User should place their @a value into
 133   // <*internal_value>.  This method is useful in reducing the number
 134   // of copies required in some cases.
 135
 136   /// Remove @a key from the map.
 137   int unbind (const ACE_Active_Map_Manager_Key &key);
 138
 139   /// Remove @a key from the map, and return the @a value associated with
 140   /// @a key.
 141   int unbind (const ACE_Active_Map_Manager_Key &key,
 142               T &value);
 143
 144   /**
 145    * Locate @a value associated with @a key.  The value is returned via
 146    * @a internal_value and hence a copy is saved.  Note that
 147    * @a internal_value is only a temporary pointer and will change when
 148    * the map resizes or when this slot is reused.  Therefore, the user
 149    * should use the pointer immediately and not hold on to it.
 150    */
 151   int unbind (const ACE_Active_Map_Manager_Key &key,
 152               T *&internal_value);
 153
 154   /// Return the current size of the map.
 155   size_t current_size () const;
 156
 157   /// Return the total size of the map.
 158   size_t total_size () const;
 159
 160   /// Returns a key that cannot be found in the map.
 161   static const ACE_Active_Map_Manager_Key npos ();
 162
 163   /// Dump the state of an object.
 164   void dump () const;
 165
 166   // = STL styled iterator factory functions.
 167
 168   /// Return forward iterator.
 169   ACE_Map_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> begin ();
 170   ACE_Map_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> end ();
 171
 172   /// Return reverse iterator.
 173   ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> rbegin ();
 174   ACE_Map_Reverse_Iterator<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> rend ();
 175
 176   /// Declare the dynamic allocation hooks.
 177   ACE_ALLOC_HOOK_DECLARE;
 178
 179 protected:
 180   /// Private base class
 181   typedef ACE_Map_Manager<ACE_Active_Map_Manager_Key, T, ACE_Null_Mutex> ACE_AMM_BASE;
 182
 183 private:
 184   // = Disallow these operations.
 185   void operator= (const ACE_Active_Map_Manager<T> &) = delete;
 186   ACE_Active_Map_Manager (const ACE_Active_Map_Manager<T> &) = delete;
 187 };
 188
 189 ACE_END_VERSIONED_NAMESPACE_DECL
 190
 191 #if defined (__ACE_INLINE__)
 192 #include "ace/Active_Map_Manager_T.inl"
 193 #endif /* __ACE_INLINE__ */
 194
 195 #include "ace/Active_Map_Manager_T.cpp"
 196
 197 #include /**/ "ace/post.h"
 198 #endif /* ACE_ACTIVE_MAP_MANAGER_T_H */