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

Subversion Repositories openrisc

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

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


<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
><HEAD
><TITLE
>Thread termination</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="The eCos Kernel"
HREF="kernel.html"><LINK
REL="PREVIOUS"
TITLE="Thread control"
HREF="kernel-thread-control.html"><LINK
REL="NEXT"
TITLE="Thread priorities"
HREF="kernel-thread-priorities.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="kernel-thread-control.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="kernel-thread-priorities.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="KERNEL-THREAD-TERMINATION">Thread termination</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN560"
></A
><H2
>Name</H2
>cyg_thread_exit, cyg_thread_kill, cyg_thread_delete&nbsp;--&nbsp;Allow threads to terminate</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN565"><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN566"><P
></P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;cyg/kernel/kapi.h&gt;
        </PRE
></TD
></TR
></TABLE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_thread_exit</CODE
>(void);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_thread_kill</CODE
>(cyg_handle_t thread);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void cyg_thread_delete</CODE
>(cyg_handle_t thread);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN582"
></A
><H2
>Description</H2
><P
>In many embedded systems the various threads are allocated statically,
created during initialization, and never need to terminate. This
avoids any need for dynamic memory allocation or other resource
management facilities. However if a given application does have a
requirement that some threads be created dynamically, must terminate,
and their resources such as the stack be reclaimed, then the kernel
provides the functions <TT
CLASS="FUNCTION"
>cyg_thread_exit</TT
>,
<TT
CLASS="FUNCTION"
>cyg_thread_kill</TT
>, and
<TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
>.
      </P
><P
><TT
CLASS="FUNCTION"
>cyg_thread_exit</TT
> allows a thread to terminate
itself, thus ensuring that it will not be run again by the scheduler.
However the <SPAN
CLASS="STRUCTNAME"
>cyg_thread</SPAN
> data structure passed
to <TT
CLASS="FUNCTION"
>cyg_thread_create</TT
> remains in use, and the
handle returned by <TT
CLASS="FUNCTION"
>cyg_thread_create</TT
> remains
valid. This allows other threads to perform certain operations on the
terminated thread, for example to determine its stack usage via
<TT
CLASS="FUNCTION"
>cyg_thread_measure_stack_usage</TT
>. When the handle
and <SPAN
CLASS="STRUCTNAME"
>cyg_thread</SPAN
> structure are no longer
required, <TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
> should be called to
release these resources. If the stack was dynamically allocated then
this should not be freed until after the call to
<TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
>.
      </P
><P
>Alternatively, one thread may use <TT
CLASS="FUNCTION"
>cyg_thread_kill</TT
>
on another This has much the same effect as the affected thread
calling <TT
CLASS="FUNCTION"
>cyg_thread_exit</TT
>. However killing a thread
is generally rather dangerous because no attempt is made to unlock any
synchronization primitives currently owned by that thread or release
any other resources that thread may have claimed. Therefore use of
this function should be avoided, and
<TT
CLASS="FUNCTION"
>cyg_thread_exit</TT
> is preferred.
<TT
CLASS="FUNCTION"
>cyg_thread_kill</TT
> cannot be used by a thread to
kill itself.
      </P
><P
><TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
> should be used on a thread
after it has exited and is no longer required. After this call the
thread handle is no longer valid, and both the
<SPAN
CLASS="STRUCTNAME"
>cyg_thread</SPAN
> structure and the thread stack can
be re-used or freed. If <TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
> is
invoked on a thread that is still running then there is an implicit
call to <TT
CLASS="FUNCTION"
>cyg_thread_kill</TT
>.
      </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="KERNEL-THREAD-TERMINATION-CONTEXT"
></A
><H2
>Valid contexts</H2
><P
><TT
CLASS="FUNCTION"
>cyg_thread_exit</TT
>,
<TT
CLASS="FUNCTION"
>cyg_thread_kill</TT
> and
<TT
CLASS="FUNCTION"
>cyg_thread_delete</TT
> can only be called from thread
context.
      </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="kernel-thread-control.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="kernel-thread-priorities.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Thread control</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="kernel.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Thread priorities</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>

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 termination</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 control"`
26			`HREF="kernel-thread-control.html"><LINK`
27			`REL="NEXT"`
28			`TITLE="Thread priorities"`
29			`HREF="kernel-thread-priorities.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-control.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-priorities.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-TERMINATION">Thread termination</H1`
83			`><DIV`
84			`CLASS="REFNAMEDIV"`
85			`><A`
86			`NAME="AEN560"`
87			`></A`
88			`><H2`
89			`>Name</H2`
90			`>cyg_thread_exit, cyg_thread_kill, cyg_thread_delete -- Allow threads to terminate</DIV`
91			`><DIV`
92			`CLASS="REFSYNOPSISDIV"`
93			`><A`
94			`NAME="AEN565"><H2`
95			`>Synopsis</H2`
96			`><DIV`
97			`CLASS="FUNCSYNOPSIS"`
98			`><A`
99			`NAME="AEN566"><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 <cyg/kernel/kapi.h>`
110			`</PRE`
111			`></TD`
112			`></TR`
113			`></TABLE`
114			`><P`
115			`><CODE`
116			`><CODE`
117			`CLASS="FUNCDEF"`
118			`>void cyg_thread_exit</CODE`
119			`>(void);</CODE`
120			`></P`
121			`><P`
122			`><CODE`
123			`><CODE`
124			`CLASS="FUNCDEF"`
125			`>void cyg_thread_kill</CODE`
126			`>(cyg_handle_t thread);</CODE`
127			`></P`
128			`><P`
129			`><CODE`
130			`><CODE`
131			`CLASS="FUNCDEF"`
132			`>void cyg_thread_delete</CODE`
133			`>(cyg_handle_t thread);</CODE`
134			`></P`
135			`><P`
136			`></P`
137			`></DIV`
138			`></DIV`
139			`><DIV`
140			`CLASS="REFSECT1"`
141			`><A`
142			`NAME="AEN582"`
143			`></A`
144			`><H2`
145			`>Description</H2`
146			`><P`
147			`>In many embedded systems the various threads are allocated statically,`
148			`created during initialization, and never need to terminate. This`
149			`avoids any need for dynamic memory allocation or other resource`
150			`management facilities. However if a given application does have a`
151			`requirement that some threads be created dynamically, must terminate,`
152			`and their resources such as the stack be reclaimed, then the kernel`
153			`provides the functions <TT`
154			`CLASS="FUNCTION"`
155			`>cyg_thread_exit</TT`
156			`>,`
157			`<TT`
158			`CLASS="FUNCTION"`
159			`>cyg_thread_kill</TT`
160			`>, and`
161			`<TT`
162			`CLASS="FUNCTION"`
163			`>cyg_thread_delete</TT`
164			`>.`
165			`</P`
166			`><P`
167			`><TT`
168			`CLASS="FUNCTION"`
169			`>cyg_thread_exit</TT`
170			`> allows a thread to terminate`
171			`itself, thus ensuring that it will not be run again by the scheduler.`
172			`However the <SPAN`
173			`CLASS="STRUCTNAME"`
174			`>cyg_thread</SPAN`
175			`> data structure passed`
176			`to <TT`
177			`CLASS="FUNCTION"`
178			`>cyg_thread_create</TT`
179			`> remains in use, and the`
180			`handle returned by <TT`
181			`CLASS="FUNCTION"`
182			`>cyg_thread_create</TT`
183			`> remains`
184			`valid. This allows other threads to perform certain operations on the`
185			`terminated thread, for example to determine its stack usage via`
186			`<TT`
187			`CLASS="FUNCTION"`
188			`>cyg_thread_measure_stack_usage</TT`
189			`>. When the handle`
190			`and <SPAN`
191			`CLASS="STRUCTNAME"`
192			`>cyg_thread</SPAN`
193			`> structure are no longer`
194			`required, <TT`
195			`CLASS="FUNCTION"`
196			`>cyg_thread_delete</TT`
197			`> should be called to`
198			`release these resources. If the stack was dynamically allocated then`
199			`this should not be freed until after the call to`
200			`<TT`
201			`CLASS="FUNCTION"`
202			`>cyg_thread_delete</TT`
203			`>.`
204			`</P`
205			`><P`
206			`>Alternatively, one thread may use <TT`
207			`CLASS="FUNCTION"`
208			`>cyg_thread_kill</TT`
209			`>`
210			`on another This has much the same effect as the affected thread`
211			`calling <TT`
212			`CLASS="FUNCTION"`
213			`>cyg_thread_exit</TT`
214			`>. However killing a thread`
215			`is generally rather dangerous because no attempt is made to unlock any`
216			`synchronization primitives currently owned by that thread or release`
217			`any other resources that thread may have claimed. Therefore use of`
218			`this function should be avoided, and`
219			`<TT`
220			`CLASS="FUNCTION"`
221			`>cyg_thread_exit</TT`
222			`> is preferred.`
223			`<TT`
224			`CLASS="FUNCTION"`
225			`>cyg_thread_kill</TT`
226			`> cannot be used by a thread to`
227			`kill itself.`
228			`</P`
229			`><P`
230			`><TT`
231			`CLASS="FUNCTION"`
232			`>cyg_thread_delete</TT`
233			`> should be used on a thread`
234			`after it has exited and is no longer required. After this call the`
235			`thread handle is no longer valid, and both the`
236			`<SPAN`
237			`CLASS="STRUCTNAME"`
238			`>cyg_thread</SPAN`
239			`> structure and the thread stack can`
240			`be re-used or freed. If <TT`
241			`CLASS="FUNCTION"`
242			`>cyg_thread_delete</TT`
243			`> is`
244			`invoked on a thread that is still running then there is an implicit`
245			`call to <TT`
246			`CLASS="FUNCTION"`
247			`>cyg_thread_kill</TT`
248			`>.`
249			`</P`
250			`></DIV`
251			`><DIV`
252			`CLASS="REFSECT1"`
253			`><A`
254			`NAME="KERNEL-THREAD-TERMINATION-CONTEXT"`
255			`></A`
256			`><H2`
257			`>Valid contexts</H2`
258			`><P`
259			`><TT`
260			`CLASS="FUNCTION"`
261			`>cyg_thread_exit</TT`
262			`>,`
263			`<TT`
264			`CLASS="FUNCTION"`
265			`>cyg_thread_kill</TT`
266			`> and`
267			`<TT`
268			`CLASS="FUNCTION"`
269			`>cyg_thread_delete</TT`
270			`> can only be called from thread`
271			`context.`
272			`</P`
273			`></DIV`
274			`><DIV`
275			`CLASS="NAVFOOTER"`
276			`><HR`
277			`ALIGN="LEFT"`
278			`WIDTH="100%"><TABLE`
279			`SUMMARY="Footer navigation table"`
280			`WIDTH="100%"`
281			`BORDER="0"`
282			`CELLPADDING="0"`
283			`CELLSPACING="0"`
284			`><TR`
285			`><TD`
286			`WIDTH="33%"`
287			`ALIGN="left"`
288			`VALIGN="top"`
289			`><A`
290			`HREF="kernel-thread-control.html"`
291			`ACCESSKEY="P"`
292			`>Prev</A`
293			`></TD`
294			`><TD`
295			`WIDTH="34%"`
296			`ALIGN="center"`
297			`VALIGN="top"`
298			`><A`
299			`HREF="ecos-ref.html"`
300			`ACCESSKEY="H"`
301			`>Home</A`
302			`></TD`
303			`><TD`
304			`WIDTH="33%"`
305			`ALIGN="right"`
306			`VALIGN="top"`
307			`><A`
308			`HREF="kernel-thread-priorities.html"`
309			`ACCESSKEY="N"`
310			`>Next</A`
311			`></TD`
312			`></TR`
313			`><TR`
314			`><TD`
315			`WIDTH="33%"`
316			`ALIGN="left"`
317			`VALIGN="top"`
318			`>Thread control</TD`
319			`><TD`
320			`WIDTH="34%"`
321			`ALIGN="center"`
322			`VALIGN="top"`
323			`><A`
324			`HREF="kernel.html"`
325			`ACCESSKEY="U"`
326			`>Up</A`
327			`></TD`
328			`><TD`
329			`WIDTH="33%"`
330			`ALIGN="right"`
331			`VALIGN="top"`
332			`>Thread priorities</TD`
333			`></TR`
334			`></TABLE`
335			`></DIV`
336			`></BODY`
337			`></HTML`
338			`>`

Browse

Tools

Subversion Repositories openrisc

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