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 = 0);
  98
  99   /// Close down a <Cache_Map_Manager> and release dynamically allocated
 100   /// resources.
 101   virtual ~ACE_Cache_Map_Manager (void);
 102
 103   /// Initialize a cache with size @a length.
 104   int open (size_t length = ACE_DEFAULT_MAP_SIZE,
 105             ACE_Allocator *alloc = 0);
 106
 107   /// Close down a cache and release dynamically allocated resources.
 108   int close (void);
 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 (void);
 191
 192   /// Return the current size of the cache.
 193   size_t current_size (void) const;
 194
 195   /// Return the total size of the cache.
 196   size_t total_size (void) const;
 197
 198   /// Dumps the state of the object.
 199   void dump (void) const;
 200
 201   // = STL styled iterator factory functions.
 202
 203   /// Return forward iterator.
 204   ITERATOR begin (void);
 205   ITERATOR end (void);
 206
 207   /// Return reverse iterator.
 208   REVERSE_ITERATOR rbegin (void);
 209   REVERSE_ITERATOR rend (void);
 210
 211   /// The map managed by the Cache_Map_Manager.
 212   CMAP_TYPE &map (void);
 213
 214   /// The caching strategy used on the cache.
 215   CACHING_STRATEGY &caching_strategy (void);
 216
 217   /// Declare the dynamic allocation hooks.
 218   ACE_ALLOC_HOOK_DECLARE;
 219
 220 protected:
 221
 222   /// The underlying map which needs to be cached.
 223   CMAP_TYPE map_;
 224
 225   /// The strategy to be followed for caching entries in the map.
 226   CACHING_STRATEGY &caching_strategy_;
 227
 228 private:
 229   // = Disallow these operations.
 230   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &))
 231   ACE_UNIMPLEMENTED_FUNC (ACE_Cache_Map_Manager (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &))
 232 };
 233
 234 /**
 235  * @class ACE_Cache_Map_Iterator
 236  *
 237  * @brief Defines a iterator for the Cache_Map_Manager.
 238  *
 239  * Implementation to be provided by the iterator of the map
 240  * managed by the ACE_Cache_Map_Manager.
 241  */
 242 template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
 243 class ACE_Cache_Map_Iterator
 244 {
 245 public:
 246   // = Traits.
 247   /// The actual value mapped to the key in the cache. The <attributes>
 248   /// are used by the strategy and is transparent to the cache user.
 249   typedef ACE_Reference_Pair<KEY, VALUE>
 250           value_type;
 251   typedef std::pair <VALUE, ATTRIBUTES>
 252           CACHE_VALUE;
 253
 254   // = Initialisation and termination methods.
 255
 256   ACE_Cache_Map_Iterator (const IMPLEMENTATION &iterator_impl);
 257
 258   /// Copy constructor.
 259   ACE_Cache_Map_Iterator (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
 260
 261   virtual ~ACE_Cache_Map_Iterator (void);
 262
 263   // = Iteration methods.
 264
 265   /// assignment operator.
 266   ACE_Cache_Map_Iterator <KEY, VALUE, IMPLEMENTATION,
 267                           CACHING_STRATEGY, ATTRIBUTES> &operator=
 268       (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION,
 269                                     CACHING_STRATEGY, ATTRIBUTES> &rhs);
 270
 271   /// Comparison operators.
 272   bool operator== (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 273   bool operator!= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 274
 275   /// Returns a reference to the internal element @c this is pointing
 276   /// to.
 277   ACE_Reference_Pair<KEY, VALUE> operator* (void) const;
 278
 279   // = STL styled iteration, compare, and reference functions.
 280
 281   /// Prefix advance
 282   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);
 283
 284   /// Postfix advance.
 285   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
 286
 287   /// Prefix reverse.
 288   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);
 289
 290   /// Postfix reverse.
 291   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
 292
 293   /// Returns the iterator of the internal map in the custody of the
 294   /// Cache_Map_Manager.
 295   IMPLEMENTATION &iterator_implementation (void);
 296
 297   /// Dump the state of an object.
 298   void dump (void) const;
 299
 300   /// Declare the dynamic allocation hooks.
 301   ACE_ALLOC_HOOK_DECLARE;
 302
 303 protected:
 304   /// The actual iterator which iterates internally on the map
 305   /// belonging to the Cache_Map_Manager.
 306   IMPLEMENTATION iterator_implementation_;
 307 };
 308
 309 /**
 310  * @class ACE_Cache_Map_Reverse_Iterator
 311  *
 312  * @brief Defines a reverse iterator for the Cache_Map_Manager.
 313  *
 314  * Implementation to be provided by the reverse iterator of the map
 315  * managed by thr Cache_Map_manager.
 316  */
 317 template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
 318 class ACE_Cache_Map_Reverse_Iterator
 319 {
 320 public:
 321   // = Traits.
 322   /// The actual value mapped to the key in the cache. The <attributes>
 323   /// are used by the strategy and is transparent to the cache user.
 324   typedef ACE_Reference_Pair<KEY, VALUE> value_type;
 325   typedef std::pair <VALUE, ATTRIBUTES> CACHE_VALUE;
 326
 327   // = Initialisation and termination methods.
 328
 329   ACE_Cache_Map_Reverse_Iterator (const REVERSE_IMPLEMENTATION &iterator_impl);
 330
 331   /// Copy constructor.
 332   ACE_Cache_Map_Reverse_Iterator (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
 333
 334   ~ACE_Cache_Map_Reverse_Iterator (void);
 335
 336   // = Iteration methods.
 337
 338   /// Assignment operator.
 339   ACE_Cache_Map_Reverse_Iterator <KEY, VALUE, REVERSE_IMPLEMENTATION,
 340                                   CACHING_STRATEGY, ATTRIBUTES> &operator=
 341      (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION,
 342                                            CACHING_STRATEGY, ATTRIBUTES> &rhs);
 343
 344   /// Comparison operators.
 345   bool operator== (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 346   bool operator!= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
 347
 348   /// Returns a reference to the internal element @c this is pointing
 349   /// to.
 350   ACE_Reference_Pair<KEY, VALUE> operator* (void) const;
 351
 352   // = STL styled iteration, compare, and reference functions.
 353
 354   /// Prefix advance
 355   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);
 356
 357   /// Postfix advance.
 358   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
 359
 360   /// Prefix reverse.
 361   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);
 362
 363   /// Postfix reverse.
 364   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
 365
 366   /// Returns the iterator of the internal map in the custody of the
 367   /// Cache_Map_Manager.
 368   REVERSE_IMPLEMENTATION &iterator_implementation (void);
 369
 370   /// Dump the state of an object.
 371   void dump (void) const;
 372
 373   /// Declare the dynamic allocation hooks.
 374   ACE_ALLOC_HOOK_DECLARE;
 375
 376 protected:
 377   /// The actual iterator which iterates internally on the map
 378   /// belonging to the Cache_Map_Manager.
 379   REVERSE_IMPLEMENTATION reverse_iterator_implementation_;
 380 };
 381
 382 ACE_END_VERSIONED_NAMESPACE_DECL
 383
 384 #if defined (__ACE_INLINE__)
 385 #include "ace/Cache_Map_Manager_T.inl"
 386 #endif /* __ACE_INLINE__ */
 387
 388 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 389 #include "ace/Cache_Map_Manager_T.cpp"
 390 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 391
 392 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 393 #pragma implementation ("Cache_Map_Manager_T.cpp")
 394 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 395
 396 #include /**/ "ace/post.h"
 397
 398 #endif /* ACE_CACHE_MAP_MANAGER_T_H */