updated comments

5 files changed, 81 insertions, 64 deletions

diff --git a/ace/Sched_Params.h b/ace/Sched_Params.h
index b5347eae2a2..dc823033cba 100644
--- a/ace/Sched_Params.h
+++ b/ace/Sched_Params.h
@@ -22,18 +22,29 @@
 
 #include "ace/Thread_Priority.h"
 // for ACE_Time_Value and ACE_SCOPE_PROCESS
-#include "ace/OS.h"  
+#include "ace/OS.h"
 
 class ACE_Export ACE_Scheduling_Params
   // = TITLE
+  //    Container for thread scheduling-related parameters.
   //
   // = DESCRIPTION
+  //    ACE_Scheduling_Params are passed via
+  //    ACE_OS::set_sched_params () to the OS to specify scheduling
+  //    parameters.  It is intended that ACE_OS::set_sched_params ()
+  //    be called from main () before any threads have been spawned.
+  //    If spawned threads inherit their parent's priority (I think
+  //    that's the case for all of our platforms), then this sets
+  //    the default base priority.  Individual thread priorities can
+  //    be adjusted as usual using ACE_OS::thr_prio () or via the
+  //    ACE_Thread interface.  See the parameter descriptions in the
+  //    private: section below.
 {
 public:
   // = Initialization and termination methods.
   ACE_Scheduling_Params (const ACE_Thread_Priority &priority = ACE_Thread_Priority (),
-			 const int scope = ACE_SCOPE_PROCESS,
-			 const ACE_Time_Value &quantum = ACE_Time_Value::zero);
+                         const int scope = ACE_SCOPE_PROCESS,
+                         const ACE_Time_Value &quantum = ACE_Time_Value::zero);
   // Constructor.
 
   ~ACE_Scheduling_Params (void);
@@ -56,11 +67,7 @@ public:
 private:
   ACE_Thread_Priority priority_;
   // Default <priority_>: sets the priority to be used for newly
-  // spawned threads.  It is intended that this function be called
-  // from main () before any threads have been spawned.  If spawned
-  // threads inherit their parent's priority (I think that's the case
-  // for all of our platforms), then this sets the default base
-  // priority.  Individual thread priorities can be adjusted as usual.
+  // spawned threads.
 
   int scope_;
   // <scope_> must be either ACE_SCOPE_PROCESS or ACE_SCOPE_LWP (which
diff --git a/ace/Sched_Params.i b/ace/Sched_Params.i
index f765684673d..82b7f29b61a 100644
--- a/ace/Sched_Params.i
+++ b/ace/Sched_Params.i
@@ -19,8 +19,8 @@
 
 ACE_INLINE
 ACE_Scheduling_Params::ACE_Scheduling_Params (const ACE_Thread_Priority &priority,
-					      const int scope,
-					      const ACE_Time_Value &quantum) 
+                                              const int scope,
+                                              const ACE_Time_Value &quantum)
   : priority_ (priority),
     scope_ (scope),
     quantum_ (quantum)
diff --git a/ace/Thread_Priority.cpp b/ace/Thread_Priority.cpp
index 97060d5942e..a282125ac37 100644
--- a/ace/Thread_Priority.cpp
+++ b/ace/Thread_Priority.cpp
@@ -41,19 +41,19 @@
  */
 
 long
-ACE_Thread_Priority::normalize (void)
+ACE_Thread_Priority::convert_to_os_priority (void)
 {
   // Get the priority class ID and attributes.
   pcinfo_t pcinfo;
   ACE_OS::strcpy (pcinfo.pc_clname,
-                  priority_class_ == ACE_HIGH_PRIORITY_CLASS 
-		  || priority_class_ == ACE_REALTIME_PRIORITY_CLASS
-		  ?  "RT"
-		  :  "TS");
-
-  if (::priocntl (P_ALL /* ignored */, 
-		  P_MYID /* ignored */, 
-		  PC_GETCID,
+                  priority_class_ == ACE_HIGH_PRIORITY_CLASS
+                  || priority_class_ == ACE_REALTIME_PRIORITY_CLASS
+                  ?  "RT"
+                  :  "TS");
+
+  if (::priocntl (P_ALL /* ignored */,
+                  P_MYID /* ignored */,
+                  PC_GETCID,
                   (char *) &pcinfo) == -1)
     return -1;
 
@@ -63,14 +63,14 @@ ACE_Thread_Priority::normalize (void)
 
   os_priority_class_ = pcinfo.pc_cid;
 
-  if (ACE_PRIORITY_MIN <= default_thread_priority_  
+  if (ACE_PRIORITY_MIN <= default_thread_priority_
       && default_thread_priority_ <= ACE_PRIORITY_MAX)
     {
       os_default_thread_priority_ =
-        priority_class_ == ACE_NORMAL_PRIORITY_CLASS 
-	|| priority_class_ == ACE_REALTIME_PRIORITY_CLASS
-	?  default_thread_priority_ + 7
-	:  default_thread_priority_;
+        priority_class_ == ACE_NORMAL_PRIORITY_CLASS
+        || priority_class_ == ACE_REALTIME_PRIORITY_CLASS
+        ?  default_thread_priority_ + 7
+        :  default_thread_priority_;
     }
   else
     // The user specified a thread priority outside the enum range, so
@@ -94,7 +94,7 @@ ACE_Thread_Priority::normalize (void)
  */
 
 long
-ACE_Thread_Priority::normalize (void)
+ACE_Thread_Priority::convert_to_os_priority (void)
 {
   switch (priority_class_)
   {
@@ -112,7 +112,7 @@ ACE_Thread_Priority::normalize (void)
       break;
   }
 
-  if (ACE_PRIORITY_MIN <= default_thread_priority_  
+  if (ACE_PRIORITY_MIN <= default_thread_priority_
       && default_thread_priority_ <= ACE_PRIORITY_MAX)
     {
       switch (default_thread_priority_)
@@ -162,30 +162,30 @@ ACE_Thread_Priority::normalize (void)
  */
 
 long
-ACE_Thread_Priority::normalize (void)
+ACE_Thread_Priority::convert_to_os_priority (void)
 {
   os_priority_class_ = -1;  /* unused on this platform */
 
-  if (ACE_PRIORITY_MIN <= default_thread_priority_  
+  if (ACE_PRIORITY_MIN <= default_thread_priority_
       && default_thread_priority_ <= ACE_PRIORITY_MAX)
     {
       switch (priority_class)
       {
         case ACE_LOW_PRIORITY_CLASS :
-          os_default_thread_priority_ = 
-	    ACE_PRIORITY_MAX - default_thread_priority_ + 21;
+          os_default_thread_priority_ =
+            ACE_PRIORITY_MAX - default_thread_priority_ + 21;
           break;
         case ACE_NORMAL_PRIORITY_CLASS :
-          os_default_thread_priority_ = 
-	    ACE_PRIORITY_MAX - default_thread_priority_ + 14;
+          os_default_thread_priority_ =
+            ACE_PRIORITY_MAX - default_thread_priority_ + 14;
           break;
         case ACE_HIGH_PRIORITY_CLASS :
-          os_default_thread_priority_ = 
-	    ACE_PRIORITY_MAX - default_thread_priority_ + 7;
+          os_default_thread_priority_ =
+            ACE_PRIORITY_MAX - default_thread_priority_ + 7;
           break;
         case ACE_REALTIME_PRIORITY_CLASS :
-          os_default_thread_priority_ = 
-	    ACE_PRIORITY_MAX - default_thread_priority_;
+          os_default_thread_priority_ =
+            ACE_PRIORITY_MAX - default_thread_priority_;
           break;
       }
     }
@@ -212,11 +212,11 @@ ACE_Thread_Priority::normalize (void)
 
 // assumes that priority increases with increasing ACE_pri_t value
 long
-ACE_Thread_Priority::normalize (void)
+ACE_Thread_Priority::convert_to_os_priority (void)
 {
   os_priority_class_ = -1;  /* unused on this platform */
 
-  if (ACE_PRIORITY_MIN <= default_thread_priority_ 
+  if (ACE_PRIORITY_MIN <= default_thread_priority_
       && default_thread_priority_ <= ACE_PRIORITY_MAX)
     {
       switch (priority_class)
diff --git a/ace/Thread_Priority.h b/ace/Thread_Priority.h
index 4e4715c5e54..4e6cd5b68e8 100644
--- a/ace/Thread_Priority.h
+++ b/ace/Thread_Priority.h
@@ -20,10 +20,19 @@
 #if ! defined (ACE_THREAD_PRIORITY_H)
 #define ACE_THREAD_PRIORITY_H
 
-class  ACE_Export ACE_Thread_Priority
+class ACE_Export ACE_Thread_Priority
   // = TITLE
+  //    Provides OS-independent scheduling priority classes and thread
+  //    priorities.
   //
   // = DESCRIPTION
+  //    ACE_Thread_Priority provides OS-independent scheduling priority
+  //    classes and thread priority values.  Applications that use
+  //    these priority values don't have to be concerned that lower
+  //    values indicate higher thread priorities on some platforms but
+  //    lower on others.  ACE_Thread_Priorities are typically used with
+  //    ACE_Scheduling_Parameters to specify scheduling behavior to the
+  //    OS.
 {
 public:
   enum Priority_Class
@@ -34,16 +43,6 @@ public:
     ACE_REALTIME_PRIORITY_CLASS
   };
 
-  // = This enum help users create OS-independent priorities.
-
-  // For applications that don't require OS- independence, they can
-  // take advantage of a greater range of thread priorities offered by
-  // their platform.  This can be done by casting the OS-dependent
-  // priority to ACE_Thread_Priority::Thread_Priority when calling the
-  // member functions that take it as an argument.  In other words,
-  // this class will not "break" if a Thread_Priority outside of
-  // [ACE_PRIORITY_MIN .. ACE_PRIORITY_MAX] is used.
-
   enum Thread_Priority
   {
     ACE_PRIORITY_0 = 0,
@@ -56,14 +55,23 @@ public:
     ACE_PRIORITY_6,
     ACE_PRIORITY_MAX = ACE_PRIORITY_6
   };
+  // = This enum helps users create OS-independent priorities.
+  //
+  // For applications that don't require OS- independence, they can
+  // take advantage of a greater range of thread priorities offered by
+  // their platform.  This can be done by casting the OS-specific
+  // priority to ACE_Thread_Priority::Thread_Priority when calling the
+  // member functions that take it as an argument.  In other words,
+  // this class will not "break" if a Thread_Priority outside of
+  // [ACE_PRIORITY_MIN .. ACE_PRIORITY_MAX] is used.
 
   // = NOTE
-
+  //
   // the following distinct ACE_Thread_Priority combinations map to
   // identical priority class/thread priority combinations on Win32.
   // They may map to distinct priorities on other platforms.  So, if
   // OS-independent behavior is desired, applications should not
-  // depend on these having either the same or different OS
+  // depend on these having either the same or different OS-specific
   // priorities:
   //
   // * ACE_LOW_PRIORITY_CLASS/ACE_PRIORITY_0 ==
@@ -77,7 +85,7 @@ public:
   //       ACE_HIGH_PRIORITY_CLASS/ACE_PRIORITY_6
 
   ACE_Thread_Priority (Priority_Class priority_class = ACE_NORMAL_PRIORITY_CLASS,
-		       Thread_Priority default_thread_priority = ACE_PRIORITY_MIN);
+                       Thread_Priority default_thread_priority = ACE_PRIORITY_MIN);
   // There can be more than one ACE_Thread_Priority instance per
   // process, e.g., one per Solaris Lightweight Process.
 
@@ -90,10 +98,11 @@ public:
 
   // = Set/Get accessors for default thread priority.
   long default_thread_priority (const Thread_Priority);
+  // Return 0 on success and -1 on failure (and sets errno).
   Thread_Priority default_thread_priority (void) const;
 
   ACE_id_t os_priority_class (void) const;
-  // Get accessor for the OS-specific priority class
+  // Get accessor for the OS-specific priority class.
 
   ACE_pri_t os_default_thread_priority (void) const;
   // Get accessor for the numeric default thread priority value, which
@@ -101,19 +110,19 @@ public:
 
 private:
   Priority_Class priority_class_;
-  // Priority class of this thread.
+  // Priority class of this thread, OS-independent.
 
   Thread_Priority default_thread_priority_;
-  // Default thread priority for this class.
+  // Default thread priority value, OS-independent.
 
   ACE_id_t os_priority_class_;
-  // Please document me.
+  // OS-specific value of priority_class_.
 
   ACE_pri_t os_default_thread_priority_;
-  // Please document me.
+  // OS-specific value of default_thread_priority_.
 
-  long normalize (void);
-  // Convert OS-dependent priorities into OS-independent priorities.
+  long convert_to_os_priority (void);
+  // Convert OS-independent priorities into OS-specific priorities.
 };
 
 #if defined (__ACE_INLINE__)
diff --git a/ace/Thread_Priority.i b/ace/Thread_Priority.i
index 7360165f2b1..9975f8f0659 100644
--- a/ace/Thread_Priority.i
+++ b/ace/Thread_Priority.i
@@ -19,12 +19,13 @@
 
 ACE_INLINE
 ACE_Thread_Priority::ACE_Thread_Priority (Priority_Class priority_class,
-					  Thread_Priority default_thread_priority) 
+                                          Thread_Priority default_thread_priority)
   : priority_class_ (priority_class),
     default_thread_priority_ (default_thread_priority)
 {
-  // normalize () sets os_priority_class_ and os_default_thread_priority_
-  (void) normalize ();
+  // convert_to_os_priority () sets os_priority_class_ and
+  // os_default_thread_priority_
+  (void) convert_to_os_priority ();
 }
 
 ACE_INLINE
@@ -36,13 +37,13 @@ ACE_INLINE long
 ACE_Thread_Priority::priority_class (const Priority_Class priority_class)
 {
   this->priority_class_ = priority_class;
-  return this->normalize ();
+  return this->convert_to_os_priority ();
 }
 
 ACE_INLINE long ACE_Thread_Priority::default_thread_priority (const Thread_Priority default_thread_priority)
 {
   this->default_thread_priority_ = default_thread_priority;
-  return this->normalize ();
+  return this->convert_to_os_priority ();
 }
 
 ACE_INLINE ACE_Thread_Priority::Priority_Class