dep/ACE_wrappers/ace/Cache_Map_Manager_T.h

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