ACE/ace/Caching_Strategies_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Caching_Strategies_T.h
   6  *
   7  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_CACHING_STRATEGIES_H
  12 #define ACE_CACHING_STRATEGIES_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/config-all.h"
  17 #include "ace/Caching_Utility_T.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #if defined(_MSC_VER)
  24 #pragma warning(disable:4503)
  25 #endif /* _MSC_VER */
  26
  27 // For linkers that cant grok long names.
  28 #define ACE_Caching_Strategy ACS
  29
  30 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  31
  32 /**
  33  * @class ACE_Caching_Strategy
  34  *
  35  * @brief This class is an abstract base class for a caching strategy.
  36  *
  37  * This class consists of all the interfaces a caching strategy should
  38  * have and is used in association with the
  39  * ACE_Caching_Strategy_Adaptor.
  40  */
  41 template <class ATTRIBUTES, class CACHING_UTILITY>
  42 class ACE_Caching_Strategy
  43 {
  44 public:
  45   /// Destructor.
  46   virtual ~ACE_Caching_Strategy ();
  47
  48   /// Accessor method for the timer attributes.
  49   virtual ATTRIBUTES attributes () = 0;
  50
  51   /// Get the percentage of entries to purge.
  52   virtual double purge_percent () = 0;
  53
  54   /// Set the percentage of entries to purge.
  55   virtual void purge_percent (double percentage) = 0;
  56
  57   // = Strategy related Operations
  58
  59   /// This method acts as a notification about the CONTAINERs bind
  60   /// method call.
  61   virtual int notify_bind (int result,
  62                            const ATTRIBUTES &attr) = 0;
  63
  64   /// This method acts as a notification about the CONTAINERs find
  65   /// method call
  66   virtual int notify_find (int result,
  67                            ATTRIBUTES &attr) = 0;
  68
  69   /// This method acts as a notification about the CONTAINERs unbind
  70   /// method call
  71   virtual int notify_unbind (int result,
  72                              const ATTRIBUTES &attr) = 0;
  73
  74   /// This method acts as a notification about the CONTAINERs trybind
  75   /// method call
  76   virtual int notify_trybind (int result,
  77                               ATTRIBUTES &attr) = 0;
  78
  79   /// This method acts as a notification about the CONTAINERs rebind
  80   /// method call
  81   virtual int notify_rebind (int result,
  82                              const ATTRIBUTES &attr) = 0;
  83
  84   /// Purge the cache.
  85   virtual CACHING_UTILITY &caching_utility () = 0;
  86
  87   /// Dumps the state of the object.
  88   virtual void dump () const = 0;
  89 };
  90
  91 //////////////////////////////////////////////////////////////////////////
  92
  93 #define ACE_Caching_Strategy_Adapter ACSA
  94
  95 /**
  96  * @class ACE_Caching_Strategy_Adapter
  97  *
  98  * @brief This class follows the Adaptor pattern and is used to provide
  99  * External Polymorphism by deriving from ACE_Caching_Strategy.
 100  *
 101  * This class simply delegates all requests to the
 102  * IMPLEMNETATION object within. This class should be passed in
 103  * place of the the abstract base ACE_Caching_Strategy class as
 104  * part of the External Polymorphism pattern.
 105  */
 106 template <class ATTRIBUTES, class CACHING_UTILITY, class IMPLEMENTATION>
 107 class ACE_Caching_Strategy_Adapter
 108   : public ACE_Caching_Strategy<ATTRIBUTES, CACHING_UTILITY>
 109 {
 110 public:
 111   /// Constructor.
 112   ACE_Caching_Strategy_Adapter (IMPLEMENTATION *implementation = 0,
 113                                 bool delete_implementation = false);
 114
 115   /// Destructor.
 116   ~ACE_Caching_Strategy_Adapter ();
 117
 118   /// Accessor method for the timer attributes.
 119   ATTRIBUTES attributes ();
 120
 121   /// Get the percentage of entries to purge.
 122   double purge_percent ();
 123
 124   /// Set the percentage of entries to purge.
 125   void purge_percent (double percentage);
 126
 127   // = Strategy related Operations
 128
 129   /// This method acts as a notification about the CONTAINERs bind
 130   /// method call.
 131   int notify_bind (int result,
 132                    const ATTRIBUTES &attr);
 133
 134   /// This method acts as a notification about the CONTAINERs find
 135   /// method call
 136   int notify_find (int result,
 137                    ATTRIBUTES &attr);
 138
 139   /// This method acts as a notification about the CONTAINERs unbind
 140   /// method call
 141   int notify_unbind (int result,
 142                      const ATTRIBUTES &attr);
 143
 144   /// This method acts as a notification about the CONTAINERs trybind
 145   /// method call
 146   int notify_trybind (int result,
 147                       ATTRIBUTES &attr);
 148
 149   /// This method acts as a notification about the CONTAINERs rebind
 150   /// method call
 151   int notify_rebind (int result,
 152                      const ATTRIBUTES &attr);
 153
 154   /// Accessor to the implementation.
 155   IMPLEMENTATION &implementation ();
 156
 157   /// Purge the cache.
 158   CACHING_UTILITY &caching_utility ();
 159
 160   /// Dumps the state of the object.
 161   void dump () const;
 162
 163   /// Declare the dynamic allocation hooks.
 164   ACE_ALLOC_HOOK_DECLARE;
 165
 166 private:
 167   /// Implementation class.
 168   IMPLEMENTATION *implementation_;
 169
 170   /// Do we need to delete the implementation?
 171   bool delete_implementation_;
 172 };
 173
 174 //////////////////////////////////////////////////////////////////////////
 175 #define ACE_LRU_Caching_Strategy ALRU
 176
 177 /**
 178  * @class ACE_LRU_Caching_Strategy
 179  *
 180  * @brief Defines a Least Recently Used strategy which will decide on
 181  * the item to be removed from the cache.
 182  *
 183  * This is a strategy which makes use of a virtual timer which
 184  * is updated whenever an item is inserted or looked up in the
 185  * container. When the need of purging entries arises, the items
 186  * with the lowest timer values are removed.
 187  * Explanation of the template parameter list:
 188  * CONTAINER is any map with entries of type <KEY, VALUE>.
 189  * The ATTRIBUTES are the deciding factor for purging of entries
 190  * and should logically be included with the VALUE. Some ways of
 191  * doing this are: As being a member of the VALUE or VALUE being
 192  * std::pair<x, ATTRIBUTES>. The CACHING_UTILITY is the
 193  * class which can be plugged in and which decides the entries
 194  * to purge.
 195  */
 196 template <class ATTRIBUTES, class CACHING_UTILITY>
 197 class ACE_LRU_Caching_Strategy
 198 {
 199 public:
 200   // Traits.
 201   typedef ATTRIBUTES CACHING_ATTRIBUTES;
 202
 203   // = Initialisation and termination.
 204
 205   /**
 206    * The <container> is the map in which the entries reside.  The
 207    * timer attribute is initialed to zero in this constructor.  And
 208    * the <purge_percent> field denotes the percentage of the entries
 209    * in the cache which can be purged automagically and by default is
 210    * set to 10%.
 211    */
 212   ACE_LRU_Caching_Strategy ();
 213
 214   // = Operations of the strategy.
 215
 216   /// Accessor method for the timer attributes.
 217   ATTRIBUTES attributes ();
 218
 219   /// Get the percentage of entries to purge.
 220   double purge_percent ();
 221
 222   /// Set the percentage of entries to purge.
 223   void purge_percent (double percentage);
 224
 225   // =  Strategy related Operations
 226
 227   /// This method acts as a notification about the CONTAINERs bind
 228   /// method call.
 229   int notify_bind (int result,
 230                    const ATTRIBUTES &attr);
 231
 232   /// This method acts as a notification about the CONTAINERs find
 233   /// method call
 234   int notify_find (int result,
 235                    ATTRIBUTES &attr);
 236
 237   /// This method acts as a notification about the CONTAINERs unbind
 238   /// method call
 239   int notify_unbind (int result,
 240                      const ATTRIBUTES &attr);
 241
 242
 243   /// This method acts as a notification about the CONTAINERs trybind
 244   /// method call
 245   int notify_trybind (int result,
 246                       ATTRIBUTES &attr);
 247
 248   /// This method acts as a notification about the CONTAINERs rebind
 249   /// method call
 250   int notify_rebind (int result,
 251                      const ATTRIBUTES &attr);
 252
 253   /// Purge the cache.
 254   CACHING_UTILITY &caching_utility ();
 255
 256   /// Dumps the state of the object.
 257   void dump () const;
 258
 259   /// Declare the dynamic allocation hooks.
 260   ACE_ALLOC_HOOK_DECLARE;
 261
 262 private:
 263   /// This element is the one which is the deciding factor for purging
 264   /// of an ITEM.
 265   ATTRIBUTES timer_;
 266
 267   /// The level about which the purging will happen automagically.
 268   double purge_percent_;
 269
 270   /// This is the helper class which will decide and expunge entries
 271   /// from the cache.
 272   CACHING_UTILITY caching_utility_;
 273 };
 274
 275 //////////////////////////////////////////////////////////////////////////
 276 #define ACE_LFU_Caching_Strategy ALFU
 277
 278 /**
 279  * @class ACE_LFU_Caching_Strategy
 280  *
 281  * @brief Defines a Least Frequently Used strategy for which will decide on
 282  * the item to be removed from the cache.
 283  *
 284  * A attribute is tagged to each item which increments whenever
 285  * the item is bound or looked up in the cache. Thus it denotes
 286  * the frequency of use. According to the value of the attribute
 287  * the item is removed from the CONTAINER i.e cache.
 288  * Explanation of the template parameter list:
 289  * CONTAINER is any map with entries of type <KEY, VALUE>.
 290  * The ATTRIBUTES are the deciding factor for purging of entries
 291  * and should logically be included with the VALUE. Some ways of
 292  * doing this are: As being a member of the VALUE or VALUE being
 293  * std::pair<x, ATTRIBUTES>. The CACHING_UTILITY is the
 294  * class which can be plugged in and which decides the entries
 295  * to purge.
 296  */
 297 template <class ATTRIBUTES, class CACHING_UTILITY>
 298 class ACE_LFU_Caching_Strategy
 299 {
 300 public:
 301   // Traits.
 302   typedef ATTRIBUTES CACHING_ATTRIBUTES;
 303
 304   // = Initialisation and termination methods.
 305
 306   /**
 307    * The <container> is the map in which the entries reside.  The
 308    * timer attribute is initialed to zero in this constructor.  And
 309    * the <purge_percent> field denotes the percentage of the entries
 310    * in the cache which can be purged automagically and by default is
 311    * set to 10%.
 312    */
 313   ACE_LFU_Caching_Strategy ();
 314
 315   // = Strategy methods.
 316
 317   /// Access the attributes.
 318   ATTRIBUTES attributes ();
 319
 320   /// Get the percentage of entries to purge.
 321   double purge_percent ();
 322
 323   /// Set the percentage of entries to purge.
 324   void purge_percent (double percentage);
 325
 326   // =  Strategy related Operations
 327
 328   /// This method acts as a notification about the CONTAINERs bind
 329   /// method call.
 330   int notify_bind (int result,
 331                    const ATTRIBUTES &attr);
 332
 333   /// Lookup notification.
 334   int notify_find (int result,
 335                    ATTRIBUTES &attr);
 336
 337   /// This method acts as a notification about the CONTAINERs unbind
 338   /// method call
 339   int notify_unbind (int result,
 340                      const ATTRIBUTES &attr);
 341
 342   /// This method acts as a notification about the CONTAINERs trybind
 343   /// method call
 344   int notify_trybind (int result,
 345                       ATTRIBUTES &attr);
 346
 347   /// This method acts as a notification about the CONTAINERs rebind
 348   /// method call
 349   int notify_rebind (int result,
 350                      const ATTRIBUTES &attr);
 351
 352   /// Purge the cache.
 353   CACHING_UTILITY &caching_utility ();
 354
 355   /// Dumps the state of the object.
 356   void dump () const;
 357
 358   /// Declare the dynamic allocation hooks.
 359   ACE_ALLOC_HOOK_DECLARE;
 360
 361 private:
 362   /// The level about which the purging will happen automagically.
 363   double purge_percent_;
 364
 365   /// This is the helper class which will decide and expunge entries
 366   /// from the cache.
 367   CACHING_UTILITY caching_utility_;
 368 };
 369
 370 /////////////////////////////////////////////////////////////
 371 #define ACE_FIFO_Caching_Strategy AFIFO
 372
 373 /**
 374  * @class ACE_FIFO_Caching_Strategy
 375  *
 376  * @brief The First In First Out strategy is implemented wherein each
 377  * item is ordered.
 378  *
 379  * The order tag of each item is used to decide the item to be
 380  * removed from the cache. The items with least order are removed.
 381  * Explanation of the template parameter list:
 382  * CONTAINER is any map with entries of type <KEY, VALUE>.
 383  * The ATTRIBUTES are the deciding factor for purging of entries
 384  * and should logically be included with the VALUE. Some ways of
 385  * doing this are: As being a member of the VALUE or VALUE being
 386  * std::pair<x, ATTRIBUTES>. The CACHING_UTILITY is the
 387  * class which can be plugged in and which decides the entries
 388  * to purge.
 389  */
 390 template<class ATTRIBUTES, class CACHING_UTILITY>
 391 class ACE_FIFO_Caching_Strategy
 392 {
 393 public:
 394   typedef ATTRIBUTES CACHING_ATTRIBUTES;
 395
 396   // = Initialisation and termination.
 397
 398   /**
 399    * The <container> is the map in which the entries reside.  The
 400    * timer attribute is initialed to zero in this constructor.  And
 401    * the <purge_percent> field denotes the percentage of the entries
 402    * in the cache which can be purged automagically and by default is
 403    * set to 10%.
 404    */
 405   ACE_FIFO_Caching_Strategy ();
 406
 407   // = Strategy methods.
 408
 409   /// Accessor method.
 410   ATTRIBUTES attributes ();
 411
 412   /// Get the percentage of entries to purge.
 413   double purge_percent ();
 414
 415   /// Set the percentage of entries to purge.
 416   void purge_percent (double percentage);
 417
 418   // =  Strategy related Operations
 419
 420   /// Notification for an item getting bound into the cache.
 421   int notify_bind (int result,
 422                    const ATTRIBUTES &attr);
 423
 424   /// This method acts as a notification about the CONTAINERs find
 425   /// method call
 426   int notify_find (int result,
 427                    ATTRIBUTES &attr);
 428
 429   /// This method acts as a notification about the CONTAINERs unbind
 430   /// method call
 431   int notify_unbind (int result,
 432                      const ATTRIBUTES &attr);
 433
 434   /// This method acts as a notification about the CONTAINERs trybind
 435   /// method call
 436   int notify_trybind (int result,
 437                       ATTRIBUTES &attr);
 438
 439   /// Notification for an item getting bound again into the cache.
 440   int notify_rebind (int result,
 441                      const ATTRIBUTES &attr);
 442
 443   /// Purge the cache.
 444   CACHING_UTILITY &caching_utility ();
 445
 446   /// Dumps the state of the object.
 447   void dump () const;
 448
 449   /// Declare the dynamic allocation hooks.
 450   ACE_ALLOC_HOOK_DECLARE;
 451
 452 private:
 453   /// The order is the deciding factor for the item to be removed from
 454   /// the cache.
 455   ATTRIBUTES order_;
 456
 457   /// The level about which the purging will happen automagically.
 458   double purge_percent_;
 459
 460   /// This is the helper class which will decide and expunge entries
 461   /// from the cache.
 462   CACHING_UTILITY caching_utility_;
 463 };
 464
 465 //////////////////////////////////////////////////////////////////////
 466 #define ACE_Null_Caching_Strategy ANULL
 467
 468 /**
 469  * @class ACE_Null_Caching_Strategy
 470  *
 471  * @brief The is a special caching strategy which doesnt have the purging
 472  * feature.
 473  *
 474  * No purging provided. To be used when purging might be too expensive
 475  * an operation.
 476  */
 477 template<class ATTRIBUTES, class CACHING_UTILITY>
 478 class ACE_Null_Caching_Strategy
 479 {
 480 public:
 481   // = Traits.
 482   typedef ATTRIBUTES CACHING_ATTRIBUTES;
 483
 484   // = Strategy methods. All are NO_OP methods!!!
 485
 486   /// Accessor method.
 487   ATTRIBUTES attributes ();
 488
 489   /// Get the percentage of entries to purge.
 490   double purge_percent ();
 491
 492   /// Set the percentage of entries to purge.
 493   void purge_percent (double percentage);
 494
 495   // =  Strategy related Operations
 496
 497   /// Notification for an item getting bound into the cache.
 498   int notify_bind (int result,
 499                    const ATTRIBUTES &attr);
 500
 501   /// This method acts as a notification about the CONTAINERs find
 502   /// method call
 503   int notify_find (int result,
 504                    ATTRIBUTES &attr);
 505
 506   /// This method acts as a notification about the CONTAINERs unbind
 507   /// method call
 508   int notify_unbind (int result,
 509                      const ATTRIBUTES &attr);
 510
 511   /// This method acts as a notification about the CONTAINERs trybind
 512   /// method call
 513   int notify_trybind (int result,
 514                       ATTRIBUTES &attr);
 515
 516   /// Notification for an item getting bound again into the cache.
 517   int notify_rebind (int result,
 518                      const ATTRIBUTES &attr);
 519
 520   /// Purge the cache.
 521   CACHING_UTILITY &caching_utility ();
 522
 523   /// Dumps the state of the object.
 524   void dump () const;
 525
 526   /// Declare the dynamic allocation hooks.
 527   ACE_ALLOC_HOOK_DECLARE;
 528
 529 private:
 530   /// This is the helper class which will decide and expunge entries
 531   /// from the cache.
 532   CACHING_UTILITY caching_utility_;
 533 };
 534
 535 ACE_END_VERSIONED_NAMESPACE_DECL
 536
 537 #if defined (__ACE_INLINE__)
 538 #include "ace/Caching_Strategies_T.inl"
 539 #endif /* __ACE_INLINE__ */
 540
 541 #include "ace/Caching_Strategies_T.cpp"
 542
 543 #include /**/ "ace/post.h"
 544
 545 #endif /* ACE_CACHING_STRATEGIES_H */