doc/html/ref/kernel-thread-priorities.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Thread priorities</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="The eCos Kernel"
  23 HREF="kernel.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Thread termination"
  26 HREF="kernel-thread-termination.html"><LINK
  27 REL="NEXT"
  28 TITLE="Per-thread data"
  29 HREF="kernel-thread-data.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="kernel-thread-termination.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="kernel-thread-data.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="KERNEL-THREAD-PRIORITIES">Thread priorities</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN616"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_thread_get_priority, cyg_thread_get_current_priority, cyg_thread_set_priority&nbsp;--&nbsp;Examine and manipulate thread priorities</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN621"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN622"><P
 100 ></P
 101 ><TABLE
 102 BORDER="5"
 103 BGCOLOR="#E0E0F0"
 104 WIDTH="70%"
 105 ><TR
 106 ><TD
 107 ><PRE
 108 CLASS="FUNCSYNOPSISINFO"
 109 >#include &lt;cyg/kernel/kapi.h&gt;
 110         </PRE
 111 ></TD
 112 ></TR
 113 ></TABLE
 114 ><P
 115 ><CODE
 116 ><CODE
 117 CLASS="FUNCDEF"
 118 >cyg_priority_t cyg_thread_get_priority</CODE
 119 >(cyg_handle_t thread);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >cyg_priority_t cyg_thread_get_current_priority</CODE
 126 >(cyg_handle_t thread);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >void cyg_thread_set_priority</CODE
 133 >(cyg_handle_t thread, cyg_priority_t priority);</CODE
 134 ></P
 135 ><P
 136 ></P
 137 ></DIV
 138 ></DIV
 139 ><DIV
 140 CLASS="REFSECT1"
 141 ><A
 142 NAME="AEN641"
 143 ></A
 144 ><H2
 145 >Description</H2
 146 ><P
 147 >Typical schedulers use the concept of a thread priority to determine
 148 which thread should run next. Exactly what this priority consists of
 149 will depend on the scheduler, but a typical implementation would be a
 150 small integer in the range 0 to 31, with 0 being the highest priority.
 151 Usually only the idle thread will run at the lowest priority. The
 152 exact number of priority levels available depends on the
 153 configuration, typically the option
 154 <TT
 155 CLASS="VARNAME"
 156 >CYGNUM_KERNEL_SCHED_PRIORITIES</TT
 157 >.
 158       </P
 159 ><P
 160 ><TT
 161 CLASS="FUNCTION"
 162 >cyg_thread_get_priority</TT
 163 > can be used to determine
 164 the priority of a thread, or more correctly the value last used in a
 165 <TT
 166 CLASS="FUNCTION"
 167 >cyg_thread_set_priority</TT
 168 > call or when the thread
 169 was first created. In some circumstances it is possible that the
 170 thread is actually running at a higher priority. For example, if it
 171 owns a mutex and priority ceilings or inheritance is being used to
 172 prevent priority inversion problems, then the thread's priority may
 173 have been boosted temporarily.
 174 <TT
 175 CLASS="FUNCTION"
 176 >cyg_thread_get_current_priority</TT
 177 > returns the real
 178 current priority.
 179       </P
 180 ><P
 181 >In many applications appropriate thread priorities can be determined
 182 and allocated statically. However, if it is necessary for a thread's
 183 priority to change at run-time then the
 184 <TT
 185 CLASS="FUNCTION"
 186 >cyg_thread_set_priority</TT
 187 > function provides this
 188 functionality.
 189       </P
 190 ></DIV
 191 ><DIV
 192 CLASS="REFSECT1"
 193 ><A
 194 NAME="KERNEL-THREAD-PRIORITIES-CONTEXT"
 195 ></A
 196 ><H2
 197 >Valid contexts</H2
 198 ><P
 199 ><TT
 200 CLASS="FUNCTION"
 201 >cyg_thread_get_priority</TT
 202 > and
 203 <TT
 204 CLASS="FUNCTION"
 205 >cyg_thread_get_current_priority</TT
 206 > can be called
 207 from thread or DSR context, although the latter is rarely useful.
 208 <TT
 209 CLASS="FUNCTION"
 210 >cyg_thread_set_priority</TT
 211 > should also only be
 212 called from thread context.
 213       </P
 214 ></DIV
 215 ><DIV
 216 CLASS="NAVFOOTER"
 217 ><HR
 218 ALIGN="LEFT"
 219 WIDTH="100%"><TABLE
 220 SUMMARY="Footer navigation table"
 221 WIDTH="100%"
 222 BORDER="0"
 223 CELLPADDING="0"
 224 CELLSPACING="0"
 225 ><TR
 226 ><TD
 227 WIDTH="33%"
 228 ALIGN="left"
 229 VALIGN="top"
 230 ><A
 231 HREF="kernel-thread-termination.html"
 232 ACCESSKEY="P"
 233 >Prev</A
 234 ></TD
 235 ><TD
 236 WIDTH="34%"
 237 ALIGN="center"
 238 VALIGN="top"
 239 ><A
 240 HREF="ecos-ref.html"
 241 ACCESSKEY="H"
 242 >Home</A
 243 ></TD
 244 ><TD
 245 WIDTH="33%"
 246 ALIGN="right"
 247 VALIGN="top"
 248 ><A
 249 HREF="kernel-thread-data.html"
 250 ACCESSKEY="N"
 251 >Next</A
 252 ></TD
 253 ></TR
 254 ><TR
 255 ><TD
 256 WIDTH="33%"
 257 ALIGN="left"
 258 VALIGN="top"
 259 >Thread termination</TD
 260 ><TD
 261 WIDTH="34%"
 262 ALIGN="center"
 263 VALIGN="top"
 264 ><A
 265 HREF="kernel.html"
 266 ACCESSKEY="U"
 267 >Up</A
 268 ></TD
 269 ><TD
 270 WIDTH="33%"
 271 ALIGN="right"
 272 VALIGN="top"
 273 >Per-thread data</TD
 274 ></TR
 275 ></TABLE
 276 ></DIV
 277 ></BODY
 278 ></HTML
 279 >