ACE_Dynamic_Message_Strategy Class Reference

An abstract base class which provides dynamic priority evaluation methods for use by the ACE_Dynamic_Message_Queue class or any other class which needs to manage the priorities of a collection of ACE_Message_Blocks dynamically. More...

#include <Dynamic_Message_Strategy.h>

Inheritance diagram for ACE_Dynamic_Message_Strategy:

Inheritance graph
[legend]
Collaboration diagram for ACE_Dynamic_Message_Strategy:

Collaboration graph
[legend]
List of all members.

Public Types

 PENDING = 0x01
 Message can still make its deadline.
 LATE = 0x02
 Message cannot make its deadline.
 BEYOND_LATE = 0x04
 Message is so late its priority is undefined.
 ANY_STATUS = 0x07
 Mask to match any priority status.
enum  Priority_Status { PENDING = 0x01, LATE = 0x02, BEYOND_LATE = 0x04, ANY_STATUS = 0x07 }

Public Member Functions

 ACE_Dynamic_Message_Strategy (unsigned long static_bit_field_mask, unsigned long static_bit_field_shift, unsigned long dynamic_priority_max, unsigned long dynamic_priority_offset)
 Constructor.
virtual ~ACE_Dynamic_Message_Strategy (void)
 Virtual destructor.
Priority_Status priority_status (ACE_Message_Block &mb, const ACE_Time_Value &tv)
 Updates the message's priority and returns its priority status.
unsigned long static_bit_field_mask (void) const
 Get static bit field mask.
void static_bit_field_mask (unsigned long)
 Set static bit field mask.
unsigned long static_bit_field_shift (void) const
 Get left shift value to make room for static bit field.
void static_bit_field_shift (unsigned long)
 Set left shift value to make room for static bit field.
unsigned long dynamic_priority_max (void) const
 Get maximum supported priority value.
void dynamic_priority_max (unsigned long)
 Set maximum supported priority value.
unsigned long dynamic_priority_offset (void) const
 Get offset to boundary between signed range and unsigned range.
void dynamic_priority_offset (unsigned long)
 Set offset to boundary between signed range and unsigned range.
virtual void dump (void) const
 Dump the state of the strategy.

Protected Member Functions

virtual void convert_priority (ACE_Time_Value &priority, const ACE_Message_Block &mb)=0
 Hook method for dynamic priority conversion.

Protected Attributes

unsigned long static_bit_field_mask_
 This is a bit mask with all ones in the static bit field.
unsigned long static_bit_field_shift_
unsigned long dynamic_priority_max_
 Maximum supported priority value.
unsigned long dynamic_priority_offset_
 Offset to boundary between signed range and unsigned range.
ACE_Time_Value max_late_
 Maximum late time value that can be represented.
ACE_Time_Value min_pending_
 Minimum pending time value that can be represented.
ACE_Time_Value pending_shift_
 Time value by which to shift pending priority.

Detailed Description

An abstract base class which provides dynamic priority evaluation methods for use by the ACE_Dynamic_Message_Queue class or any other class which needs to manage the priorities of a collection of ACE_Message_Blocks dynamically.

Methods for deadline and laxity based priority evaluation are provided. These methods assume a specific partitioning of the message priority number into a higher order dynamic bit field and a lower order static priority bit field. The default partitioning assumes an unsigned dynamic message priority field of 22 bits and an unsigned static message priority field of 10 bits. This corresponds to the initial values of the static class members. To provide a different partitioning, assign a different set of values to the static class memebers before using the static member functions.

Definition at line 48 of file Dynamic_Message_Strategy.h.

Member Enumeration Documentation

enum ACE_Dynamic_Message_Strategy::Priority_Status

Enumerator:
PENDING  Message can still make its deadline.
LATE  Message cannot make its deadline.
BEYOND_LATE  Message is so late its priority is undefined.
ANY_STATUS  Mask to match any priority status.

Definition at line 57 of file Dynamic_Message_Strategy.h.

00058   {
00059     /// Message can still make its deadline
00060     PENDING     = 0x01,
00061     /// Message cannot make its deadline
00062     LATE        = 0x02,
00063     /// Message is so late its priority is undefined
00064     BEYOND_LATE = 0x04,
00065     /// Mask to match any priority status
00066     ANY_STATUS  = 0x07
00067   };

Constructor & Destructor Documentation

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_Dynamic_Message_Strategy::ACE_Dynamic_Message_Strategy ( unsigned long  static_bit_field_mask,
unsigned long  static_bit_field_shift,
unsigned long  dynamic_priority_max,
unsigned long  dynamic_priority_offset 
)

Constructor.

Definition at line 20 of file Dynamic_Message_Strategy.cpp.

00024   : static_bit_field_mask_ (static_bit_field_mask),
00025     static_bit_field_shift_ (static_bit_field_shift),
00026     dynamic_priority_max_ (dynamic_priority_max),
00027     dynamic_priority_offset_ (dynamic_priority_offset),
00028     max_late_ (0, dynamic_priority_offset - 1),
00029     min_pending_ (0, dynamic_priority_offset),
00030     pending_shift_ (0, dynamic_priority_max)
00031 {
00032 }

ACE_Dynamic_Message_Strategy::~ACE_Dynamic_Message_Strategy ( void   )  [virtual]

Virtual destructor.

Definition at line 36 of file Dynamic_Message_Strategy.cpp.

00037 {
00038 }

Member Function Documentation

virtual void ACE_Dynamic_Message_Strategy::convert_priority ( ACE_Time_Value &  priority,
const ACE_Message_Block &  mb 
) [protected, pure virtual]

Hook method for dynamic priority conversion.

Implemented in ACE_Deadline_Message_Strategy, and ACE_Laxity_Message_Strategy.

Referenced by priority_status().

void ACE_Dynamic_Message_Strategy::dump ( void   )  const [virtual]

Dump the state of the strategy.

Reimplemented in ACE_Deadline_Message_Strategy, and ACE_Laxity_Message_Strategy.

Definition at line 89 of file Dynamic_Message_Strategy.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_TEXT, ACE_TRACE, LM_DEBUG, max_late_, min_pending_, pending_shift_, ACE_Time_Value::sec(), and ACE_Time_Value::usec().

Referenced by ACE_Dynamic_Message_Queue<>::dump(), ACE_Laxity_Message_Strategy::dump(), and ACE_Deadline_Message_Strategy::dump().

00090 {
00091 #if defined (ACE_HAS_DUMP)
00092   ACE_TRACE ("ACE_Dynamic_Message_Strategy::dump");
00093 
00094   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00095 
00096   ACE_DEBUG ((LM_DEBUG,
00097               ACE_TEXT ("static_bit_field_mask_ = %u\n")
00098               ACE_TEXT ("static_bit_field_shift_ = %u\n")
00099               ACE_TEXT ("dynamic_priority_max_ = %u\n")
00100               ACE_TEXT ("dynamic_priority_offset_ = %u\n")
00101               ACE_TEXT ("max_late_ = [%d sec, %d usec]\n")
00102               ACE_TEXT ("min_pending_ = [%d sec, %d usec]\n")
00103               ACE_TEXT ("pending_shift_ = [%d sec, %d usec]\n"),
00104               this->static_bit_field_mask_,
00105               this->static_bit_field_shift_,
00106               this->dynamic_priority_max_,
00107               this->dynamic_priority_offset_,
00108               this->max_late_.sec (),
00109               this->max_late_.usec (),
00110               this->min_pending_.sec (),
00111               this->min_pending_.usec (),
00112               this->pending_shift_.sec (),
00113               this->pending_shift_.usec ()));
00114 
00115   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00116 #endif /* ACE_HAS_DUMP */
00117 }

ACE_INLINE void ACE_Dynamic_Message_Strategy::dynamic_priority_max ( unsigned  long  ) 

Set maximum supported priority value.

Definition at line 43 of file Dynamic_Message_Strategy.inl.

References dynamic_priority_max_, and pending_shift_.

00044 {
00045   // pending_shift_ depends on dynamic_priority_max_: for performance
00046   // reasons, the value in pending_shift_ is (re)calculated only when
00047   // dynamic_priority_max_ is initialized or changes, and is stored
00048   // as a class member rather than being a derived value.
00049   dynamic_priority_max_ = ul;
00050   pending_shift_ = ACE_Time_Value (0, ul);
00051 }

ACE_INLINE unsigned long ACE_Dynamic_Message_Strategy::dynamic_priority_max ( void   )  const

Get maximum supported priority value.

Definition at line 36 of file Dynamic_Message_Strategy.inl.

References dynamic_priority_max_.

00037 {
00038   return dynamic_priority_max_;
00039 }

ACE_INLINE void ACE_Dynamic_Message_Strategy::dynamic_priority_offset ( unsigned  long  ) 

Set offset to boundary between signed range and unsigned range.

Definition at line 62 of file Dynamic_Message_Strategy.inl.

References dynamic_priority_offset_, max_late_, and min_pending_.

00063 {
00064   // max_late_ and min_pending_ depend on dynamic_priority_offset_:
00065   // for performance reasons, the values in max_late_ and min_pending_
00066   // are (re)calculated only when dynamic_priority_offset_ is
00067   // initialized or changes, and are stored as a class member rather
00068   // than being derived each time one of their values is needed.
00069   dynamic_priority_offset_ = ul;
00070   max_late_ = ACE_Time_Value (0, ul - 1);
00071   min_pending_ = ACE_Time_Value (0, ul);
00072 }

ACE_INLINE unsigned long ACE_Dynamic_Message_Strategy::dynamic_priority_offset ( void   )  const

Get offset to boundary between signed range and unsigned range.

Definition at line 55 of file Dynamic_Message_Strategy.inl.

References dynamic_priority_offset_.

00056 {
00057   return dynamic_priority_offset_;
00058 }

ACE_Dynamic_Message_Strategy::Priority_Status ACE_Dynamic_Message_Strategy::priority_status ( ACE_Message_Block &  mb,
const ACE_Time_Value &  tv 
)

Updates the message's priority and returns its priority status.

Definition at line 41 of file Dynamic_Message_Strategy.cpp.

References ACE_ONE_SECOND_IN_USECS, BEYOND_LATE, convert_priority(), LATE, max_late_, min_pending_, ACE_Message_Block::msg_priority(), PENDING, pending_shift_, ACE_Time_Value::sec(), static_bit_field_mask_, static_bit_field_shift_, ACE_Time_Value::usec(), and ACE_Time_Value::zero.

Referenced by ACE_Dynamic_Message_Queue<>::enqueue_i(), ACE_Dynamic_Message_Queue<>::refresh_late_queue(), ACE_Dynamic_Message_Queue<>::refresh_pending_queue(), and ACE_Dynamic_Message_Queue<>::sublist_enqueue_i().

00043 {
00044   // default the message to have pending priority status
00045   Priority_Status status = ACE_Dynamic_Message_Strategy::PENDING;
00046 
00047   // start with the passed absolute time as the message's priority, then
00048   // call the polymorphic hook method to (at least partially) convert
00049   // the absolute time and message attributes into the message's priority
00050   ACE_Time_Value priority (tv);
00051   convert_priority (priority, mb);
00052 
00053   // if the priority is negative, the message is pending
00054   if (priority < ACE_Time_Value::zero)
00055     {
00056       // priority for pending messages must be shifted
00057       // upward above the late priority range
00058       priority += pending_shift_;
00059       if (priority < min_pending_)
00060         priority = min_pending_;
00061     }
00062   // otherwise, if the priority is greater than the maximum late
00063   // priority value that can be represented, it is beyond late
00064   else if (priority > max_late_)
00065     {
00066       // all messages that are beyond late are assigned lowest priority (zero)
00067       mb.msg_priority (0);
00068       return ACE_Dynamic_Message_Strategy::BEYOND_LATE;
00069     }
00070   // otherwise, the message is late, but its priority is correct
00071   else
00072     status = ACE_Dynamic_Message_Strategy::LATE;
00073 
00074   // use (fast) bitwise operators to isolate and replace
00075   // the dynamic portion of the message's priority
00076   mb.msg_priority((mb.msg_priority() & static_bit_field_mask_) |
00077                   ((priority.usec () +
00078                     ACE_ONE_SECOND_IN_USECS * (suseconds_t)(priority.sec())) <<
00079                    static_bit_field_shift_));
00080 
00081   // returns the priority status of the message
00082   return status;
00083 }

ACE_INLINE void ACE_Dynamic_Message_Strategy::static_bit_field_mask ( unsigned  long  ) 

Set static bit field mask.

Definition at line 15 of file Dynamic_Message_Strategy.inl.

References static_bit_field_mask_.

00016 {
00017   static_bit_field_mask_ = ul;
00018 }

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE unsigned long ACE_Dynamic_Message_Strategy::static_bit_field_mask ( void   )  const

Get static bit field mask.

Definition at line 8 of file Dynamic_Message_Strategy.inl.

References static_bit_field_mask_.

00009 {
00010   return static_bit_field_mask_;
00011 }

ACE_INLINE void ACE_Dynamic_Message_Strategy::static_bit_field_shift ( unsigned  long  ) 

Set left shift value to make room for static bit field.

Definition at line 29 of file Dynamic_Message_Strategy.inl.

References static_bit_field_shift_.

00030 {
00031   static_bit_field_shift_ = ul;
00032 }

ACE_INLINE unsigned long ACE_Dynamic_Message_Strategy::static_bit_field_shift ( void   )  const

Get left shift value to make room for static bit field.

Definition at line 22 of file Dynamic_Message_Strategy.inl.

References static_bit_field_shift_.

00023 {
00024   return static_bit_field_shift_;
00025 }

Member Data Documentation

unsigned long ACE_Dynamic_Message_Strategy::dynamic_priority_max_ [protected]

Maximum supported priority value.

Definition at line 125 of file Dynamic_Message_Strategy.h.

Referenced by dynamic_priority_max().

unsigned long ACE_Dynamic_Message_Strategy::dynamic_priority_offset_ [protected]

Offset to boundary between signed range and unsigned range.

Definition at line 128 of file Dynamic_Message_Strategy.h.

Referenced by dynamic_priority_offset().

ACE_Time_Value ACE_Dynamic_Message_Strategy::max_late_ [protected]

Maximum late time value that can be represented.

Definition at line 131 of file Dynamic_Message_Strategy.h.

Referenced by dump(), dynamic_priority_offset(), and priority_status().

ACE_Time_Value ACE_Dynamic_Message_Strategy::min_pending_ [protected]

Minimum pending time value that can be represented.

Definition at line 134 of file Dynamic_Message_Strategy.h.

Referenced by dump(), dynamic_priority_offset(), and priority_status().

ACE_Time_Value ACE_Dynamic_Message_Strategy::pending_shift_ [protected]

Time value by which to shift pending priority.

Definition at line 137 of file Dynamic_Message_Strategy.h.

Referenced by dump(), dynamic_priority_max(), and priority_status().

unsigned long ACE_Dynamic_Message_Strategy::static_bit_field_mask_ [protected]

This is a bit mask with all ones in the static bit field.

Definition at line 115 of file Dynamic_Message_Strategy.h.

Referenced by priority_status(), and static_bit_field_mask().

unsigned long ACE_Dynamic_Message_Strategy::static_bit_field_shift_ [protected]

This is a left shift value to make room for static bit field: this value should be the logarithm base 2 of (static_bit_field_mask_ + 1).

Definition at line 122 of file Dynamic_Message_Strategy.h.

Referenced by priority_status(), and static_bit_field_shift().

The documentation for this class was generated from the following files:
Generated on Tue Feb 2 17:35:05 2010 for ACE by  doxygen 1.4.7