doc/html/ref/kernel-thread-termination.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 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&nbsp;--&nbsp;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 &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_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 >