ACE/ace/Hash_Cache_Map_Manager_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Hash_Cache_Map_Manager_T.h
   6  *
   7  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11
  12 #ifndef HASH_CACHE_MAP_MANAGER_T_H
  13 #define HASH_CACHE_MAP_MANAGER_T_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/Hash_Map_Manager_T.h"
  18 #include "ace/Cache_Map_Manager_T.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 #pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/Null_Mutex.h"
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 // Forward declaration.
  29 class ACE_Allocator;
  30
  31 #define ACE_CACHE_MAP_MANAGER \
  32         ACE_Cache_Map_Manager<KEY, \
  33                               VALUE, \
  34                               ACE_Hash_Map_Manager_Ex<KEY, std::pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
  35                               ACE_Hash_Map_Iterator_Ex<KEY, std::pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
  36                               ACE_Hash_Map_Reverse_Iterator_Ex<KEY, std::pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
  37                               CACHING_STRATEGY, \
  38                               ATTRIBUTES>
  39
  40  /**
  41   * @class ACE_Hash_Cache_Map_Manager
  42   *
  43   * @brief Defines a abstraction which will purge entries from a map.
  44   * The map considered is the ACE_Hash_Map_Manager_Ex.
  45   *
  46   * The Hash_Cache_Map_Manager will manage the map it contains
  47   * and provide purging on demand from the map. The strategy for
  48   * caching is decided by the user and provided to the Cache
  49   * Manager.  The Cache Manager acts as a agent and communicates
  50   * between the Map and the Strategy for purging entries from the
  51   * map.  To tap the optimal methods like find(key,value,entry)
  52   * present in the ACE_Hash_Map_Manager,
  53   * Hash_Cache_Map_Manager provides extra functionality on top
  54   * of the Cache_Map_Manager.
  55   * No locking mechanism provided since locking at this level
  56   * isn't efficient.  Locking has to be provided by the
  57   * application.
  58   */
  59 template <class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS, class CACHING_STRATEGY, class ATTRIBUTES>
  60 class ACE_Hash_Cache_Map_Manager : public ACE_CACHE_MAP_MANAGER
  61 {
  62  public:
  63
  64   /**
  65    * The actual value mapped to the key in the map. The <attributes>
  66    * are used by the strategy and is transparent to the user of this
  67    * class.
  68    */
  69   typedef std::pair<VALUE, ATTRIBUTES> CACHE_VALUE;
  70   typedef ACE_Hash_Map_Manager_Ex<KEY, CACHE_VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> HASH_MAP;
  71   typedef ACE_Hash_Map_Entry<KEY, CACHE_VALUE> CACHE_ENTRY;
  72   typedef KEY key_type;
  73   typedef VALUE mapped_type;
  74
  75   /// Initialize a <Hash_Cache_Map_Manager> with @a size entries.
  76   ACE_Hash_Cache_Map_Manager (CACHING_STRATEGY &caching_s,
  77                               size_t size = ACE_DEFAULT_MAP_SIZE,
  78                               ACE_Allocator *alloc = 0);
  79
  80   /// Close down a <Cache_Map_Manager> and release dynamically allocated
  81   /// resources.
  82   ~ACE_Hash_Cache_Map_Manager (void);
  83
  84   /**
  85    * Associate @a key with @a value.  If @a key is already in the
  86    * MAP then the ENTRY is not changed.  Returns 0 if a new entry is
  87    * bound successfully, returns 1 if an attempt is made to bind an
  88    * existing entry, and returns -1 if failures occur.
  89    */
  90   int bind (const KEY &key,
  91             const VALUE &value);
  92
  93   /**
  94    * Same as a normal bind, except the cache entry is also passed back
  95    * to the caller.  The entry in this case will either be the newly
  96    * created entry, or the existing one.
  97    */
  98   int bind (const KEY &key,
  99             const VALUE &value,
 100             CACHE_ENTRY *&entry);
 101
 102   /// Loopkup entry<key,value> in the cache.
 103   int find (const KEY &key,
 104             VALUE &value);
 105
 106   /// Is @a key in the cache?
 107   int find (const KEY &key);
 108
 109   /// Obtain the entry when the find succeeds.
 110   int find (const KEY &key,
 111             CACHE_ENTRY *&entry);
 112
 113   /**
 114    * Reassociate the @a key with @a value. If the @a key already exists
 115    * in the cache then returns 1, on a new bind returns 0 and returns
 116    * -1 in case of any failures.
 117    */
 118   int rebind (const KEY &key,
 119               const VALUE &value);
 120
 121   /**
 122    * Reassociate @a key with @a value, storing the old value into the
 123    * "out" parameter @a old_value.  The function fails if @a key is not
 124    * in the cache for caches that do not allow user specified keys.
 125    * However, for caches that allow user specified keys, if the key is
 126    * not in the cache, a new @a key / @a value association is created.
 127    */
 128   int rebind (const KEY &key,
 129               const VALUE &value,
 130               VALUE &old_value);
 131
 132   /**
 133    * Reassociate @a key with @a value, storing the old key and value
 134    * into the "out" parameters @a old_key and @a old_value.  The
 135    * function fails if @a key is not in the cache for caches that do not
 136    * allow user specified keys.  However, for caches that allow user
 137    * specified keys, if the key is not in the cache, a new @a key / @a value
 138    * association is created.
 139    */
 140   int rebind (const KEY &key,
 141               const VALUE &value,
 142               KEY &old_key,
 143               VALUE &old_value);
 144
 145   /**
 146    * Same as a normal rebind, except the cache entry is also passed back
 147    * to the caller.  The entry in this case will either be the newly
 148    * created entry, or the existing one.
 149    */
 150   int rebind (const KEY &key,
 151               const VALUE &value,
 152               CACHE_ENTRY *&entry);
 153
 154   /**
 155    * Associate @a key with @a value if and only if @a key is not in the
 156    * cache.  If @a key is already in the cache, then the @a value parameter
 157    * is overwritten with the existing value in the cache. Returns 0 if a
 158    * new @a key / @a value association is created.  Returns 1 if an
 159    * attempt is made to bind an existing entry.  This function fails
 160    * for maps that do not allow user specified keys.
 161    */
 162   int trybind (const KEY &key,
 163                VALUE &value);
 164
 165   /**
 166    * Same as a normal trybind, except the cache entry is also passed
 167    * back to the caller.  The entry in this case will either be the
 168    * newly created entry, or the existing one.
 169    */
 170   int trybind (const KEY &key,
 171                VALUE &value,
 172                CACHE_ENTRY *&entry);
 173
 174   /// Remove @a key from the cache.
 175   int unbind (const KEY &key);
 176
 177   /// Remove @a key from the cache, and return the @a value associated with
 178   /// @a key.
 179   int unbind (const KEY &key,
 180               VALUE &value);
 181
 182   /// Remove entry from map.
 183   int unbind (CACHE_ENTRY *entry);
 184
 185   /// Declare the dynamic allocation hooks.
 186   ACE_ALLOC_HOOK_DECLARE;
 187
 188 protected:
 189   /// Base class.
 190   typedef ACE_CACHE_MAP_MANAGER ACE_HCMM_BASE;
 191 };
 192
 193 ACE_END_VERSIONED_NAMESPACE_DECL
 194
 195
 196 #if defined (__ACE_INLINE__)
 197 #include "ace/Hash_Cache_Map_Manager_T.inl"
 198 #endif /* __ACE_INLINE__ */
 199
 200 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 201 #include "ace/Hash_Cache_Map_Manager_T.cpp"
 202 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 203
 204 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 205 #pragma implementation ("Hash_Cache_Map_Manager_T.cpp")
 206 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 207
 208 #include /**/ "ace/post.h"
 209
 210 #endif /* HASH_CACHE_MAP_MANAGER_T_H */