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    * The actual value mapped to the key in the map. The <attributes>
  65    * are used by the strategy and is transparent to the user of this
  66    * class.
  67    */
  68   typedef std::pair<VALUE, ATTRIBUTES> CACHE_VALUE;
  69   typedef ACE_Hash_Map_Manager_Ex<KEY, CACHE_VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> HASH_MAP;
  70   typedef ACE_Hash_Map_Entry<KEY, CACHE_VALUE> CACHE_ENTRY;
  71   typedef KEY key_type;
  72   typedef VALUE mapped_type;
  73
  74   /// Initialize a <Hash_Cache_Map_Manager> with @a size entries.
  75   ACE_Hash_Cache_Map_Manager (CACHING_STRATEGY &caching_s,
  76                               size_t size = ACE_DEFAULT_MAP_SIZE,
  77                               ACE_Allocator *alloc = nullptr);
  78
  79   /// Close down a <Cache_Map_Manager> and release dynamically allocated
  80   /// resources.
  81   ~ACE_Hash_Cache_Map_Manager () = default;
  82
  83   /**
  84    * Associate @a key with @a value.  If @a key is already in the
  85    * MAP then the ENTRY is not changed.  Returns 0 if a new entry is
  86    * bound successfully, returns 1 if an attempt is made to bind an
  87    * existing entry, and returns -1 if failures occur.
  88    */
  89   int bind (const KEY &key,
  90             const VALUE &value);
  91
  92   /**
  93    * Same as a normal bind, except the cache entry is also passed back
  94    * to the caller.  The entry in this case will either be the newly
  95    * created entry, or the existing one.
  96    */
  97   int bind (const KEY &key,
  98             const VALUE &value,
  99             CACHE_ENTRY *&entry);
 100
 101   /// Loopkup entry<key,value> in the cache.
 102   int find (const KEY &key,
 103             VALUE &value);
 104
 105   /// Is @a key in the cache?
 106   int find (const KEY &key);
 107
 108   /// Obtain the entry when the find succeeds.
 109   int find (const KEY &key,
 110             CACHE_ENTRY *&entry);
 111
 112   /**
 113    * Reassociate the @a key with @a value. If the @a key already exists
 114    * in the cache then returns 1, on a new bind returns 0 and returns
 115    * -1 in case of any failures.
 116    */
 117   int rebind (const KEY &key,
 118               const VALUE &value);
 119
 120   /**
 121    * Reassociate @a key with @a value, storing the old value into the
 122    * "out" parameter @a old_value.  The function fails if @a key is not
 123    * in the cache for caches that do not allow user specified keys.
 124    * However, for caches that allow user specified keys, if the key is
 125    * not in the cache, a new @a key / @a value association is created.
 126    */
 127   int rebind (const KEY &key,
 128               const VALUE &value,
 129               VALUE &old_value);
 130
 131   /**
 132    * Reassociate @a key with @a value, storing the old key and value
 133    * into the "out" parameters @a old_key and @a old_value.  The
 134    * function fails if @a key is not in the cache for caches that do not
 135    * allow user specified keys.  However, for caches that allow user
 136    * specified keys, if the key is not in the cache, a new @a key / @a value
 137    * association is created.
 138    */
 139   int rebind (const KEY &key,
 140               const VALUE &value,
 141               KEY &old_key,
 142               VALUE &old_value);
 143
 144   /**
 145    * Same as a normal rebind, except the cache entry is also passed back
 146    * to the caller.  The entry in this case will either be the newly
 147    * created entry, or the existing one.
 148    */
 149   int rebind (const KEY &key,
 150               const VALUE &value,
 151               CACHE_ENTRY *&entry);
 152
 153   /**
 154    * Associate @a key with @a value if and only if @a key is not in the
 155    * cache.  If @a key is already in the cache, then the @a value parameter
 156    * is overwritten with the existing value in the cache. Returns 0 if a
 157    * new @a key / @a value association is created.  Returns 1 if an
 158    * attempt is made to bind an existing entry.  This function fails
 159    * for maps that do not allow user specified keys.
 160    */
 161   int trybind (const KEY &key,
 162                VALUE &value);
 163
 164   /**
 165    * Same as a normal trybind, except the cache entry is also passed
 166    * back to the caller.  The entry in this case will either be the
 167    * newly created entry, or the existing one.
 168    */
 169   int trybind (const KEY &key,
 170                VALUE &value,
 171                CACHE_ENTRY *&entry);
 172
 173   /// Remove @a key from the cache.
 174   int unbind (const KEY &key);
 175
 176   /// Remove @a key from the cache, and return the @a value associated with
 177   /// @a key.
 178   int unbind (const KEY &key,
 179               VALUE &value);
 180
 181   /// Remove entry from map.
 182   int unbind (CACHE_ENTRY *entry);
 183
 184   /// Declare the dynamic allocation hooks.
 185   ACE_ALLOC_HOOK_DECLARE;
 186
 187 protected:
 188   /// Base class.
 189   typedef ACE_CACHE_MAP_MANAGER ACE_HCMM_BASE;
 190 };
 191
 192 ACE_END_VERSIONED_NAMESPACE_DECL
 193
 194
 195 #if defined (__ACE_INLINE__)
 196 #include "ace/Hash_Cache_Map_Manager_T.inl"
 197 #endif /* __ACE_INLINE__ */
 198
 199 #include "ace/Hash_Cache_Map_Manager_T.cpp"
 200
 201 #include /**/ "ace/post.h"
 202
 203 #endif /* HASH_CACHE_MAP_MANAGER_T_H */