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