ACE/ace/Dynamic_Message_Strategy.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Dynamic_Message_Strategy.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_DYNAMIC_MESSAGE_STRATEGY_H
  12 #define ACE_DYNAMIC_MESSAGE_STRATEGY_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/config-lite.h"
  17 #include /**/ "ace/ACE_export.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/Message_Block.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 /**
  28  * @class ACE_Dynamic_Message_Strategy
  29  *
  30  * @brief An abstract base class which provides dynamic priority
  31  * evaluation methods for use by the ACE_Dynamic_Message_Queue
  32  * class or any other class which needs to manage the priorities
  33  * of a collection of ACE_Message_Blocks dynamically.
  34  *
  35  * Methods for deadline and laxity based priority evaluation are
  36  * provided.  These methods assume a specific partitioning of
  37  * the message priority number into a higher order dynamic bit
  38  * field and a lower order static priority bit field.  The
  39  * default partitioning assumes an unsigned dynamic message
  40  * priority field of 22 bits and an unsigned static message
  41  * priority field of 10 bits.  This corresponds to the initial
  42  * values of the static class members.  To provide a different
  43  * partitioning, assign a different set of values to the static
  44  * class members before using the static member functions.
  45  */
  46 class ACE_Export ACE_Dynamic_Message_Strategy
  47 {
  48 public:
  49   /// Message priority status
  50   /// Values are defined as bit flags so that status combinations may
  51   /// be specified easily.
  52   enum Priority_Status
  53   {
  54     /// Message can still make its deadline
  55     PENDING     = 0x01,
  56     /// Message cannot make its deadline
  57     LATE        = 0x02,
  58     /// Message is so late its priority is undefined
  59     BEYOND_LATE = 0x04,
  60     /// Mask to match any priority status
  61     ANY_STATUS  = 0x07
  62   };
  63
  64   /// Constructor.
  65   ACE_Dynamic_Message_Strategy (unsigned long static_bit_field_mask,
  66                                 unsigned long static_bit_field_shift,
  67                                 unsigned long dynamic_priority_max,
  68                                 unsigned long dynamic_priority_offset);
  69
  70   /// Virtual destructor.
  71   virtual ~ACE_Dynamic_Message_Strategy ();
  72
  73   /// Updates the message's priority and returns its priority status.
  74   Priority_Status priority_status (ACE_Message_Block &mb,
  75                                    const ACE_Time_Value &tv);
  76
  77   /// Get static bit field mask.
  78   unsigned long static_bit_field_mask () const;
  79
  80   /// Set static bit field mask.
  81   void static_bit_field_mask (unsigned long);
  82
  83   /// Get left shift value to make room for static bit field.
  84   unsigned long static_bit_field_shift () const;
  85
  86   /// Set left shift value to make room for static bit field.
  87   void static_bit_field_shift (unsigned long);
  88
  89   /// Get maximum supported priority value.
  90   unsigned long dynamic_priority_max () const;
  91
  92   /// Set maximum supported priority value.
  93   void dynamic_priority_max (unsigned long);
  94
  95   /// Get offset to boundary between signed range and unsigned range.
  96   unsigned long dynamic_priority_offset () const;
  97
  98   /// Set offset to boundary between signed range and unsigned range.
  99   void dynamic_priority_offset (unsigned long);
 100
 101   /// Dump the state of the strategy.
 102   virtual void dump () const;
 103
 104 protected:
 105   /// Hook method for dynamic priority conversion.
 106   virtual void convert_priority (ACE_Time_Value &priority,
 107                                  const ACE_Message_Block &mb) = 0;
 108
 109   /// This is a bit mask with all ones in the static bit field.
 110   unsigned long static_bit_field_mask_;
 111
 112   /**
 113    * This is a left shift value to make room for static bit field:
 114    * this value should be the logarithm base 2 of
 115    * (static_bit_field_mask_ + 1).
 116    */
 117   unsigned long static_bit_field_shift_;
 118
 119   /// Maximum supported priority value.
 120   unsigned long dynamic_priority_max_;
 121
 122   /// Offset to boundary between signed range and unsigned range.
 123   unsigned long dynamic_priority_offset_;
 124
 125   /// Maximum late time value that can be represented.
 126   ACE_Time_Value max_late_;
 127
 128   /// Minimum pending time value that can be represented.
 129   ACE_Time_Value min_pending_;
 130
 131   /// Time value by which to shift pending priority.
 132   ACE_Time_Value pending_shift_;
 133 };
 134
 135 /**
 136  * @class ACE_Deadline_Message_Strategy
 137  *
 138  * @brief Deadline based message priority strategy.
 139  *
 140  * Assigns dynamic message priority according to time to deadline.  The
 141  * message priority is divided into high and low order bit fields.  The
 142  * high order bit field is used for dynamic message priority, which is
 143  * updated whenever the convert_priority() method is called.  The
 144  * low order bit field is used for static message priority and is left
 145  * unchanged.  The partitioning of the priority value into high and low
 146  * order bit fields is done according to the arguments passed to the
 147  * strategy object's constructor.
 148  */
 149 class ACE_Export ACE_Deadline_Message_Strategy : public ACE_Dynamic_Message_Strategy
 150 {
 151 public:
 152   /// Constructor with all arguments defaulted.
 153   ACE_Deadline_Message_Strategy (unsigned long static_bit_field_mask = 0x3FFUL,       // 2^(10) - 1
 154                                  unsigned long static_bit_field_shift = 10,           // 10 low order bits
 155                                  unsigned long dynamic_priority_max = 0x3FFFFFUL,     // 2^(22)-1
 156                                  unsigned long dynamic_priority_offset = 0x200000UL); // 2^(22-1)
 157
 158   /// Virtual destructor.
 159   virtual ~ACE_Deadline_Message_Strategy ();
 160
 161   /// Dynamic priority conversion function based on time to deadline.
 162   virtual void convert_priority (ACE_Time_Value &priority,
 163                                  const ACE_Message_Block &mb);
 164
 165   /// Dump the state of the strategy.
 166   virtual void dump () const;
 167 };
 168
 169 /**
 170  * @class ACE_Laxity_Message_Strategy
 171  *
 172  * @brief Laxity based message priority strategy.
 173  *
 174  * Assigns dynamic message priority according to laxity (time to
 175  * deadline minus worst case execution time).  The message priority is
 176  * divided into high and low order bit fields.  The high order
 177  * bit field is used for dynamic message priority, which is
 178  * updated whenever the convert_priority() method is called.  The
 179  * low order bit field is used for static message priority and is left
 180  * unchanged.  The partitioning of the priority value into high and low
 181  * order bit fields is done according to the arguments passed to the
 182  * strategy object's constructor.
 183  */
 184 class ACE_Export ACE_Laxity_Message_Strategy : public ACE_Dynamic_Message_Strategy
 185 {
 186 public:
 187   /// Ctor, with all arguments defaulted.
 188   ACE_Laxity_Message_Strategy (unsigned long static_bit_field_mask = 0x3FFUL,       // 2^(10) - 1
 189                                unsigned long static_bit_field_shift = 10,           // 10 low order bits
 190                                unsigned long dynamic_priority_max = 0x3FFFFFUL,     // 2^(22)-1
 191                                unsigned long dynamic_priority_offset = 0x200000UL); // 2^(22-1)
 192
 193   /// virtual dtor.
 194   virtual ~ACE_Laxity_Message_Strategy ();
 195
 196   /// Dynamic priority conversion function based on laxity.
 197   virtual void convert_priority (ACE_Time_Value &priority,
 198                                  const ACE_Message_Block &mb);
 199
 200   /// Dump the state of the strategy.
 201   virtual void dump () const;
 202 };
 203
 204 ACE_END_VERSIONED_NAMESPACE_DECL
 205
 206 #if defined (__ACE_INLINE__)
 207 #include "ace/Dynamic_Message_Strategy.inl"
 208 #endif /* __ACE_INLINE__ */
 209
 210 #include /**/ "ace/post.h"
 211
 212 #endif /* ACE_DYNAMIC_MESSAGE_STRATEGY_H */