doc/html/ref/kernel-thread-data.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 >Per-thread data</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 priorities"
  26 HREF="kernel-thread-priorities.html"><LINK
  27 REL="NEXT"
  28 TITLE="Thread destructors"
  29 HREF="kernel-thread-destructors.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-priorities.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-destructors.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-DATA">Per-thread data</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN660"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data&nbsp;--&nbsp;Manipulate per-thread data</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN667"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN668"><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 >cyg_ucount32 cyg_thread_new_data_index</CODE
 119 >(void);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void cyg_thread_free_data_index</CODE
 126 >(cyg_ucount32 index);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >cyg_addrword_t cyg_thread_get_data</CODE
 133 >(cyg_ucount32 index);</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >cyg_addrword_t* cyg_thread_get_data_ptr</CODE
 140 >(cyg_ucount32 index);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void cyg_thread_set_data</CODE
 147 >(cyg_ucount32 index, cyg_addrword_t data);</CODE
 148 ></P
 149 ><P
 150 ></P
 151 ></DIV
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="AEN696"
 157 ></A
 158 ><H2
 159 >Description</H2
 160 ><P
 161 >In some applications and libraries it is useful to have some data that
 162 is specific to each thread. For example, many of the functions in the
 163 POSIX compatibility package return -1 to indicate an error and store
 164 additional information in what appears to be a global variable
 165 <TT
 166 CLASS="VARNAME"
 167 >errno</TT
 168 >. However, if multiple threads make concurrent
 169 calls into the POSIX library and if <TT
 170 CLASS="VARNAME"
 171 >errno</TT
 172 > were
 173 really a global variable then a thread would have no way of knowing
 174 whether the current <TT
 175 CLASS="VARNAME"
 176 >errno</TT
 177 > value really corresponded
 178 to the last POSIX call it made, or whether some other thread had run
 179 in the meantime and made a different POSIX call which updated the
 180 variable. To avoid such confusion <TT
 181 CLASS="VARNAME"
 182 >errno</TT
 183 > is instead
 184 implemented as a per-thread variable, and each thread has its own
 185 instance.
 186       </P
 187 ><P
 188 >The support for per-thread data can be disabled via the configuration
 189 option <TT
 190 CLASS="VARNAME"
 191 >CYGVAR_KERNEL_THREADS_DATA</TT
 192 >. If enabled, each
 193 <SPAN
 194 CLASS="STRUCTNAME"
 195 >cyg_thread</SPAN
 196 > data structure holds a small array
 197 of words. The size of this array is determined by the configuration
 198 option <TT
 199 CLASS="VARNAME"
 200 >CYGNUM_KERNEL_THREADS_DATA_MAX</TT
 201 >. When a
 202 thread is created the array is filled with zeroes.
 203       </P
 204 ><P
 205 >If an application needs to use per-thread data then it needs an index
 206 into this array which has not yet been allocated to other code. This
 207 index can be obtained by calling
 208 <TT
 209 CLASS="FUNCTION"
 210 >cyg_thread_new_data_index</TT
 211 >, and then used in
 212 subsequent calls to <TT
 213 CLASS="FUNCTION"
 214 >cyg_thread_get_data</TT
 215 >.
 216 Typically indices are allocated during system initialization and
 217 stored in static variables. If for some reason a slot in the array is
 218 no longer required and can be re-used then it can be released by calling
 219 <TT
 220 CLASS="FUNCTION"
 221 >cyg_thread_free_data_index</TT
 222 >,
 223       </P
 224 ><P
 225 >The current per-thread data in a given slot can be obtained using
 226 <TT
 227 CLASS="FUNCTION"
 228 >cyg_thread_get_data</TT
 229 >. This implicitly operates on
 230 the current thread, and its single argument should be an index as
 231 returned by <TT
 232 CLASS="FUNCTION"
 233 >cyg_thread_new_data_index</TT
 234 >. The
 235 per-thread data can be updated using
 236 <TT
 237 CLASS="FUNCTION"
 238 >cyg_thread_set_data</TT
 239 >. If a particular item of
 240 per-thread data is needed repeatedly then
 241 <TT
 242 CLASS="FUNCTION"
 243 >cyg_thread_get_data_ptr</TT
 244 > can be used to obtain the
 245 address of the data, and indirecting through this pointer allows the
 246 data to be examined and updated efficiently.
 247       </P
 248 ><P
 249 >Some packages, for example the error and POSIX packages, have
 250 pre-allocated slots in the array of per-thread data. These slots
 251 should not normally be used by application code, and instead slots
 252 should be allocated during initialization by a call to
 253 <TT
 254 CLASS="FUNCTION"
 255 >cyg_thread_new_data_index</TT
 256 >. If it is known that,
 257 for example, the configuration will never include the POSIX
 258 compatibility package then application code may instead decide to
 259 re-use the slot allocated to that package,
 260 <TT
 261 CLASS="VARNAME"
 262 >CYGNUM_KERNEL_THREADS_DATA_POSIX</TT
 263 >, but obviously
 264 this does involve a risk of strange and subtle bugs if the
 265 application's requirements ever change.
 266       </P
 267 ></DIV
 268 ><DIV
 269 CLASS="REFSECT1"
 270 ><A
 271 NAME="KERNEL-THREAD-DATA-CONTEXT"
 272 ></A
 273 ><H2
 274 >Valid contexts</H2
 275 ><P
 276 >Typically <TT
 277 CLASS="FUNCTION"
 278 >cyg_thread_new_data_index</TT
 279 > is only
 280 called during initialization, but may also be called at any time in
 281 thread context. <TT
 282 CLASS="FUNCTION"
 283 >cyg_thread_free_data_index</TT
 284 >, if
 285 used at all, can also be called during initialization or from thread
 286 context. <TT
 287 CLASS="FUNCTION"
 288 >cyg_thread_get_data</TT
 289 >,
 290 <TT
 291 CLASS="FUNCTION"
 292 >cyg_thread_get_data_ptr</TT
 293 >, and
 294 <TT
 295 CLASS="FUNCTION"
 296 >cyg_thread_set_data</TT
 297 > may only be called from
 298 thread context because they implicitly operate on the current thread.
 299       </P
 300 ></DIV
 301 ><DIV
 302 CLASS="NAVFOOTER"
 303 ><HR
 304 ALIGN="LEFT"
 305 WIDTH="100%"><TABLE
 306 SUMMARY="Footer navigation table"
 307 WIDTH="100%"
 308 BORDER="0"
 309 CELLPADDING="0"
 310 CELLSPACING="0"
 311 ><TR
 312 ><TD
 313 WIDTH="33%"
 314 ALIGN="left"
 315 VALIGN="top"
 316 ><A
 317 HREF="kernel-thread-priorities.html"
 318 ACCESSKEY="P"
 319 >Prev</A
 320 ></TD
 321 ><TD
 322 WIDTH="34%"
 323 ALIGN="center"
 324 VALIGN="top"
 325 ><A
 326 HREF="ecos-ref.html"
 327 ACCESSKEY="H"
 328 >Home</A
 329 ></TD
 330 ><TD
 331 WIDTH="33%"
 332 ALIGN="right"
 333 VALIGN="top"
 334 ><A
 335 HREF="kernel-thread-destructors.html"
 336 ACCESSKEY="N"
 337 >Next</A
 338 ></TD
 339 ></TR
 340 ><TR
 341 ><TD
 342 WIDTH="33%"
 343 ALIGN="left"
 344 VALIGN="top"
 345 >Thread priorities</TD
 346 ><TD
 347 WIDTH="34%"
 348 ALIGN="center"
 349 VALIGN="top"
 350 ><A
 351 HREF="kernel.html"
 352 ACCESSKEY="U"
 353 >Up</A
 354 ></TD
 355 ><TD
 356 WIDTH="33%"
 357 ALIGN="right"
 358 VALIGN="top"
 359 >Thread destructors</TD
 360 ></TR
 361 ></TABLE
 362 ></DIV
 363 ></BODY
 364 ></HTML
 365 >