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. -->
12 >Per-thread data</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
25 TITLE="Thread priorities"
26 HREF="kernel-thread-priorities.html"><LINK
28 TITLE="Thread destructors"
29 HREF="kernel-thread-destructors.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-thread-priorities.html"
71 HREF="kernel-thread-destructors.html"
82 NAME="KERNEL-THREAD-DATA">Per-thread data</H1
90 >cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data -- Manipulate per-thread data</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >cyg_ucount32 cyg_thread_new_data_index</CODE
125 >void cyg_thread_free_data_index</CODE
126 >(cyg_ucount32 index);</CODE
132 >cyg_addrword_t cyg_thread_get_data</CODE
133 >(cyg_ucount32 index);</CODE
139 >cyg_addrword_t* cyg_thread_get_data_ptr</CODE
140 >(cyg_ucount32 index);</CODE
146 >void cyg_thread_set_data</CODE
147 >(cyg_ucount32 index, cyg_addrword_t data);</CODE
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
168 >. However, if multiple threads make concurrent
169 calls into the POSIX library and if <TT
173 really a global variable then a thread would have no way of knowing
174 whether the current <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
184 implemented as a per-thread variable, and each thread has its own
188 >The support for per-thread data can be disabled via the configuration
191 >CYGVAR_KERNEL_THREADS_DATA</TT
196 > data structure holds a small array
197 of words. The size of this array is determined by the configuration
200 >CYGNUM_KERNEL_THREADS_DATA_MAX</TT
202 thread is created the array is filled with zeroes.
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
210 >cyg_thread_new_data_index</TT
212 subsequent calls to <TT
214 >cyg_thread_get_data</TT
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
221 >cyg_thread_free_data_index</TT
225 >The current per-thread data in a given slot can be obtained using
228 >cyg_thread_get_data</TT
229 >. This implicitly operates on
230 the current thread, and its single argument should be an index as
233 >cyg_thread_new_data_index</TT
235 per-thread data can be updated using
238 >cyg_thread_set_data</TT
239 >. If a particular item of
240 per-thread data is needed repeatedly then
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.
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
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,
262 >CYGNUM_KERNEL_THREADS_DATA_POSIX</TT
264 this does involve a risk of strange and subtle bugs if the
265 application's requirements ever change.
271 NAME="KERNEL-THREAD-DATA-CONTEXT"
278 >cyg_thread_new_data_index</TT
280 called during initialization, but may also be called at any time in
283 >cyg_thread_free_data_index</TT
285 used at all, can also be called during initialization or from thread
288 >cyg_thread_get_data</TT
292 >cyg_thread_get_data_ptr</TT
296 >cyg_thread_set_data</TT
297 > may only be called from
298 thread context because they implicitly operate on the current thread.
306 SUMMARY="Footer navigation table"
317 HREF="kernel-thread-priorities.html"
335 HREF="kernel-thread-destructors.html"
345 >Thread priorities</TD
359 >Thread destructors</TD