ACE/ace/Cache_Map_Manager_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Cache_Map_Manager_T.h
   6  *
   7  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_CACHE_MAP_MANAGER_T_H
  12 #define ACE_CACHE_MAP_MANAGER_T_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/config-all.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Default_Constants.h"
  23 #include "ace/Global_Macros.h"
  24 #include "ace/Pair_T.h"
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 // Forward declaration.
  29 class ACE_Allocator;
  30
  31 #define ACE_Cache_Map_Iterator ACMI
  32 #define ACE_Cache_Map_Reverse_Iterator ACMRI
  33
  34 template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
  35 class ACE_Cache_Map_Iterator;
  36
  37 template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
  38 class ACE_Cache_Map_Reverse_Iterator;
  39
  40 // For linkers that cant grok long names.
  41 #define ACE_Cache_Map_Manager ACMM
  42
  43 /**
  44  * @class ACE_Cache_Map_Manager
  45  *
  46  * @brief Defines a abstraction that will purge entries from a map.
  47  *
  48  * The <ACE_Cache_Map_Manager> will manage the map it contains
  49  * and provide purging on demand from the map. The strategy for
  50  * caching is decided by the user and provided to the Cache
  51  * Manager.  The Cache Manager acts as a agent and communicates
  52  * between the Map and the Strategy for purging entries from the
  53  * map.
  54  * No locking mechanism provided since locking at this level
  55  * isn't efficient.  Locking has to be provided by the
  56  * application.
  57  */
  58 template <class KEY, class VALUE, class CMAP_TYPE, class ITERATOR_IMPL, class REVERSE_ITERATOR_IMPL, class CACHING_STRATEGY, class ATTRIBUTES>
  59 class ACE_Cache_Map_Manager
  60 {
  61 public:
  62   // = Traits.
  63   typedef KEY key_type;
  64   typedef VALUE mapped_type;
  65   typedef CMAP_TYPE map_type;
  66   typedef CACHING_STRATEGY caching_strategy_type;
  67
  68   typedef ITERATOR_IMPL ITERATOR_IMPLEMENTATION;
  69   typedef REVERSE_ITERATOR_IMPL REVERSE_ITERATOR_IMPLEMENTATION;
  70
  71   friend class ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;
  72   friend class ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;
  73
  74   // = ACE-style iterator typedefs.
  75   typedef ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
  76           ITERATOR;
  77   typedef ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
  78           REVERSE_ITERATOR;
  79
  80    // = STL-style iterator typedefs.
  81   typedef ITERATOR
  82           iterator;
  83   typedef REVERSE_ITERATOR
  84           reverse_iterator;
  85
  86   /**
  87    * The actual value mapped to the key in the map. The <attributes>
  88    * are used by the strategy and is transparent to the user of this
  89    * class.
  90    */
  91   typedef std::pair<VALUE, ATTRIBUTES> CACHE_VALUE;
  92
  93   /// Initialize a <Cache_Map_Manager> with <caching_strategy> and
  94   /// @a size entries.
  95   ACE_Cache_Map_Manager (CACHING_STRATEGY &caching_strategy,
  96                          size_t size = ACE_DEFAULT_MAP_SIZE,
  97                          ACE_Allocator *alloc = nullptr);
  98
  99   /// Close down a <Cache_Map_Manager> and release dynamically allocated
 100   /// resources.
 101   virtual ~ACE_Cache_Map_Manager ();
 102
 103   /// Initialize a cache with size @a length.
 104   int open (size_t length = ACE_DEFAULT_MAP_SIZE,
 105             ACE_Allocator *alloc = nullptr);
 106
 107   /// Close down a cache and release dynamically allocated resources.
 108   int close ();
 109
 110   /**
 111    * Associate @a key with @a value.  If @a key is already in the CMAP_TYPE
 112    * then the ENTRY is not changed.  Returns 0 if a new entry is bound
 113    * successfully, returns 1 if an attempt is made to bind an existing
 114    * entry, and returns -1 if failures occur.
 115    */
 116   int bind (const KEY &key,
 117             const VALUE &value);
 118
 119   /**
 120    * Lookup entry<key,value> in the cache. If it is not found, returns -1.
 121    * If the @a key is located in the CMAP_TYPE object, the CACHING_STRATEGY is
 122    * notified of it via notify_find (int result, ATTRIBUTES &attribute).
 123    * If notify_find also returns 0 (success), then this function returns
 124    * 0 (success) and sets the cached value in @a value.
 125    */
 126   int find (const KEY &key,
 127             VALUE &value);
 128
 129   /**
 130    * Lookup entry<key,value> in the cache. If it is not found, returns -1.
 131    * If the @a key is located in the CMAP_TYPE object, the CACHING_STRATEGY is
 132    * notified of it via notify_find (int result, ATTRIBUTES &attribute).
 133    * If notify_find also returns 0 (success), then this function returns
 134    * 0 (success).
 135    */
 136   int find (const KEY &key);
 137
 138   /**
 139    * Reassociate the @a key with @a value. If the @a key already exists
 140    * in the cache then returns 1, on a new bind returns 0 and returns
 141    * -1 in case of any failures.
 142    */
 143   int rebind (const KEY &key,
 144               const VALUE &value);
 145
 146   /**
 147    * Reassociate @a key with @a value, storing the old value into the
 148    * "out" parameter @a old_value.  The function fails if @a key is not
 149    * in the cache for caches that do not allow user specified keys.
 150    * However, for caches that allow user specified keys, if the key is
 151    * not in the cache, a new @a key / @a value association is created.
 152    */
 153   int rebind (const KEY &key,
 154               const VALUE &value,
 155               VALUE &old_value);
 156
 157   /**
 158    * Reassociate @a key with @a value, storing the old key and value
 159    * into the "out" parameters @a old_key and @a old_value.  The
 160    * function fails if @a key is not in the cache for caches that do
 161    * not allow user specified keys.  However, for caches that allow
 162    * user specified keys, if the key is not in the cache, a new
 163    * @a key / @a value association is created.
 164    */
 165   int rebind (const KEY &key,
 166               const VALUE &value,
 167               KEY &old_key,
 168               VALUE &old_value);
 169
 170   /**
 171    * Associate @a key with @a value if and only if @a key is not in the
 172    * cache.  If @a key is already in the cache, then the @a value
 173    * parameter is overwritten with the existing value in the
 174    * cache. Returns 0 if a new @a key / @a value association is created.
 175    * Returns 1 if an attempt is made to bind an existing entry.  This
 176    * function fails for maps that do not allow user specified keys.
 177    */
 178   int trybind (const KEY &key,
 179                VALUE &value);
 180
 181   /// Remove @a key from the cache.
 182   int unbind (const KEY &key);
 183
 184   /// Remove @a key from the cache, and return the @a value associated with
 185   /// @a key.
 186   int unbind (const KEY &key,
 187               VALUE &value);
 188
 189   /// Remove entries from the cache depending upon the strategy.
 190   int purge ();
 191
 192   /// Return the current size of the cache.
 193   size_t current_size () const;
 194
 195   /// Return the total size of the cache.
 196   size_t total_size () const;
 197
 198   /// Dumps the state of the object.
 199   void dump () const;
 200
 201   // = STL styled iterator factory functions.
 202
 203   /// Return forward iterator.
 204   ITERATOR begin ();
 205   ITERATOR end ();
 206
 207   /// Return reverse iterator.
 208   REVERSE_ITERATOR rbegin ();
 209   REVERSE_ITERATOR rend ();
 210
 211   /// The map managed by the Cache_Map_Manager.
 212   CMAP_TYPE &map ();
 213
 214   /// The caching strategy used on the cache.
 215   CACHING_STRATEGY &caching_strategy ();
 216
 217   /// Declare the dynamic allocation hooks.
 218   ACE_ALLOC_HOOK_DECLARE;
 219
 220 protected:
 221   /// The underlying map which needs to be cached.
 222   CMAP_TYPE map_;
 223
 224   /// The strategy to be followed for caching entries in the map.
 225   CACHING_STRATEGY &caching_strategy_;
 226
 227 private:
 228   // = Disallow these operations.
 229   void operator= (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &) = delete;
 230   ACE_Cache_Map_Manager (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &) = delete;
 231 };
 232
 233 /**
 234  * @class ACE_Cache_Map_Iterator
 235  *
 236  * @brief Defines a iterator for the Cache_Map_Manager.
 237  *
 238  * Implementation to be provided by the iterator of the map
 239  * managed by the ACE_Cache_Map_Manager.
 240  */
 241 template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
 242 class ACE_Cache_Map_Iterator
 243 {
 244 public:
 245   // = Traits.
 246   /// The actual value mapped to the key in the cache. The <attributes>
 247   /// are used by the strategy and is transparent to the cache user.
 248   typedef ACE_Reference_Pair<KEY, VALUE>
 249           value_type;
 250   typedef std::pair <VALUE, ATTRIBUTES>
 251           CACHE_VALUE;
 252
 253   // = Initialisation and termination methods.
 254
 255   ACE_Cache_Map_Iterator (const IMPLEMENTATION &iterator_impl);
 256
 257   /// Copy constructor.
 258   ACE_Cache_Map_Iterator (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
 259
 260   virtual ~ACE_Cache_Map_Iterator () = default;
 261
 262   // = Iteration methods.
 263
 264   /// assignment operator.
 265   ACE_Cache_Map_Iterator <KEY, VALUE, IMPLEMENTATION,
 266                           CACHING_STRATEGY, ATTRIBUTES> &operator=
 267       (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION,
 268                                     CACHING_STRATEGY, ATTRIBUTES> &rhs);
 269
 270   /// Comparison operators.
 271   bool operator== (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 272   bool operator!= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 273
 274   /// Returns a reference to the internal element @c this is pointing
 275   /// to.
 276   ACE_Reference_Pair<KEY, VALUE> operator* () const;
 277
 278   // = STL styled iteration, compare, and reference functions.
 279
 280   /// Prefix advance
 281   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ ();
 282
 283   /// Postfix advance.
 284   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
 285
 286   /// Prefix reverse.
 287   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- ();
 288
 289   /// Postfix reverse.
 290   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
 291
 292   /// Returns the iterator of the internal map in the custody of the
 293   /// Cache_Map_Manager.
 294   IMPLEMENTATION &iterator_implementation ();
 295
 296   /// Dump the state of an object.
 297   void dump () const;
 298
 299   /// Declare the dynamic allocation hooks.
 300   ACE_ALLOC_HOOK_DECLARE;
 301
 302 protected:
 303   /// The actual iterator which iterates internally on the map
 304   /// belonging to the Cache_Map_Manager.
 305   IMPLEMENTATION iterator_implementation_;
 306 };
 307
 308 /**
 309  * @class ACE_Cache_Map_Reverse_Iterator
 310  *
 311  * @brief Defines a reverse iterator for the Cache_Map_Manager.
 312  *
 313  * Implementation to be provided by the reverse iterator of the map
 314  * managed by thr Cache_Map_manager.
 315  */
 316 template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
 317 class ACE_Cache_Map_Reverse_Iterator
 318 {
 319 public:
 320   // = Traits.
 321   /// The actual value mapped to the key in the cache. The <attributes>
 322   /// are used by the strategy and is transparent to the cache user.
 323   typedef ACE_Reference_Pair<KEY, VALUE> value_type;
 324   typedef std::pair <VALUE, ATTRIBUTES> CACHE_VALUE;
 325
 326   // = Initialisation and termination methods.
 327
 328   ACE_Cache_Map_Reverse_Iterator (const REVERSE_IMPLEMENTATION &iterator_impl);
 329
 330   /// Copy constructor.
 331   ACE_Cache_Map_Reverse_Iterator (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
 332
 333   ~ACE_Cache_Map_Reverse_Iterator () = default;
 334
 335   // = Iteration methods.
 336
 337   /// Assignment operator.
 338   ACE_Cache_Map_Reverse_Iterator <KEY, VALUE, REVERSE_IMPLEMENTATION,
 339                                   CACHING_STRATEGY, ATTRIBUTES> &operator=
 340      (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION,
 341                                            CACHING_STRATEGY, ATTRIBUTES> &rhs);
 342
 343   /// Comparison operators.
 344   bool operator== (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 345   bool operator!= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 346
 347   /// Returns a reference to the internal element @c this is pointing
 348   /// to.
 349   ACE_Reference_Pair<KEY, VALUE> operator* () const;
 350
 351   // = STL styled iteration, compare, and reference functions.
 352
 353   /// Prefix advance
 354   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ ();
 355
 356   /// Postfix advance.
 357   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
 358
 359   /// Prefix reverse.
 360   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- ();
 361
 362   /// Postfix reverse.
 363   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
 364
 365   /// Returns the iterator of the internal map in the custody of the
 366   /// Cache_Map_Manager.
 367   REVERSE_IMPLEMENTATION &iterator_implementation ();
 368
 369   /// Dump the state of an object.
 370   void dump () const;
 371
 372   /// Declare the dynamic allocation hooks.
 373   ACE_ALLOC_HOOK_DECLARE;
 374
 375 protected:
 376   /// The actual iterator which iterates internally on the map
 377   /// belonging to the Cache_Map_Manager.
 378   REVERSE_IMPLEMENTATION reverse_iterator_implementation_;
 379 };
 380
 381 ACE_END_VERSIONED_NAMESPACE_DECL
 382
 383 #if defined (__ACE_INLINE__)
 384 #include "ace/Cache_Map_Manager_T.inl"
 385 #endif /* __ACE_INLINE__ */
 386
 387 #include "ace/Cache_Map_Manager_T.cpp"
 388
 389 #include /**/ "ace/post.h"
 390
 391 #endif /* ACE_CACHE_MAP_MANAGER_T_H */