Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Cache_Map_Manager_T.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Cache_Map_Manager_T.h
00006  *
00007  *  $Id: Cache_Map_Manager_T.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_CACHE_MAP_MANAGER_T_H
00014 #define ACE_CACHE_MAP_MANAGER_T_H
00015 
00016 #include "ace/pre.h"
00017 
00018 #include "ace/config-all.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 #include "ace/Default_Constants.h"
00025 #include "ace/Global_Macros.h"
00026 #include "ace/Pair_T.h"
00027 
00028 // Forward declaration.
00029 class ACE_Allocator;
00030 
00031 #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES)
00032 
00033 #define ACE_Cache_Map_Iterator ACMI
00034 #define ACE_Cache_Map_Reverse_Iterator ACMRI
00035 
00036 template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
00037 class ACE_Cache_Map_Iterator;
00038 
00039 template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
00040 class ACE_Cache_Map_Reverse_Iterator;
00041 
00042 #define ACE_T1 class KEY, class VALUE, class MAP, class ITERATOR_IMPL, class REVERSE_ITERATOR_IMPL, class CACHING_STRATEGY, class ATTRIBUTES
00043 #define ACE_T2 KEY, VALUE, MAP, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES
00044 
00045 #else
00046 
00047 #define ACE_T1 class KEY, class VALUE, class MAP, class CACHING_STRATEGY, class ATTRIBUTES
00048 #define ACE_T2 KEY, VALUE, MAP, CACHING_STRATEGY, ATTRIBUTES
00049 
00050 #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */
00051 
00052 // For linkers that cant grok long names.
00053 #define ACE_Cache_Map_Manager ACMM
00054 
00055 /**
00056  * @class ACE_Cache_Map_Manager
00057  *
00058  * @brief Defines a abstraction that will purge entries from a map.
00059  *
00060  * The <ACE_Cache_Map_Manager> will manage the map it contains
00061  * and provide purging on demand from the map. The strategy for
00062  * caching is decided by the user and provided to the Cache
00063  * Manager.  The Cache Manager acts as a agent and communicates
00064  * between the Map and the Strategy for purging entries from the
00065  * map.
00066  * No locking mechanism provided since locking at this level
00067  * isn't efficient.  Locking has to be provided by the
00068  * application.
00069  */
00070 template <ACE_T1>
00071 class ACE_Cache_Map_Manager
00072 {
00073 public:
00074 
00075   // = Traits.
00076   typedef KEY key_type;
00077   typedef VALUE mapped_type;
00078   typedef MAP map_type;
00079   typedef CACHING_STRATEGY caching_strategy_type;
00080 
00081 #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES)
00082 
00083   typedef ITERATOR_IMPL ITERATOR_IMPLEMENTATION;
00084   typedef REVERSE_ITERATOR_IMPL REVERSE_ITERATOR_IMPLEMENTATION;
00085 
00086   friend class ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;
00087   friend class ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;
00088 
00089   // = ACE-style iterator typedefs.
00090   typedef ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
00091           ITERATOR;
00092   typedef ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
00093           REVERSE_ITERATOR;
00094 
00095    // = STL-style iterator typedefs.
00096   typedef ITERATOR
00097           iterator;
00098   typedef REVERSE_ITERATOR
00099           reverse_iterator;
00100 
00101 #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */
00102 
00103   /**
00104    * The actual value mapped to the key in the map. The <attributes>
00105    * are used by the strategy and is transparent to the user of this
00106    * class.
00107    */
00108   typedef ACE_Pair<VALUE, ATTRIBUTES> CACHE_VALUE;
00109 
00110   // = Initialization and termination methods.
00111 
00112   /// Initialize a <Cache_Map_Manager> with <caching_strategy> and
00113   /// <size> entries.
00114   ACE_Cache_Map_Manager (CACHING_STRATEGY &caching_strategy,
00115                          size_t size = ACE_DEFAULT_MAP_SIZE,
00116                          ACE_Allocator *alloc = 0);
00117 
00118   /// Close down a <Cache_Map_Manager> and release dynamically allocated
00119   /// resources.
00120   virtual ~ACE_Cache_Map_Manager (void);
00121 
00122   /// Initialize a cache with size <length>.
00123   int open (size_t length = ACE_DEFAULT_MAP_SIZE,
00124             ACE_Allocator *alloc = 0);
00125 
00126   /// Close down a cache and release dynamically allocated resources.
00127   int close (void);
00128 
00129   /**
00130    * Associate <key> with <value>.  If <key> is already in the MAP
00131    * then the ENTRY is not changed.  Returns 0 if a new entry is bound
00132    * successfully, returns 1 if an attempt is made to bind an existing
00133    * entry, and returns -1 if failures occur.
00134    */
00135   int bind (const KEY &key,
00136             const VALUE &value);
00137 
00138   /**
00139    * Lookup entry<key,value> in the cache. If it is not found, returns -1.
00140    * If the <key> is located in the MAP object, the CACHING_STRATEGY is
00141    * notified of it via notify_find (int result, ATTRIBUTES &attribute).
00142    * If notify_find also returns 0 (success), then this function returns
00143    * 0 (success) and sets the cached value in <value>.
00144    */
00145   int find (const KEY &key,
00146             VALUE &value);
00147 
00148   /**
00149    * Lookup entry<key,value> in the cache. If it is not found, returns -1.
00150    * If the <key> is located in the MAP object, the CACHING_STRATEGY is
00151    * notified of it via notify_find (int result, ATTRIBUTES &attribute).
00152    * If notify_find also returns 0 (success), then this function returns
00153    * 0 (success).
00154    */
00155   int find (const KEY &key);
00156 
00157   /**
00158    * Reassociate the <key> with <value>. If the <key> already exists
00159    * in the cache then returns 1, on a new bind returns 0 and returns
00160    * -1 in case of any failures.
00161    */
00162   int rebind (const KEY &key,
00163               const VALUE &value);
00164 
00165   /**
00166    * Reassociate <key> with <value>, storing the old value into the
00167    * "out" parameter <old_value>.  The function fails if <key> is not
00168    * in the cache for caches that do not allow user specified keys.
00169    * However, for caches that allow user specified keys, if the key is
00170    * not in the cache, a new <key>/<value> association is created.
00171    */
00172   int rebind (const KEY &key,
00173               const VALUE &value,
00174               VALUE &old_value);
00175 
00176   /**
00177    * Reassociate <key> with <value>, storing the old key and value
00178    * into the "out" parameters <old_key> and <old_value>.  The
00179    * function fails if <key> is not in the cache for caches that do
00180    * not allow user specified keys.  However, for caches that allow
00181    * user specified keys, if the key is not in the cache, a new
00182    * <key>/<value> association is created.
00183    */
00184   int rebind (const KEY &key,
00185               const VALUE &value,
00186               KEY &old_key,
00187               VALUE &old_value);
00188 
00189   /**
00190    * Associate <key> with <value> if and only if <key> is not in the
00191    * cache.  If <key> is already in the cache, then the <value>
00192    * parameter is overwritten with the existing value in the
00193    * cache. Returns 0 if a new <key>/<value> association is created.
00194    * Returns 1 if an attempt is made to bind an existing entry.  This
00195    * function fails for maps that do not allow user specified keys.
00196    */
00197   int trybind (const KEY &key,
00198                VALUE &value);
00199 
00200   /// Remove <key> from the cache.
00201   int unbind (const KEY &key);
00202 
00203   /// Remove <key> from the cache, and return the <value> associated with
00204   /// <key>.
00205   int unbind (const KEY &key,
00206               VALUE &value);
00207 
00208   /// Remove entries from the cache depending upon the strategy.
00209   int purge (void);
00210 
00211   /// Return the current size of the cache.
00212   size_t current_size (void) const;
00213 
00214   /// Return the total size of the cache.
00215   size_t total_size (void) const;
00216 
00217   /// Dumps the state of the object.
00218   void dump (void) const;
00219 
00220 #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES)
00221 
00222   // = STL styled iterator factory functions.
00223 
00224   /// Return forward iterator.
00225   ITERATOR begin (void);
00226   ITERATOR end (void);
00227 
00228   /// Return reverse iterator.
00229   REVERSE_ITERATOR rbegin (void);
00230   REVERSE_ITERATOR rend (void);
00231 
00232 #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */
00233 
00234   /// The map managed by the Cache_Map_Manager.
00235   MAP &map (void);
00236 
00237   /// The caching strategy used on the cache.
00238   CACHING_STRATEGY &caching_strategy (void);
00239 
00240 protected:
00241 
00242   /// The underlying map which needs to be cached.
00243   MAP map_;
00244 
00245   /// The strategy to be followed for caching entries in the map.
00246   CACHING_STRATEGY &caching_strategy_;
00247 
00248 private:
00249 
00250   // = Disallow these operations.
00251   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Cache_Map_Manager<ACE_T2> &))
00252   ACE_UNIMPLEMENTED_FUNC (ACE_Cache_Map_Manager (const ACE_Cache_Map_Manager<ACE_T2> &))
00253 
00254 };
00255 
00256 #if !defined (ACE_HAS_BROKEN_EXTENDED_TEMPLATES)
00257 
00258 /**
00259  * @class ACE_Cache_Map_Iterator
00260  *
00261  * @brief Defines a iterator for the Cache_Map_Manager.
00262  *
00263  * Implementation to be provided by the iterator of the map
00264  * managed by the ACE_Cache_Map_Manager.
00265  */
00266 template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
00267 class ACE_Cache_Map_Iterator
00268 {
00269 
00270 public:
00271 
00272   // = Traits.
00273   /// The actual value mapped to the key in the cache. The <attributes>
00274   /// are used by the strategy and is transperant to the cache user.
00275   typedef ACE_Reference_Pair<KEY, VALUE>
00276           value_type;
00277   typedef ACE_Pair <VALUE, ATTRIBUTES>
00278           CACHE_VALUE;
00279 
00280   // = Initialisation and termination methods.
00281 
00282   ACE_Cache_Map_Iterator (const IMPLEMENTATION &iterator_impl);
00283 
00284   /// Copy constructor.
00285   ACE_Cache_Map_Iterator (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
00286 
00287   virtual ~ACE_Cache_Map_Iterator (void);
00288 
00289   // = Iteration methods.
00290 
00291   /// assignment operator.
00292   ACE_Cache_Map_Iterator <KEY, VALUE, IMPLEMENTATION,
00293                           CACHING_STRATEGY, ATTRIBUTES> &operator=
00294       (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION,
00295                                     CACHING_STRATEGY, ATTRIBUTES> &rhs);
00296 
00297   /// Comparision operators.
00298   int operator== (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
00299   int operator!= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
00300 
00301   /// Returns a reference to the internal element <this> is pointing
00302   /// to.
00303   ACE_Reference_Pair<KEY, VALUE> operator* (void) const;
00304 
00305   // = STL styled iteration, compare, and reference functions.
00306 
00307   /// Prefix advance
00308   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);
00309 
00310   /// Postfix advance.
00311   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
00312 
00313   /// Prefix reverse.
00314   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);
00315 
00316   /// Postfix reverse.
00317   ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
00318 
00319   /// Returns the iterator of the internal map in the custody of the
00320   /// Cache_Map_Manager.
00321   IMPLEMENTATION &iterator_implementation (void);
00322 
00323   /// Dump the state of an object.
00324   void dump (void) const;
00325 
00326   /// Declare the dynamic allocation hooks.
00327   ACE_ALLOC_HOOK_DECLARE;
00328 
00329 protected:
00330   /// The actual iterator which iterates internally on the map
00331   /// belonging to the Cache_Map_Manager.
00332   IMPLEMENTATION iterator_implementation_;
00333 };
00334 
00335 /**
00336  * @class ACE_Cache_Map_Reverse_Iterator
00337  *
00338  * @brief Defines a reverse iterator for the Cache_Map_Manager.
00339  *
00340  * Implementation to be provided by the reverse iterator of the map
00341  * managed by thr Cache_Map_manager.
00342  */
00343 template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
00344 class ACE_Cache_Map_Reverse_Iterator
00345 {
00346 public:
00347 
00348   // = Traits.
00349   /// The actual value mapped to the key in the cache. The <attributes>
00350   /// are used by the strategy and is transperant to the cache user.
00351   typedef ACE_Reference_Pair<KEY, VALUE> value_type;
00352   typedef ACE_Pair <VALUE, ATTRIBUTES> CACHE_VALUE;
00353 
00354   // = Initialisation and termination methods.
00355 
00356   ACE_Cache_Map_Reverse_Iterator (const REVERSE_IMPLEMENTATION &iterator_impl);
00357 
00358   /// Copy constructor.
00359   ACE_Cache_Map_Reverse_Iterator (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);
00360 
00361   ~ACE_Cache_Map_Reverse_Iterator (void);
00362 
00363   // = Iteration methods.
00364 
00365   /// Assignment operator.
00366   ACE_Cache_Map_Reverse_Iterator <KEY, VALUE, REVERSE_IMPLEMENTATION,
00367                                   CACHING_STRATEGY, ATTRIBUTES> &operator=
00368      (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION,
00369                                            CACHING_STRATEGY, ATTRIBUTES> &rhs);
00370 
00371   /// Comparision operators.
00372   int operator== (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
00373   int operator!= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
00374 
00375   /// Returns a reference to the internal element <this> is pointing
00376   /// to.
00377   ACE_Reference_Pair<KEY, VALUE> operator* (void) const;
00378 
00379   // = STL styled iteration, compare, and reference functions.
00380 
00381   /// Prefix advance
00382   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);
00383 
00384   /// Postfix advance.
00385   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);
00386 
00387   /// Prefix reverse.
00388   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);
00389 
00390   /// Postfix reverse.
00391   ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);
00392 
00393   /// Returns the iterator of the internal map in the custody of the
00394   /// Cache_Map_Manager.
00395   REVERSE_IMPLEMENTATION &iterator_implementation (void);
00396 
00397   /// Dump the state of an object.
00398   void dump (void) const;
00399 
00400   /// Declare the dynamic allocation hooks.
00401   ACE_ALLOC_HOOK_DECLARE;
00402 
00403 protected:
00404   /// The actual iterator which iterates internally on the map
00405   /// belonging to the Cache_Map_Manager.
00406   REVERSE_IMPLEMENTATION reverse_iterator_implementation_;
00407 };
00408 
00409 #endif /* ACE_HAS_BROKEN_EXTENDED_TEMPLATES */
00410 
00411 #undef ACE_T1
00412 #undef ACE_T2
00413 
00414 #if defined (__ACE_INLINE__)
00415 #include "ace/Cache_Map_Manager_T.i"
00416 #endif /* __ACE_INLINE__ */
00417 
00418 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00419 #include "ace/Cache_Map_Manager_T.cpp"
00420 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00421 
00422 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00423 #pragma implementation ("Cache_Map_Manager_T.cpp")
00424 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00425 
00426 #include "ace/post.h"
00427 
00428 #endif /* ACE_CACHE_MAP_MANAGER_T_H */

Generated on Mon Jun 16 11:19:15 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002