OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-thread-control.html] - Blame information for rev 598

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.