doc/html/ref/kernel-thread-control.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 control</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 information"
  26 HREF="kernel-thread-info.html"><LINK
  27 REL="NEXT"
  28 TITLE="Thread termination"
  29 HREF="kernel-thread-termination.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-info.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-termination.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-CONTROL">Thread control</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN482"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_thread_yield, cyg_thread_delay, cyg_thread_suspend, cyg_thread_resume, cyg_thread_release&nbsp;--&nbsp;Control whether or not a thread is running</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN489"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN490"><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 >void cyg_thread_yield</CODE
 119 >(void);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void cyg_thread_delay</CODE
 126 >(cyg_tick_count_t delay);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >void cyg_thread_suspend</CODE
 133 >(cyg_handle_t thread);</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >void cyg_thread_resume</CODE
 140 >(cyg_handle_t thread);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void cyg_thread_release</CODE
 147 >(cyg_handle_t thread);</CODE
 148 ></P
 149 ><P
 150 ></P
 151 ></DIV
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="AEN516"
 157 ></A
 158 ><H2
 159 >Description</H2
 160 ><P
 161 >These functions provide some control over whether or not a particular
 162 thread can run. Apart from the required use of
 163 <TT
 164 CLASS="FUNCTION"
 165 >cyg_thread_resume</TT
 166 > to start a newly-created
 167 thread, application code should normally use proper synchronization
 168 primitives such as condition variables or mail boxes.
 169       </P
 170 ></DIV
 171 ><DIV
 172 CLASS="REFSECT1"
 173 ><A
 174 NAME="AEN520"
 175 ></A
 176 ><H2
 177 >Yield</H2
 178 ><P
 179 ><TT
 180 CLASS="FUNCTION"
 181 >cyg_thread_yield</TT
 182 > allows a thread to relinquish
 183 control of the processor to some other runnable thread which has the
 184 same priority. This can have no effect on any higher-priority thread
 185 since, if such a thread were runnable, the current thread would have
 186 been preempted in its favour. Similarly it can have no effect on any
 187 lower-priority thread because the current thread will always be run in
 188 preference to those. As a consequence this function is only useful
 189 in configurations with a scheduler that allows multiple threads to run
 190 at the same priority, for example the mlqueue scheduler. If instead
 191 the bitmap scheduler was being used then
 192 <TT
 193 CLASS="FUNCTION"
 194 >cyg_thread_yield()</TT
 195 > would serve no purpose.
 196       </P
 197 ><P
 198 >Even if a suitable scheduler such as the mlqueue scheduler has been
 199 configured, <TT
 200 CLASS="FUNCTION"
 201 >cyg_thread_yield</TT
 202 > will still rarely
 203 prove useful: instead timeslicing will be used to ensure that all
 204 threads of a given priority get a fair slice of the available
 205 processor time. However it is possible to disable timeslicing via the
 206 configuration option <TT
 207 CLASS="VARNAME"
 208 >CYGSEM_KERNEL_SCHED_TIMESLICE</TT
 209 >,
 210 in which case <TT
 211 CLASS="FUNCTION"
 212 >cyg_thread_yield</TT
 213 > can be used to
 214 implement a form of cooperative multitasking.
 215       </P
 216 ></DIV
 217 ><DIV
 218 CLASS="REFSECT1"
 219 ><A
 220 NAME="AEN529"
 221 ></A
 222 ><H2
 223 >Delay</H2
 224 ><P
 225 ><TT
 226 CLASS="FUNCTION"
 227 >cyg_thread_delay</TT
 228 > allows a thread to suspend until
 229 the specified number of clock ticks have occurred. For example, if a
 230 value of 1 is used and the system clock runs at a frequency of 100Hz
 231 then the thread will sleep for up to 10 milliseconds. This
 232 functionality depends on the presence of a real-time system clock, as
 233 controlled by the configuration option
 234 <TT
 235 CLASS="VARNAME"
 236 >CYGVAR_KERNEL_COUNTERS_CLOCK</TT
 237 >.
 238       </P
 239 ><P
 240 >If the application requires delays measured in milliseconds or similar
 241 units rather than in clock ticks, some calculations are needed to
 242 convert between these units as described in <A
 243 HREF="kernel-clocks.html"
 244 >Clocks</A
 245 >. Usually these calculations can be done by
 246 the application developer, or at compile-time. Performing such
 247 calculations prior to every call to
 248 <TT
 249 CLASS="FUNCTION"
 250 >cyg_thread_delay</TT
 251 > adds unnecessary overhead to the
 252 system.
 253       </P
 254 ></DIV
 255 ><DIV
 256 CLASS="REFSECT1"
 257 ><A
 258 NAME="AEN537"
 259 ></A
 260 ><H2
 261 >Suspend and Resume</H2
 262 ><P
 263 >Associated with each thread is a suspend counter. When a thread is
 264 first created this counter is initialized to 1.
 265 <TT
 266 CLASS="FUNCTION"
 267 >cyg_thread_suspend</TT
 268 > can be used to increment the
 269 suspend counter, and <TT
 270 CLASS="FUNCTION"
 271 >cyg_thread_resume</TT
 272 > decrements
 273 it. The scheduler will never run a thread with a non-zero suspend
 274 counter. Therefore a newly created thread will not run until it has
 275 been resumed.
 276       </P
 277 ><P
 278 >An occasional problem with the use of suspend and resume functionality
 279 is that a thread gets suspended more times than it is resumed and
 280 hence never becomes runnable again. This can lead to very confusing
 281 behaviour. To help with debugging such problems the kernel provides a
 282 configuration option
 283 <TT
 284 CLASS="VARNAME"
 285 >CYGNUM_KERNEL_MAX_SUSPEND_COUNT_ASSERT</TT
 286 > which
 287 imposes an upper bound on the number of suspend calls without matching
 288 resumes, with a reasonable default value. This functionality depends
 289 on infrastructure assertions being enabled.
 290       </P
 291 ></DIV
 292 ><DIV
 293 CLASS="REFSECT1"
 294 ><A
 295 NAME="AEN544"
 296 ></A
 297 ><H2
 298 >Releasing a Blocked Thread</H2
 299 ><P
 300 >When a thread is blocked on a synchronization primitive such as a
 301 semaphore or a mutex, or when it is waiting for an alarm to trigger,
 302 it can be forcibly woken up using
 303 <TT
 304 CLASS="FUNCTION"
 305 >cyg_thread_release</TT
 306 >. Typically this will call the
 307 affected synchronization primitive to return false, indicating that
 308 the operation was not completed successfully. This function has to be
 309 used with great care, and in particular it should only be used on
 310 threads that have been designed appropriately and check all return
 311 codes. If instead it were to be used on, say, an arbitrary thread that
 312 is attempting to claim a mutex then that thread might not bother to
 313 check the result of the mutex lock operation - usually there would be
 314 no reason to do so. Therefore the thread will now continue running in
 315 the false belief that it has successfully claimed a mutex lock, and
 316 the resulting behaviour is undefined. If the system has been built
 317 with assertions enabled then it is possible that an assertion will
 318 trigger when the thread tries to release the mutex it does not
 319 actually own.
 320       </P
 321 ><P
 322 >The main use of <TT
 323 CLASS="FUNCTION"
 324 >cyg_thread_release</TT
 325 > is in the
 326 POSIX compatibility layer, where it is used in the implementation of
 327 per-thread signals and cancellation handlers.
 328       </P
 329 ></DIV
 330 ><DIV
 331 CLASS="REFSECT1"
 332 ><A
 333 NAME="KERNEL-THREAD-CONTROL-CONTEXT"
 334 ></A
 335 ><H2
 336 >Valid contexts</H2
 337 ><P
 338 ><TT
 339 CLASS="FUNCTION"
 340 >cyg_thread_yield</TT
 341 > can only be called from thread
 342 context, A DSR must always run to completion and cannot yield the
 343 processor to some thread. <TT
 344 CLASS="FUNCTION"
 345 >cyg_thread_suspend</TT
 346 >,
 347 <TT
 348 CLASS="FUNCTION"
 349 >cyg_thread_resume</TT
 350 >, and
 351 <TT
 352 CLASS="FUNCTION"
 353 >cyg_thread_release</TT
 354 > may be called from thread or
 355 DSR context.
 356       </P
 357 ></DIV
 358 ><DIV
 359 CLASS="NAVFOOTER"
 360 ><HR
 361 ALIGN="LEFT"
 362 WIDTH="100%"><TABLE
 363 SUMMARY="Footer navigation table"
 364 WIDTH="100%"
 365 BORDER="0"
 366 CELLPADDING="0"
 367 CELLSPACING="0"
 368 ><TR
 369 ><TD
 370 WIDTH="33%"
 371 ALIGN="left"
 372 VALIGN="top"
 373 ><A
 374 HREF="kernel-thread-info.html"
 375 ACCESSKEY="P"
 376 >Prev</A
 377 ></TD
 378 ><TD
 379 WIDTH="34%"
 380 ALIGN="center"
 381 VALIGN="top"
 382 ><A
 383 HREF="ecos-ref.html"
 384 ACCESSKEY="H"
 385 >Home</A
 386 ></TD
 387 ><TD
 388 WIDTH="33%"
 389 ALIGN="right"
 390 VALIGN="top"
 391 ><A
 392 HREF="kernel-thread-termination.html"
 393 ACCESSKEY="N"
 394 >Next</A
 395 ></TD
 396 ></TR
 397 ><TR
 398 ><TD
 399 WIDTH="33%"
 400 ALIGN="left"
 401 VALIGN="top"
 402 >Thread information</TD
 403 ><TD
 404 WIDTH="34%"
 405 ALIGN="center"
 406 VALIGN="top"
 407 ><A
 408 HREF="kernel.html"
 409 ACCESSKEY="U"
 410 >Up</A
 411 ></TD
 412 ><TD
 413 WIDTH="33%"
 414 ALIGN="right"
 415 VALIGN="top"
 416 >Thread termination</TD
 417 ></TR
 418 ></TABLE
 419 ></DIV
 420 ></BODY
 421 ></HTML
 422 >