Hash_Cache_Map_Manager_T.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Hash_Cache_Map_Manager_T.h
00006  *
00007  *  Hash_Cache_Map_Manager_T.h,v 4.20 2005/10/28 16:14:52 ossama Exp
00008  *
00009  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 
00014 #ifndef HASH_CACHE_MAP_MANAGER_T_H
00015 #define HASH_CACHE_MAP_MANAGER_T_H
00016 
00017 #include /**/ "ace/pre.h"
00018 
00019 #include "ace/Hash_Map_Manager_T.h"
00020 #include "ace/Cache_Map_Manager_T.h"
00021 
00022 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00023 #pragma once
00024 #endif /* ACE_LACKS_PRAGMA_ONCE */
00025 
00026 #include "ace/Null_Mutex.h"
00027 
00028 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00029 
00030 // Forward declaration.
00031 class ACE_Allocator;
00032 
00033 #define ACE_CACHE_MAP_MANAGER \
00034         ACE_Cache_Map_Manager<KEY, \
00035                               VALUE, \
00036                               ACE_Hash_Map_Manager_Ex<KEY, ACE_Pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
00037                               ACE_Hash_Map_Iterator_Ex<KEY, ACE_Pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
00038                               ACE_Hash_Map_Reverse_Iterator_Ex<KEY, ACE_Pair<VALUE, ATTRIBUTES>, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex>, \
00039                               CACHING_STRATEGY, \
00040                               ATTRIBUTES>
00041 
00042 // For linkers that cant grok long names.
00043 #define ACE_Hash_Cache_Map_Manager AHCMM
00044 
00045  /**
00046   * @class ACE_Hash_Cache_Map_Manager
00047   *
00048   * @brief Defines a abstraction which will purge entries from a map.
00049   * The map considered is the ACE_Hash_Map_Manager_Ex.
00050   *
00051   * The Hash_Cache_Map_Manager will manage the map it contains
00052   * and provide purging on demand from the map. The strategy for
00053   * caching is decided by the user and provided to the Cache
00054   * Manager.  The Cache Manager acts as a agent and communicates
00055   * between the Map and the Strategy for purging entries from the
00056   * map.  To tap the optimal methods like find(key,value,entry)
00057   * present in the ACE_Hash_Map_Manager,
00058   * Hash_Cache_Map_Manager provides extra functionality on top
00059   * of the Cache_Map_Manager.
00060   * No locking mechanism provided since locking at this level
00061   * isnt efficient.  Locking has to be provided by the
00062   * application.
00063   */
00064 template <class KEY, class VALUE, class HASH_KEY, class COMPARE_KEYS, class CACHING_STRATEGY, class ATTRIBUTES>
00065 class ACE_Hash_Cache_Map_Manager : public ACE_CACHE_MAP_MANAGER
00066 {
00067  public:
00068 
00069   /**
00070    * The actual value mapped to the key in the map. The <attributes>
00071    * are used by the strategy and is transparent to the user of this
00072    * class.
00073    */
00074   typedef ACE_Pair<VALUE, ATTRIBUTES> CACHE_VALUE;
00075   typedef ACE_Hash_Map_Manager_Ex<KEY, CACHE_VALUE, HASH_KEY, COMPARE_KEYS, ACE_Null_Mutex> HASH_MAP;
00076   typedef ACE_Hash_Map_Entry<KEY, CACHE_VALUE> CACHE_ENTRY;
00077   typedef KEY key_type;
00078   typedef VALUE mapped_type;
00079 
00080   // = Initialization and termination methods.
00081   /// Initialize a <Hash_Cache_Map_Manager> with <size> entries.
00082   ACE_Hash_Cache_Map_Manager (CACHING_STRATEGY &caching_s,
00083                               size_t size = ACE_DEFAULT_MAP_SIZE,
00084                               ACE_Allocator *alloc = 0);
00085 
00086   /// Close down a <Cache_Map_Manager> and release dynamically allocated
00087   /// resources.
00088   ~ACE_Hash_Cache_Map_Manager (void);
00089 
00090   /**
00091    * Associate <key> with <value>.  If <key> is already in the
00092    * MAP then the ENTRY is not changed.  Returns 0 if a new entry is
00093    * bound successfully, returns 1 if an attempt is made to bind an
00094    * existing entry, and returns -1 if failures occur.
00095    */
00096   int bind (const KEY &key,
00097             const VALUE &value);
00098 
00099   /**
00100    * Same as a normal bind, except the cache entry is also passed back
00101    * to the caller.  The entry in this case will either be the newly
00102    * created entry, or the existing one.
00103    */
00104   int bind (const KEY &key,
00105             const VALUE &value,
00106             CACHE_ENTRY *&entry);
00107 
00108   /// Loopkup entry<key,value> in the cache.
00109   int find (const KEY &key,
00110             VALUE &value);
00111 
00112   /// Is <key> in the cache?
00113   int find (const KEY &key);
00114 
00115   /// Obtain the entry when the find succeeds.
00116   int find (const KEY &key,
00117             CACHE_ENTRY *&entry);
00118 
00119   /**
00120    * Reassociate the <key> with <value>. If the <key> already exists
00121    * in the cache then returns 1, on a new bind returns 0 and returns
00122    * -1 in case of any failures.
00123    */
00124   int rebind (const KEY &key,
00125               const VALUE &value);
00126 
00127   /**
00128    * Reassociate <key> with <value>, storing the old value into the
00129    * "out" parameter <old_value>.  The function fails if <key> is not
00130    * in the cache for caches that do not allow user specified keys.
00131    * However, for caches that allow user specified keys, if the key is
00132    * not in the cache, a new <key>/<value> association is created.
00133    */
00134   int rebind (const KEY &key,
00135               const VALUE &value,
00136               VALUE &old_value);
00137 
00138   /**
00139    * Reassociate <key> with <value>, storing the old key and value
00140    * into the "out" parameters <old_key> and <old_value>.  The
00141    * function fails if <key> is not in the cache for caches that do not
00142    * allow user specified keys.  However, for caches that allow user
00143    * specified keys, if the key is not in the cache, a new <key>/<value>
00144    * association is created.
00145    */
00146   int rebind (const KEY &key,
00147               const VALUE &value,
00148               KEY &old_key,
00149               VALUE &old_value);
00150 
00151   /**
00152    * Same as a normal rebind, except the cache entry is also passed back
00153    * to the caller.  The entry in this case will either be the newly
00154    * created entry, or the existing one.
00155    */
00156   int rebind (const KEY &key,
00157               const VALUE &value,
00158               CACHE_ENTRY *&entry);
00159 
00160   /**
00161    * Associate <key> with <value> if and only if <key> is not in the
00162    * cache.  If <key> is already in the cache, then the <value> parameter
00163    * is overwritten with the existing value in the cache. Returns 0 if a
00164    * new <key>/<value> association is created.  Returns 1 if an
00165    * attempt is made to bind an existing entry.  This function fails
00166    * for maps that do not allow user specified keys.
00167    */
00168   int trybind (const KEY &key,
00169                VALUE &value);
00170 
00171   /**
00172    * Same as a normal trybind, except the cache entry is also passed
00173    * back to the caller.  The entry in this case will either be the
00174    * newly created entry, or the existing one.
00175    */
00176   int trybind (const KEY &key,
00177                VALUE &value,
00178                CACHE_ENTRY *&entry);
00179 
00180   /// Remove <key> from the cache.
00181   int unbind (const KEY &key);
00182 
00183   /// Remove <key> from the cache, and return the <value> associated with
00184   /// <key>.
00185   int unbind (const KEY &key,
00186               VALUE &value);
00187 
00188   /// Remove entry from map.
00189   int unbind (CACHE_ENTRY *entry);
00190 
00191 protected:
00192 
00193   /// Base class.
00194   typedef ACE_CACHE_MAP_MANAGER ACE_HCMM_BASE;
00195 };
00196 
00197 ACE_END_VERSIONED_NAMESPACE_DECL
00198 
00199 
00200 #if defined (__ACE_INLINE__)
00201 #include "ace/Hash_Cache_Map_Manager_T.inl"
00202 #endif /* __ACE_INLINE__ */
00203 
00204 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00205 #include "ace/Hash_Cache_Map_Manager_T.cpp"
00206 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00207 
00208 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00209 #pragma implementation ("Hash_Cache_Map_Manager_T.cpp")
00210 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00211 
00212 #include /**/ "ace/post.h"
00213 
00214 #endif /* HASH_CACHE_MAP_MANAGER_T_H */

Generated on Thu Nov 9 09:41:51 2006 for ACE by doxygen 1.3.6