1CTHREAD(3) Common Library Functions CTHREAD(3)
2
6 Cthread - LCG Thread inferface
7
9 #include <Cthread_api.h>
10 int Cthread_create(void *(*startroutine)(void *), void * arg);
12 int Cthread_create_detached(void *(*startroutine)(void *),void *arg);
14 int Cthread_join(int cid, int **status);
16 int Cthread_mutex_lock(void *addr);
18 int Cthread_mutex_trylock(void *addr);
20 int Cthread_mutex_timedlock(void *addr, int timeout);
22 int Cthread_mutex_unlock(void *addr);
24 int Cthread_mutex_destroy(void *addr);
26 int Cthread_cond_wait(void *addr);
28 int Cthread_cond_timedwait(void *addr, int timeout);
30 int Cthread_cond_signal(void *addr);
32 int Cthread_cond_broadcast(void *addr);
34 int Cthread_detach(int cid);
36 int Cthread_kill(int cid, int signo);
38 int Cthread_exit(void *status);
40 int Cthread_self(void);
42 int Cthread_getspecific(int *global_key, void **addr);
44 int Cthread_setspecific(int *global_key, void * addr);
46
49 Cthread is a common API interface for multithreaded programs, although
50 there is also support for nonthreaded application, where some of the
51 Cthread functions then becomes useless.
52 For non-thread applications see the section NON-THREAD ENVIRONMENT
54 Any created thread is identified uniquely with a cid, standing for
56 Cthread identifier.
57 In multithread environment, Cthread is an interface to pthread func‐
59 tions on UNIX, and an interface to Win32 C-runtime library on Win‐
60 dows/NT.
61 Cthread_create is creating a thread given its starting point startrou‐
63 tine and its arguments arg address. The thread is created with the
64 default parameters, e.g. it is a joinable thread.
65 Return value is the Cthread identifier cid , greater or equal to zero,
67 or -1 on error.
68 Cthread_create_detached takes the same arguments as Cthread_create and
70 (tries) to create a detachable thread, which will then make it act as a
71 daemon. This means that ressources used by this thread will be freed
72 immediately when it terminates. On the other hand, such thread cannot
73 be synchronized with other threads using the Cthread_join method.
74 You have to remind that creating a detachable thread do not work imme‐
76 diately at the creation step on every thread implementation, in partic‐
77 ular in the DCE threads. If the implementation do not allow this at
78 creation time, then Cthread_create_detached calls Cthread_create.
79 Please have a look at Cthread_detach section.
80 Return value is the Cthread identifier cid , greater or equal to zero,
82 or -1 on error.
83 Cthread_exit makes current thread exiting. If status isn't NULL, it is
85 assumed to point to an integer whose value if the status that a
86 Cthread_join would received, in case the thread is joinable. Please
87 note that Cthread_exit is dangerous and non-recommended on Windows
88 platform.
89 Return value is 0 on success, or -1 on error.
91 Cthread_kill sends signo signal number to the thread cid. This affect
93 the status that a Cthread_join would received, in case the thread to be
94 killed is joinable. Please note that Cthread_kill is not supported on
95 DCE threads.
96 Return value is 0 on success, or -1 on error.
98 Cthread_join suspends the calling thread until the one identified with
100 the Cthread identifier cid terminates. If the status parameter is not
101 NULL, the status of the terminating thread cid is stored there. This
102 status is the pointer returned by thread cid at its end.
103 Return value is 0 on success, or -1 on error.
105 Cthread_mutex_lock is an alias for Cthread_mutex_timedlock with a time‐
107 out of -1.
108 Cthread_mutex_trylock is an alias for Cthread_mutex_timedlock with a
110 timeout of 0.
111 Cthread_mutex_timedlock is acquiring a mutex, creating it if necessary,
113 on the addr address. The second parameter is the eventual timeout in
114 seconds. If this parameter is < 0, the calling thread is suspended
115 until it is granted access to addr , if it is zero, the calling thread
116 will try to gain the lock, and if it is greater than zero the calling
117 thread will wait up to timeout seconds.
118 Please note that, in Cthread, a creation of a mutex is always associ‐
120 ated with a creation of a conditionnal variable. See
121 Cthread_cond_timedwait and Cthread_cond_broadcast_.
122 Return value is 0 on success, or -1 on error.
124 Cthread_mutex_unlock is unlocking the mutex that the calling thread is
126 assumed to have acquired previously, calling Cthread_mutex_timedlock on
127 the addr address.
128 Cthread_cond_wait is an alias for Cthread_cond_timedwait with a timeout
130 of -1.
131 Cthread_cond_timedwait is waiting for a condition variable, which is,
133 by default in Cthread, broadcasted, associated with a mutex previously
134 created on the addr address. Calling this function before the creation
135 and the lock of a mutex, with Cthread_mutex_timedlock is a programming
136 error.
137 While the thread is waiting on a condition to arise on the addr
139 address, the corresponding lock is released. It will be acquired as
140 soon as the condition happens. Please note that the use of condition is
141 subject to normal thread programming rules, e.g. the lock, a loop on a
142 predicate, a wait inside the loop, and the unlock.
143 If the timeout parameter, in seconds, is greater than zero, then the
145 function will not suspend the calling thread more than this limit.
146 Return value is 0 on success, or -1 on error.
148 Cthread_cond_signal is an alias for Cthread_cond_broadcast.
150 Cthread_cond_broadcast restarts threads that are waiting on a condition
152 variable vs. addr address.
153 Return value is 0 on success, or -1 on error.
155 Cthread_detach is detaching the calling thread, identified with cid
157 Cthread identifier. Whereas the normal thread packages that allow a
158 thread to be detached at the creation step, see Cthread_cre‐
159 ate_detached, returns an error if such a detached thread tries to
160 detach himself again, Cthread_detach will not, because of this differ‐
161 ent behaviour vs. different thread implementations: it is not possible
162 everywhere to create a detached thread immediately, like in DCE
163 threads.
164 This means that if a user is creating a thread with Cthread_create or
166 Cthread_create_detached, the created thread will, in any case, be
167 allowed to call Cthread_detach: if the calling thread is not yet
168 detached, it will be changed so forth, and if the calling thread is
169 already detached, the return value will be 0.
170 Return value is 0 on success, or -1 on error.
172 Cthread_mutex_destroy is removing its corresponding entry in Cthread
174 internal linked list, freeing all thread associated stuff, like the
175 mutex itself, and the conditionnal variable (see Cthread_mutex_timed‐
176 lock).
177 Return value is 0 on success, or -1 on error.
179 Cthread_self is returning the Cthread identifier cid of the calling
181 thread.
182 Return value is the cid (greater or equal to zero) on success, or -1 on
184 error.
185 Cthread_getspecific is creating and/or getting a thread-specific stor‐
187 age address for every instance of the global_key address, storing its
188 result in addr location. The first time it is called, the stored result
189 is NULL, next time it will be the address of the memory the user would
190 have previously allocated and associated with the key using
191 Cthread_setspecific.
192 Return value is 0 on success, or -1 on error.
194 Cthread_setspecific is associating a memory, starting at addr that he
196 have previously allocated, with the global_key address. If he tries to
197 do so without calling previously Cthread_getspecific, then such a call
198 will be done internally.
199 Return value is 0 on success, or -1 on error.
201
204 Beyond the errno value, Cthread is setting the serrno value to generic
205 values that can be:
206 SECTHREADINIT
208 LCG Thread interface initialization error
209 A thread initialisation call failed. In principle, on UNIX this
211 will be a call to pthread_mutex_init (and possibly
212 pthread_mutexattr_init) that failed, on Windows/NT this might be
213 a call to CreateMutex.
214 SECTHREADERR
216 LCG Thread interface failure in calling your thread library
217 A thread call to your native system library (like the pthread
219 one on UNIX) failed. Please note that this is differentiated to
220 the Cthread initialization and can happen if you are using too
221 much thread keys, for example. This is really a run-time error
222 only concerning your operating system thread interface. Any
223 other system call failure, but not a thread one, and not at the
224 initialisation step, will set serrno to SEINTERNAL
225 SEOPNOTSUP
227 Operation not supported
228 This can be generated only if you compiled Cthread with a
230 -DCTHREAD_PROTO flag that Cthread do not know about. Check your
231 LCG configuration site.def.
232 SEINTERNAL
234 Internal error
235 You can have more information by compiling the Cthread package
237 with the flag -DCTHREAD_DEBUG, and catching the printout on your
238 stderr stream. This is any system call that failed (like mal‐
239 loc()), except those to the thread library (for which SECTHREAD‐
240 ERR or SECTHREADINIT is to be found), or any critical internal
241 run-time error (such as a non correct value found in some
242 Cthread internal structures).
243 SETIMEDOUT (routines with a timeout parameter only)
245 Timed out
246 You called a routine with a timeout value greater than zero that
248 reached the maximum number of timeout seconds in waiting state.
249 EINVAL
251 Invalid parameters
252 You called a routine with invalid parameter(s). Please check
254 your code.
255
258 Here is an example with thread-specific data
259 #include <Cthread_api.h> /* Cthread include file */
261 #include <stdio.h> /* For I/O functions and definitions */
262 #define NTHREADS 5 /* Number of threads */
263 #define NLOOP 5 /* Number of loops in threads */
264 static int global_key;
266 /* Internal Prototypes */
268 void *mythread(void *);
269 void testit();
270 int main() {
272 int i, n;
273 for (i=1; i <= NTHREADS; i++) {
275 if ((n = Cthread_create(&mythread,NULL)) < 0) {
276 exit(EXIT_FAILURE);
277 } else {
278 fprintf(stderr,"[main] --> Created Cthread ID %d\n",n);
279 }
280 }
281 sleep(NTHREADS);
283 exit(EXIT_SUCCESS);
284 }
285 void *mythread(void *arg) {
287 int i;
288 /* Call the same routine NLOOP times */
290 for (i=1; i <= NLOOP; i++) {
291 testit();
292 }
293 return(NULL);
295 }
296 void testit() {
298 char *addr = NULL;
299 int n;
300 if ((n = Cthread_detach(Cthread_self())))
302 exit(EXIT_FAILURE);
303 if ((n = Cthread_getspecific(&global_key,(void **) &addr)))
305 exit(EXIT_FAILURE);
306 if (addr == NULL) {
308 addr = malloc(100);
309 fprintf(stderr,"[%d] --> new 0x%x\n",
310 Cthread_self(),addr);
311 if (Cthread_setspecific(&global_key,addr))
312 exit(EXIT_FAILURE);
313 } else {
314 fprintf(stderr,"[%d] --> old 0x%x\n",
315 Cthread_self(),addr);
316 }
317 sprintf(addr,"[%d] Print with TSD buffer : Cthread ID=%d\n",
319 Cthread_self(),Cthread_self());
320 fprintf(stderr,addr);
322 return;
324 }
325
327 In such an environment, almost all methods becomes no-op, except:
328 Creation of process(es):
330 Cthread_create
331 Cthread_create_detached (equivalent to Cthread_create)
332 Cthread_join
333 Use of "Process"-specific variables:
335 Cthread_getspecific
336 Cthread_setspecific
337 For these two last functions, Cthread will garbage itself its
339 eventual list of "Process"-specific variables. This means that,
340 as in a thread environment, the user will not have to free mem‐
341 ory allocated and registered with a call to Cthread_setspecific.
342
344 pthread, DCE, LinuxThreads, Win32
345
348 LCG Grid Deployment Team
349LCG $Date: 2005/03/29 09:27:18 $ CTHREAD(3)