ACE/ace/Sched_Params.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Sched_Params.h
   6  *
   7  *  @author David Levine <levine@cs.wustl.edu>
   8  *  @author Carlos O'Ryan <coryan@uci.edu>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_SCHED_PARAMS_H
  13 #define ACE_SCHED_PARAMS_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Time_Value.h"
  23 #include "ace/OS_NS_Thread.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 /**
  28  * @class ACE_Sched_Params
  29  *
  30  * @brief Container for scheduling-related parameters.
  31  *
  32  * ACE_Sched_Params are passed via <ACE_OS::sched_params> to the
  33  * OS to specify scheduling parameters.  These parameters include
  34  * scheduling policy, such as FIFO (ACE_SCHED_FIFO), round-robin
  35  * (ACE_SCHED_RR), or an implementation-defined "OTHER"
  36  * (ACE_SCHED_OTHER), to which many systems default; priority;
  37  * and a time-slice quantum for round-robin scheduling.  A
  38  * "scope" parameter specifies whether the ACE_Sched_Params
  39  * applies to the current process, current lightweight process
  40  * (LWP) (on Solaris), or current thread.  Please see the "NOTE"
  41  * below about not all combinations of parameters being legal on
  42  * a particular platform.
  43  * For the case of thread priorities, it is intended that
  44  * <ACE_OS::sched_params> usually be called from <main> before
  45  * any threads have been spawned.  If spawned threads inherit
  46  * their parent's priority (I think that's the default behavior
  47  * for all of our platforms), then this sets the default base
  48  * priority.  Individual thread priorities can be adjusted as
  49  * usual using <ACE_OS::thr_prio> or via the ACE_Thread
  50  * interface.  See the parameter descriptions in the private:
  51  * section below.
  52  * @note This class does not do any checking of parameters.  It
  53  * is just a container class.  If it is constructed with values
  54  * that are not supported on a platform, the call to
  55  * <ACE_OS::sched_params> will fail by returning -1 with EINVAL
  56  * (available through <ACE_OS::last_error>).
  57  */
  58 class ACE_Export ACE_Sched_Params
  59 {
  60   //    NOTE: Solaris 2.5.x threads in the RT class must set the
  61   //    priority of their LWP.  The only way to do that through ACE is
  62   //    for the RT thread itself to call <ACE_OS::thr_setprio> with
  63   //    it's own priority.
  64
  65   //    OS Scheduling parameters are complicated and often confusing.
  66   //    Many thanks to Thilo Kielmann
  67   //    <kielmann@informatik.uni-siegen.de> for his careful review of
  68   //    this class design, thoughtful comments, and assistance with
  69   //    implementation, especially for PTHREADS platforms.  Please
  70   //    send any comments or corrections to the ACE developers.
  71 public:
  72   typedef int Policy;
  73
  74   /// Constructor.
  75   ACE_Sched_Params (const Policy policy,
  76                     const ACE_Sched_Priority priority,
  77                     const int scope = ACE_SCOPE_THREAD,
  78                     const ACE_Time_Value &quantum = ACE_Time_Value::zero);
  79
  80   /// Termination.
  81   ~ACE_Sched_Params (void);
  82
  83   // = Get/Set methods:
  84
  85   // = Get/Set policy
  86   Policy policy (void) const;
  87   void policy (const Policy);
  88
  89   // = Get/Set priority.
  90   ACE_Sched_Priority priority (void) const;
  91   void priority (const ACE_Sched_Priority);
  92
  93   // = Get/Set scope.
  94   int scope (void) const;
  95   void scope(const int);
  96
  97   // = Get/Set quantum.
  98   const ACE_Time_Value &quantum (void) const;
  99   void quantum (const ACE_Time_Value &);
 100
 101   // = Accessors for OS-specific priorities.
 102   // These return priority values for ACE_SCHED_OTHER if the Policy value
 103   // is invalid.
 104   static int priority_min (const Policy,
 105                            const int scope = ACE_SCOPE_THREAD);
 106   static int priority_max (const Policy,
 107                            const int scope = ACE_SCOPE_THREAD);
 108
 109   /**
 110    * The next higher priority.  "Higher" refers to scheduling priority,
 111    * not to the priority value itself.  (On some platforms, higher scheduling
 112    * priority is indicated by a lower priority value.)  If "priority" is
 113    * already the highest priority (for the specified policy), then it is
 114    * returned.
 115    */
 116   static int next_priority (const Policy,
 117                             const int priority,
 118                             const int scope = ACE_SCOPE_THREAD);
 119
 120   /**
 121    * The previous, lower priority.  "Lower" refers to scheduling priority,
 122    * not to the priority value itself.  (On some platforms, lower scheduling
 123    * priority is indicated by a higher priority value.)  If "priority" is
 124    * already the lowest priority (for the specified policy), then it is
 125    * returned.
 126    */
 127   static int previous_priority (const Policy,
 128                                 const int priority,
 129                                 const int scope = ACE_SCOPE_THREAD);
 130
 131 private:
 132   /// Scheduling policy.
 133   Policy policy_;
 134
 135   /// Default <priority_>: for setting the priority for the process, LWP,
 136   /// or thread, as indicated by the scope_ parameter.
 137   ACE_Sched_Priority priority_;
 138
 139   /**
 140    * <scope_> must be one of the following:
 141    *   ACE_SCOPE_PROCESS:  sets the scheduling policy for the
 142    *     process, and the process priority.  On some platforms,
 143    *     such as Win32, the scheduling policy can _only_ be
 144    *     set at process scope.
 145    *   ACE_SCOPE_LWP: lightweight process scope, only used with
 146    *     Solaris threads.
 147    *   ACE_SCOPE_THREAD: sets the scheduling policy for the thread,
 148    *     if the OS supports it, such as with Posix threads, and the
 149    *     thread priority.
 150    * NOTE:  I don't think that these are the same as POSIX
 151    *        contention scope.  POSIX users who are interested in,
 152    *        and understand, contention scope will have to set it
 153    *        by using system calls outside of ACE.
 154    */
 155   int scope_;
 156
 157   /**
 158    * The <quantum_> is for time slicing.  An ACE_Time_Value of 0 has
 159    * special significance: it means time-slicing is disabled; with
 160    * that, a thread that is running on a CPU will continue to run
 161    * until it blocks or is preempted.  Currently ignored if the OS
 162    * doesn't directly support time slicing, such as on VxWorks, or
 163    * setting the quantum (can that be done on Win32?).
 164    */
 165   ACE_Time_Value quantum_;
 166 };
 167
 168 /**
 169  * @class ACE_Sched_Priority_Iterator
 170  *
 171  * @brief An iterator over the OS-defined scheduling priorities.
 172  *
 173  * The order of priorities (numeric value vs. importance) is OS
 174  * dependant, it can be the case that the priorities are not even
 175  * contigous.  This class permits iteration over priorities using
 176  * the iterator pattern.
 177  */
 178 class ACE_Export ACE_Sched_Priority_Iterator
 179 {
 180 public:
 181   /// Initialize the iterator, the arguments define the scheduling
 182   /// policy and scope for the priorities (see ACE_Sched_Param).
 183   ACE_Sched_Priority_Iterator (const ACE_Sched_Params::Policy &policy,
 184                                int scope = ACE_SCOPE_THREAD);
 185
 186   /// Default dtor.
 187   ~ACE_Sched_Priority_Iterator (void);
 188
 189   /// Check if there are more priorities.
 190   int more (void) const;
 191
 192   /// Return the current priority.
 193   int priority (void) const;
 194
 195   /// Move to the next priority.
 196   /// The iteration is from lowest to highest importance.
 197   void next (void);
 198
 199   /// Accessor for the scheduling policy over which we are iterating.
 200   const ACE_Sched_Params::Policy &policy (void) const;
 201
 202   /// Accessor for the scheduling
 203   int scope (void) const;
 204
 205 private:
 206   /// The Scheduling policy (FIFO, RR, etc.) and scheduling scope
 207   /// (PROCESS, SYSTEM) we are iterating on.
 208   ACE_Sched_Params::Policy policy_;
 209   int scope_;
 210
 211   /// The current priority.
 212   int priority_;
 213
 214   /**
 215    * This is set to 1 when there are no more priorities. Cannot easily
 216    * compare against the highest priority on platforms were priorities
 217    * are non-contigous or descending.
 218    */
 219   int done_;
 220 };
 221
 222 ACE_END_VERSIONED_NAMESPACE_DECL
 223
 224 #if defined (__ACE_INLINE__)
 225 #include "ace/Sched_Params.inl"
 226 #endif /* __ACE_INLINE__ */
 227
 228 #include /**/ "ace/post.h"
 229 #endif /* ACE_SCHED_PARAMS_H */