1CTHREAD(3) Common Library Functions
2CTHREAD(3)
3[1mNAME[0m
7 [1mCthread [22m‐ [1mLCG Thread [22minferface
8[1mSYNOPSIS[0m
10 [1m#include <Cthread_api.h>[0m
11 [1mint Cthread_create(void *(*[4m[22mstartrou‐
13tine[24m[1m)(void *), void * [4m[22marg[24m[1m);[0m
14 [1mint Cthread_create_detached(void *(*[4m[22mstartrou‐
16tine[24m[1m)(void *),void *[4m[22marg[24m[1m);[0m
17 [1mint Cthread_join(int [4m[22mcid[24m[1m, int
19**[4m[22mstatus[24m[1m);[0m
20 [1mint Cthread_mutex_lock(void *[4m[22maddr[24m[1m);[0m
22 [1mint Cthread_mutex_trylock(void *[4m[22maddr[24m[1m);[0m
24 [1mint Cthread_mutex_timedlock(void *[4m[22maddr[24m[1m,
26int [4m[22mtimeout[24m[1m);[0m
27 [1mint Cthread_mutex_unlock(void *[4m[22maddr[24m[1m);[0m
29 [1mint Cthread_mutex_destroy(void *[4m[22maddr[24m[1m);[0m
31 [1mint Cthread_cond_wait(void *[4m[22maddr[24m[1m);[0m
33 [1mint Cthread_cond_timedwait(void *[4m[22maddr[24m[1m,
35int [4m[22mtimeout[24m[1m);[0m
36 [1mint Cthread_cond_signal(void *[4m[22maddr[24m[1m);[0m
38 [1mint Cthread_cond_broadcast(void *[4m[22mad‐
40dr[24m[1m);[0m
41 [1mint Cthread_detach(int [4m[22mcid[24m[1m);[0m
43 [1mint Cthread_kill(int [4m[22mcid[24m[1m, int [4m[22msig‐
45no[24m[1m);[0m
46 [1mint Cthread_exit(void *[4m[22mstatus[24m[1m);[0m
48 [1mint Cthread_self(void);[0m
50 [1mint Cthread_getspecific(int *[4m[22mglobal_key[24m[1m,
52void **[4m[22maddr[24m[1m);[0m
53 [1mint Cthread_setspecific(int *[4m[22mglobal_key[24m[1m,
55void * [4m[22maddr[24m[1m);[0m
56[1mDESCRIPTION[0m
59 [1mCthread [22mis a common API interface for multithread‐
60ed programs, although
61 there is also support for nonthreaded application, where
62some of the
63 [1mCthread [22mfunctions then becomes useless.
64 For non‐thread applications see the section [1mNON‐THREAD
66ENVIRONMENT[0m
67 Any created thread is identified uniquely with a
69[1mcid[22m, standing for
70 [1mC[22mthread [1mid[22mentifier.
71 In multithread environment, [1mCthread [22mis an interface
73to [1mpthread [22mfunc‐
74 tions on [1mUNIX[22m, and an interface to [1mWin32
75[22mC‐runtime library on [1mWin‐[0m
76 [1mdows/NT[22m.
77 [1mCthread_create [22mis creating a thread given its
79starting point [4mstartrou‐[0m
80 [4mtine[24m and its arguments [4marg[24m address. The
81thread is created with the
82 default parameters, e.g. it is a joinable thread.
83 Return value is the [1mCthread [22midentifier [4mcid[24m ,
85greater or equal to zero,
86 or ‐1 on error.
87 [1mCthread_create_detached [22mtakes the same arguments
89as [1mCthread_create [22mand
90 (tries) to create a detachable thread, which will then
91make it act as a
92 daemon. This means that ressources used by this thread
93will be freed
94 immediately when it terminates. On the other hand, such
95thread cannot
96 be synchronized with other threads using the [1mC‐
97thread_join [22mmethod.
98 You have to remind that creating a detachable thread do
100not work imme‐
101 diately at the creation step on every thread implementa‐
102tion, in partic‐
103 ular in the [1mDCE [22mthreads. If the implementation
104do not allow this at
105 creation time, then [1mCthread_create_detached
106[22mcalls [1mCthread_create[22m.
107 Please have a look at [1mCthread_detach [22msection.
108 Return value is the [1mCthread [22midentifier [4mcid[24m
110, greater or equal to zero,
111 or ‐1 on error.
112 [1mCthread_exit [22mmakes current thread exiting. If
114[1mstatus [22misn’t NULL, it is
115 assumed to point to an integer whose value if the
116status that a
117 [1mCthread_join [22mwould received, in case the thread
118is joinable. Please
119 note that [1mCthread_exit [22mis dangerous and non‐
120recommended on Windows
121 platform.
122 Return value is 0 on success, or ‐1 on error.
124 [1mCthread_kill [22msends [1msigno [22msignal number to
126the thread [1mcid. [22mThis affect
127 the status that a [1mCthread_join [22mwould received, in
128case the thread to be
129 killed is joinable. Please note that [1mCthread_kill
130[22mis not supported on
131 DCE threads.
132 Return value is 0 on success, or ‐1 on error.
134 [1mCthread_join [22msuspends the calling thread until the
136one identified with
137 the [1mCthread [22midentifier [4mcid[24m terminates. If
138the [4mstatus[24m parameter is not
139 [1mNULL[22m, the status of the terminating thread
140[4mcid[24m is stored there. This
141 status is the pointer returned by thread [4mcid[24m at its
142end.
143 Return value is 0 on success, or ‐1 on error.
145 [1mCthread_mutex_lock [22mis an alias for [1mCthread_mu‐
147tex_timedlock [22mwith a [4mtime‐[0m
148 [4mout[24m of ‐1.
149 [1mCthread_mutex_trylock [22mis an alias for [1mC‐
151thread_mutex_timedlock [22mwith a
152 [4mtimeout[24m of 0.
153 [1mCthread_mutex_timedlock [22mis acquiring a mutex, cre‐
155ating it if necessary,
156 on the [4maddr[24m address. The second parameter is the
157eventual [4mtimeout[24m in
158 seconds. If this parameter is < 0, the calling thread
159is suspended
160 until it is granted access to [4maddr[24m , if it is ze‐
161ro, the calling thread
162 will try to gain the lock, and if it is greater than zero
163the calling
164 thread will wait up to [4mtimeout[24m seconds.
165 Please note that, in [1mCthread[22m, a creation of a mu‐
167tex is always associ‐
168 ated with a creation of a conditionnal
169variable. See
170 [1mCthread_cond_timedwait [22mand [1mCthread_cond_broad‐
171cast_[22m.
172 Return value is 0 on success, or ‐1 on error.
174 [1mCthread_mutex_unlock [22mis unlocking the mutex that
176the calling thread is
177 assumed to have acquired previously, calling [1mC‐
178thread_mutex_timedlock [22mon
179 the [4maddr[24m address.
180 [1mCthread_cond_wait [22mis an alias for [1mC‐
182thread_cond_timedwait [22mwith a [4mtimeout[0m
183 of ‐1.
184 [1mCthread_cond_timedwait [22mis waiting for a condition
186variable, which is,
187 by default in [1mCthread[22m, broadcasted, associated
188with a mutex previously
189 created on the [4maddr[24m address. Calling this function
190before the creation
191 [1mand [22mthe lock of a mutex, with [1mCthread_mu‐
192tex_timedlock [22mis a programming
193 error.
194 While the thread is waiting on a condition to arise
196on the [4maddr[0m
197 address, the corresponding lock is released. It will
198be acquired as
199 soon as the condition happens. Please note that the use of
200condition is
201 subject to normal thread programming rules, e.g. the
202lock, a loop on a
203 predicate, a wait inside the loop, and the unlock.
204 If the [4mtimeout[24m parameter, in seconds, is greater
206than zero, then the
207 function will not suspend the calling thread more than
208this limit.
209 Return value is 0 on success, or ‐1 on error.
211 [1mCthread_cond_signal [22mis an alias for [1mC‐
213thread_cond_broadcast[22m.
214 [1mCthread_cond_broadcast [22mrestarts threads that are
216waiting on a condition
217 variable vs. [4maddr[24m address.
218 Return value is 0 on success, or ‐1 on error.
220 [1mCthread_detach [22mis detaching the calling thread,
222identified with [4mcid[0m
223 [1mCthread [22midentifier. Whereas the normal thread
224packages that allow a
225 thread to be detached at the creation step, see
226[1mCthread_cre‐[0m
227 [1mate_detached[22m, returns an error if such a de‐
228tached thread tries to
229 detach himself again, [1mCthread_detach [22mwill not, be‐
230cause of this differ‐
231 ent behaviour vs. different thread implementations: it is
232not possible
233 everywhere to create a detached thread immediately,
234like in DCE
235 threads.
236 This means that if a user is creating a thread with
238[1mCthread_create [22mor
239 [1mCthread_create_detached[22m, the created thread will,
240in any case, be
241 allowed to call [1mCthread_detach[22m: if the call‐
242ing thread is not yet
243 detached, it will be changed so forth, and if the call‐
244ing thread is
245 already detached, the return value will be 0.
246 Return value is 0 on success, or ‐1 on error.
248 [1mCthread_mutex_destroy [22mis removing its corre‐
250sponding entry in [1mCthread[0m
251 internal linked list, freeing all thread associated
252stuff, like the
253 mutex itself, and the conditionnal variable (see [1mC‐
254thread_mutex_timed‐[0m
255 [1mlock[22m).
256 Return value is 0 on success, or ‐1 on error.
258 [1mCthread_self [22mis returning the [1mCthread [22miden‐
260tifier [4mcid[24m of the calling
261 thread.
262 Return value is the [4mcid[24m (greater or equal to zero)
264on success, or ‐1 on
265 error.
266 [1mCthread_getspecific [22mis creating and/or getting a
268thread‐specific stor‐
269 age address for every instance of the [4mglobal_key[24m
270address, storing its
271 result in [4maddr[24m location. The first time it is
272called, the stored result
273 is [1mNULL[22m, next time it will be the address of the
274memory the user would
275 have previously allocated and associated with the
276key using
277 [1mCthread_setspecific[22m.
278 Return value is 0 on success, or ‐1 on error.
280 [1mCthread_setspecific [22mis associating a memory,
282starting at [4maddr[24m that he
283 have previously allocated, with the [4mglobal_key[24m ad‐
284dress. If he tries to
285 do so without calling previously [1mCthread_getspecif‐
286ic[22m, then such a call
287 will be done internally.
288 Return value is 0 on success, or ‐1 on error.
290[1mERRORS[0m
293 Beyond the errno value, [1mCthread [22mis setting the ser‐
294rno value to generic
295 values that can be:
296 [1mSECTHREADINIT[0m
298 LCG Thread interface initialization error
299 A thread initialisation call failed. In principle,
301on UNIX this
302 will be a call to pthread_mutex_init
303(and possibly
304 pthread_mutexattr_init) that failed, on Windows/NT
305this might be
306 a call to CreateMutex.
307 [1mSECTHREADERR[0m
309 LCG Thread interface failure in calling your thread
310library
311 A thread call to your native system library (like
313the pthread
314 one on UNIX) failed. Please note that this is dif‐
315ferentiated to
316 the Cthread initialization and can happen if you
317are using too
318 much thread keys, for example. This is really a
319run‐time error
320 only concerning your operating system thread
321interface. Any
322 other system call failure, but not a thread one,
323and not at the
324 initialisation step, will set serrno to [1mSEINTER‐
325NAL[0m
326 [1mSEOPNOTSUP[0m
328 Operation not supported
329 This can be generated only if you compiled
331Cthread with a
332 ‐DCTHREAD_PROTO flag that Cthread do not know
333about. Check your
334 LCG configuration site.def.
335 [1mSEINTERNAL[0m
337 Internal error
338 You can have more information by compiling the
340Cthread package
341 with the flag ‐DCTHREAD_DEBUG, and catching the
342printout on your
343 stderr stream. This is any system call that failed
344(like mal‐
345 loc()), except those to the thread library (for
346which SECTHREAD‐
347 ERR or SECTHREADINIT is to be found), or any crit‐
348ical internal
349 run‐time error (such as a non correct value
350found in some
351 Cthread internal structures).
352 [1mSETIMEDOUT [22m(routines with a timeout parameter only)
354 Timed out
355 You called a routine with a timeout value greater
357than zero that
358 reached the maximum number of timeout seconds in
359waiting state.
360 [1mEINVAL[0m
362 Invalid parameters
363 You called a routine with invalid parameter(s).
365Please check
366 your code.
367[1mEXAMPLES[0m
370 [1mHere is an example with thread‐specific data[0m
371 #include <Cthread_api.h> /* [1mCthread [22minclude file */
373 #include <stdio.h> /* For I/O functions and defini‐
374tions */
375 #define NTHREADS 5 /* Number of threads */
376 #define NLOOP 5 /* Number of loops in threads */
377 static int global_key;
379 /* Internal Prototypes */
381 void *mythread(void *);
382 void testit();
383 int main() {
385 int i, n;
386 for (i=1; i <= NTHREADS; i++) {
388 if ((n = [1mCthread_create[22m(&mythread,NULL)) < 0) {
389 exit(EXIT_FAILURE);
390 } else {
391 fprintf(stderr,"[main] ‐‐> Created Cthread ID
392%d0,n);
393 }
394 }
395 sleep(NTHREADS);
397 exit(EXIT_SUCCESS);
398 }
399 void *mythread(void *arg) {
401 int i;
402 /* Call the same routine NLOOP times */
404 for (i=1; i <= NLOOP; i++) {
405 testit();
406 }
407 return(NULL);
409 }
410 void testit() {
412 char *addr = NULL;
413 int n;
414 if ((n = [1mCthread_detach[22m(Cthread_self())))
416 exit(EXIT_FAILURE);
417 if ((n = [1mCthread_getspecific[22m(&global_key,(void
419**) &addr)))
420 exit(EXIT_FAILURE);
421 if (addr == NULL) {
423 addr = malloc(100);
424 fprintf(stderr,"[%d] ‐‐> new 0x%x0,
425 Cthread_self(),addr);
426 if ([1mCthread_setspecific[22m(&global_key,addr))
427 exit(EXIT_FAILURE);
428 } else {
429 fprintf(stderr,"[%d] ‐‐> old 0x%x0,
430 Cthread_self(),addr);
431 }
432 sprintf(addr,"[%d] Print with TSD buffer : Cthread
434ID=%d0,
435 Cthread_self(),Cthread_self());
436 fprintf(stderr,addr);
438 return;
440 }
441[1mNON‐THREAD ENVIRONMENT[0m
443 In such an environment, almost all methods becomes no‐op,
444except:
445 Creation of process(es):
447 [1mCthread_create[0m
448 [1mCthread_create_detached [22m(equivalent
449to [1mCthread_create[22m)
450 [1mCthread_join[0m
451 Use of "Process"‐specific variables:
453 [1mCthread_getspecific[0m
454 [1mCthread_setspecific[0m
455 For these two last functions, [1mCthread [22mwill
457garbage itself its
458 eventual list of "Process"‐specific variables.
459This means that,
460 [1mas in a thread environment[22m, the user will
461[1mnot [22mhave to free mem‐
462 ory allocated [1mand [22mregistered with a call to
463[1mCthread_setspecific[22m.
464[1mSEE ALSO[0m
466 [1mpthread[22m, [1mDCE[22m, [1mLinuxThreads[22m,
467[1mWin32[0m
468[1mAUTHOR[0m
471 [1mLCG Grid Deployment [22mTeam
472LCG $Date: 2005/03/29 09:27:18 $
476CTHREAD(3)
477