incorporate updates from Thilo

3 files changed, 82 insertions, 55 deletions

diff --git a/ace/OS.cpp b/ace/OS.cpp
index 6423f4c5c1b..a957881cc6e 100644
--- a/ace/OS.cpp
+++ b/ace/OS.cpp
@@ -625,46 +625,6 @@ ACE_OS::sched_params (const ACE_Sched_Params &sched_params)
 
   return 0;
 
-#elif defined (ACE_WIN32)
-
-  if (sched_params.scope () != ACE_SCOPE_PROCESS  ||
-      sched_params.quantum () != ACE_Time_Value::zero)
-    {
-      // Win32 only allows setting priority class (therefore, policy)
-      // at the process level.  I don't know of a way to set the quantum.
-      errno = EINVAL;
-      return -1;
-    }
-
-  // Set the priority class of this process to the REALTIME process class
-  // _if_ the policy is ACE_SCHED_FIFO.  Otherwise, set to NORMAL.
-  if (! ::SetPriorityClass (
-          ::GetCurrentProcess (),
-          sched_params.policy () == ACE_SCHED_FIFO
-            ?  REALTIME_PRIORITY_CLASS
-            :  NORMAL_PRIORITY_CLASS))
-    {
-      return -1;
-    }
-
-  // Set the thread priority on the current thread.
-  return ACE_OS::thr_setprio (sched_params.priority ());
-
-#elif defined (VXWORKS)
-  // There is only one class of priorities on VxWorks, and no
-  // time quanta.  So, just set the current thread's priority.
-
-  if (sched_params.policy () != ACE_SCHED_FIFO  ||
-      sched_params.scope () != ACE_SCOPE_PROCESS  ||
-      sched_params.quantum () != ACE_Time_Value::zero)
-    {
-      errno = EINVAL;
-      return -1;
-    }
-
-  // Set the thread priority on the current thread.
-  return ACE_OS::thr_setprio (sched_params.priority ());
-
 #elif (defined (ACE_HAS_DCETHREADS) || defined (ACE_HAS_PTHREADS)) && !defined (ACE_LACKS_SETSCHED)
   if (sched_params.quantum () != ACE_Time_Value::zero)
     {
@@ -678,7 +638,6 @@ ACE_OS::sched_params (const ACE_Sched_Params &sched_params)
   // has only been tested for POSIX 1003.1c threads, and may cause problems
   // with other PThreads flavors!
 
-  ACE_thread_t thr_id = ACE_OS::thr_self ();
   int result;
   struct sched_param param;
 
@@ -687,7 +646,7 @@ ACE_OS::sched_params (const ACE_Sched_Params &sched_params)
   if (sched_params.scope () == ACE_SCOPE_PROCESS)
     {
       ACE_OSCALL_RETURN (ACE_ADAPT_RETVAL (::sched_setscheduler (
-                                             thr_id,
+                                             0,    // this process
                                              sched_params.policy (),
                                              &param),
                                            result),
@@ -695,7 +654,7 @@ ACE_OS::sched_params (const ACE_Sched_Params &sched_params)
     }
   else if (sched_params.scope () == ACE_SCOPE_THREAD)
     {
-      param.sched_priority = sched_params.priority ();
+      ACE_thread_t thr_id = ACE_OS::thr_self ();
   
       ACE_OSCALL_RETURN (ACE_ADAPT_RETVAL (::pthread_setschedparam (
                                              thr_id,
@@ -711,6 +670,46 @@ ACE_OS::sched_params (const ACE_Sched_Params &sched_params)
     }
 
   return 0;
+#elif defined (ACE_WIN32)
+
+  if (sched_params.scope () != ACE_SCOPE_PROCESS  ||
+      sched_params.quantum () != ACE_Time_Value::zero)
+    {
+      // Win32 only allows setting priority class (therefore, policy)
+      // at the process level.  I don't know of a way to set the quantum.
+      errno = EINVAL;
+      return -1;
+    }
+
+  // Set the priority class of this process to the REALTIME process class
+  // _if_ the policy is ACE_SCHED_FIFO.  Otherwise, set to NORMAL.
+  if (! ::SetPriorityClass (
+          ::GetCurrentProcess (),
+          sched_params.policy () == ACE_SCHED_FIFO
+            ?  REALTIME_PRIORITY_CLASS
+            :  NORMAL_PRIORITY_CLASS))
+    {
+      return -1;
+    }
+
+  // Set the thread priority on the current thread.
+  return ACE_OS::thr_setprio (sched_params.priority ());
+
+#elif defined (VXWORKS)
+  // There is only one class of priorities on VxWorks, and no
+  // time quanta.  So, just set the current thread's priority.
+
+  if (sched_params.policy () != ACE_SCHED_FIFO  ||
+      sched_params.scope () != ACE_SCOPE_PROCESS  ||
+      sched_params.quantum () != ACE_Time_Value::zero)
+    {
+      errno = EINVAL;
+      return -1;
+    }
+
+  // Set the thread priority on the current thread.
+  return ACE_OS::thr_setprio (sched_params.priority ());
+
 #else
   ACE_NOTSUP_RETURN (ENOTSUP);
 #endif /* ACE_HAS_STHREADS */
diff --git a/ace/Sched_Params.cpp b/ace/Sched_Params.cpp
index 6524b8ef5e9..551c34285dd 100644
--- a/ace/Sched_Params.cpp
+++ b/ace/Sched_Params.cpp
@@ -56,8 +56,9 @@ ACE_Sched_Params::priority_min (const Policy policy)
         }
 
       // OK, now we've got the class ID in pcinfo.pc_cid.  In addition,
-      // the maximum configured real-time priority is in ((tsinfo_t *)
-      // pcinfo.pc_clinfo)->ts_maxupri.
+      // the maximum configured time-share priority is in ((tsinfo_t *)
+      // pcinfo.pc_clinfo)->ts_maxupri.  The minimum priority is just
+      // the negative of that.
 
       return -((tsinfo_t *) pcinfo.pc_clinfo)->ts_maxupri;
     }
@@ -144,6 +145,7 @@ ACE_Sched_Params::next_priority (const Policy policy, const int priority)
         return THREAD_PRIORITY_TIME_CRITICAL;
     }
 #elif defined (ACE_HAS_THREADS)
+  // including STHREADS, DCETHREADS, and PTHREADS
   const int max = priority_max (policy);
   return priority < max  ?  priority + 1  :  max;
 #elif
@@ -179,6 +181,7 @@ ACE_Sched_Params::previous_priority (const Policy policy,
         return THREAD_PRIORITY_HIGHEST;
     }
 #elif defined (ACE_HAS_THREADS)
+  // including STHREADS, DCETHREADS, and PTHREADS
   const int min = priority_min (policy);
   return priority > min  ?  priority - 1  :  min;
 #elif
diff --git a/ace/Sched_Params.h b/ace/Sched_Params.h
index 17b0f872b70..de58cd86744 100644
--- a/ace/Sched_Params.h
+++ b/ace/Sched_Params.h
@@ -24,25 +24,46 @@
 
 class ACE_Export ACE_Sched_Params
   // = TITLE
-  //    Container for thread scheduling-related parameters.
+  //    Container for scheduling-related parameters.
   //
   // = DESCRIPTION
   //    ACE_Sched_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.
+  //    ACE_OS::sched_params () to the OS to specify scheduling
+  //    parameters.  These parameters include scheduling policy,
+  //    such as FIFO, round-robin, or an implementation-defined
+  //    "OTHER" (to which many systems default); priority; and
+  //    a time-slice quantum for round-robin scheduling.
+  //    A "scope" parameter specifies whether the ACE_Sched_Params
+  //    applies to the current process, current lightweight process
+  //    (LWP) (on Solaris), or current thread.  Please see the "NOTE"
+  //    below about not all combinations of parameters being legal
+  //    on a particular platform.
+  //
+  //    For the case of thread priorities, it is intended that
+  //    ACE_OS::sched_params () usually 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
+  //    that's the default behavior 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.
   //
   //    NOTE:  this class does not do any checking of parameters.
   //    It is just a container class.  If it is constructed with values
   //    that are not supported on a platform, the call to
-  //    ACE_OS::set_sched_params () will fail by returning -1 with EINVAL
+  //    ACE_OS::sched_params () will fail by returning -1 with EINVAL
   //    (available through ACE_OS::last_error ()).
+
+  //    OS Scheduling parameters are complicated and often confusing.  Many
+  //    thanks to Thilo Kielmann <kielmann@informatik.uni-siegen.de> for his
+  //    careful review of this class design, thoughtful comments, and
+  //    assistance with implementation, especially for PTHREADS platforms.
+  //    Please don't blame him for anything about this class or
+  //    ACE_OS::sched_params () that you don't like or that isn't right;
+  //    the ACE Team, in particular David Levine <levine@cs.wustl.edu>
+  //    is fully responsible for that.  Please send any comments or
+  //    corrections to us.
 {
 public:
   typedef int Policy;
@@ -96,8 +117,8 @@ private:
   // Scheduling policy.
 
   ACE_Sched_Priority priority_;
-  // Default <priority_>: sets the priority to be used for newly
-  // spawned threads.
+  // Default <priority_>: for setting the priority for the process, LWP,
+  // or thread, as indicated by the scope_ parameter.
 
   int scope_;
   // <scope_> must one of the following:
@@ -110,6 +131,10 @@ private:
   //   ACE_SCOPE_THREAD: sets the scheduling policy for the thread,
   //     if the OS supports it, such as with Posix threads, and the
   //     thread priority.
+  // NOTE:  I don't think that these are the same as POSIX
+  //        contention scope.  POSIX users who are interested in,
+  //        and understand, contention scope will have to set it
+  //        by using system calls outside of ACE.
 
   ACE_Time_Value quantum_;
   // The <quantum_> is for time slicing.  An ACE_Time_Value of 0 has