doc/html/ref/kernel-thread-destructors.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 destructors</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="Per-thread data"
  26 HREF="kernel-thread-data.html"><LINK
  27 REL="NEXT"
  28 TITLE="Exception handling"
  29 HREF="kernel-exceptions.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-data.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-exceptions.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-DESTRUCTORS">Thread destructors</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN730"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_thread_add_destructor, cyg_thread_rem_destructor&nbsp;--&nbsp;Call functions on thread termination</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN734"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN735"><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 typedef void (*<SPAN
 111 CLASS="TYPE"
 112 >cyg_thread_destructor_fn</SPAN
 113 >)(<SPAN
 114 CLASS="TYPE"
 115 >cyg_addrword_t</SPAN
 116 >);
 117         </PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >cyg_bool_t cyg_thread_add_destructor</CODE
 126 >(cyg_thread_destructor_fn fn, cyg_addrword_t data);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >cyg_bool_t cyg_thread_rem_destructor</CODE
 133 >(cyg_thread_destructor_fn fn, cyg_addrword_t data);</CODE
 134 ></P
 135 ><P
 136 ></P
 137 ></DIV
 138 ></DIV
 139 ><DIV
 140 CLASS="REFSECT1"
 141 ><A
 142 NAME="AEN753"
 143 ></A
 144 ><H2
 145 >Description</H2
 146 ><P
 147 >These functions are provided for cases when an application requires a
 148 function to be automatically called when a thread exits. This is often
 149 useful when, for example, freeing up resources allocated by the thread.
 150       </P
 151 ><P
 152 >This support must be enabled with the configuration option
 153 <TT
 154 CLASS="VARNAME"
 155 >CYGPKG_KERNEL_THREADS_DESTRUCTORS</TT
 156 >. When enabled,
 157 you may register a function of type
 158 <SPAN
 159 CLASS="TYPE"
 160 >cyg_thread_destructor_fn</SPAN
 161 > to be called on thread
 162 termination using <TT
 163 CLASS="FUNCTION"
 164 >cyg_thread_add_destructor</TT
 165 >. You
 166 may also provide it with a piece of arbitrary information in the
 167 <TT
 168 CLASS="PARAMETER"
 169 ><I
 170 >data</I
 171 ></TT
 172 > argument which will be passed to the
 173 destructor function <TT
 174 CLASS="PARAMETER"
 175 ><I
 176 >fn</I
 177 ></TT
 178 > when the thread
 179 terminates. If you no longer wish to call a function previous
 180 registered with <TT
 181 CLASS="FUNCTION"
 182 >cyg_thread_add_destructor</TT
 183 >, you
 184 may call <TT
 185 CLASS="FUNCTION"
 186 >cyg_thread_rem_destructor</TT
 187 > with the same
 188 parameters used to register the destructor function. Both these
 189 functions return <TT
 190 CLASS="LITERAL"
 191 >true</TT
 192 > on success and
 193 <TT
 194 CLASS="LITERAL"
 195 >false</TT
 196 > on failure.
 197       </P
 198 ><P
 199 >By default, thread destructors are per-thread, which means that registering
 200 a destructor function only registers that function for the current thread.
 201 In other words, each thread has its own list of destructors.
 202 Alternatively you may disable the configuration option
 203 <TT
 204 CLASS="VARNAME"
 205 >CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</TT
 206 > in which
 207 case any registered destructors will be run when <SPAN
 208 CLASS="emphasis"
 209 ><I
 210 CLASS="EMPHASIS"
 211 >any</I
 212 ></SPAN
 213 >
 214 threads exit. In other words, the thread destructor list is global and all
 215 threads have the same destructors.
 216       </P
 217 ><P
 218 >There is a limit to the number of destructors which may be registered,
 219 which can be controlled with the
 220 <TT
 221 CLASS="VARNAME"
 222 >CYGNUM_KERNEL_THREADS_DESTRUCTORS</TT
 223 > configuration
 224 option. Increasing this value will very slightly increase the amount
 225 of memory in use, and when
 226 <TT
 227 CLASS="VARNAME"
 228 >CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</TT
 229 > is
 230 enabled, the amount of memory used per thread will increase. When the
 231 limit has been reached, <TT
 232 CLASS="FUNCTION"
 233 >cyg_thread_add_destructor</TT
 234 >
 235 will return <TT
 236 CLASS="LITERAL"
 237 >false</TT
 238 >.
 239       </P
 240 ></DIV
 241 ><DIV
 242 CLASS="REFSECT1"
 243 ><A
 244 NAME="KERNEL-THREAD-DESTRUCTORS-CONTEXT"
 245 ></A
 246 ><H2
 247 >Valid contexts</H2
 248 ><P
 249 >When <TT
 250 CLASS="VARNAME"
 251 >CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</TT
 252 >
 253 is enabled, these functions must only be called from a thread context
 254 as they implicitly operate on the current thread. When
 255 <TT
 256 CLASS="VARNAME"
 257 >CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</TT
 258 > is
 259 disabled, these functions may be called from thread or DSR context,
 260 or at initialization time.
 261       </P
 262 ></DIV
 263 ><DIV
 264 CLASS="NAVFOOTER"
 265 ><HR
 266 ALIGN="LEFT"
 267 WIDTH="100%"><TABLE
 268 SUMMARY="Footer navigation table"
 269 WIDTH="100%"
 270 BORDER="0"
 271 CELLPADDING="0"
 272 CELLSPACING="0"
 273 ><TR
 274 ><TD
 275 WIDTH="33%"
 276 ALIGN="left"
 277 VALIGN="top"
 278 ><A
 279 HREF="kernel-thread-data.html"
 280 ACCESSKEY="P"
 281 >Prev</A
 282 ></TD
 283 ><TD
 284 WIDTH="34%"
 285 ALIGN="center"
 286 VALIGN="top"
 287 ><A
 288 HREF="ecos-ref.html"
 289 ACCESSKEY="H"
 290 >Home</A
 291 ></TD
 292 ><TD
 293 WIDTH="33%"
 294 ALIGN="right"
 295 VALIGN="top"
 296 ><A
 297 HREF="kernel-exceptions.html"
 298 ACCESSKEY="N"
 299 >Next</A
 300 ></TD
 301 ></TR
 302 ><TR
 303 ><TD
 304 WIDTH="33%"
 305 ALIGN="left"
 306 VALIGN="top"
 307 >Per-thread data</TD
 308 ><TD
 309 WIDTH="34%"
 310 ALIGN="center"
 311 VALIGN="top"
 312 ><A
 313 HREF="kernel.html"
 314 ACCESSKEY="U"
 315 >Up</A
 316 ></TD
 317 ><TD
 318 WIDTH="33%"
 319 ALIGN="right"
 320 VALIGN="top"
 321 >Exception handling</TD
 322 ></TR
 323 ></TABLE
 324 ></DIV
 325 ></BODY
 326 ></HTML
 327 >