1CMUTEX(3) Common Library Functions
2CMUTEX(3)
3[1mNAME[0m
7 [1mCmutex [22m‐ [1mLCG Mutex [22minferface
8[1mSYNOPSIS[0m
10 [1m#include <Cmutex.h>[0m
11 [1mvoid Cmutex_init(int (*[4m[22mlockrou‐
13tine[24m[1m)(void *[4m[22maddr[24m[1m, int [4m[22mtime‐
14out[24m[1m), int[0m
15 [1m(*[4m[22munlockroutine[24m[1m)(void * [4m[22mad‐
16dr[24m[1m));[0m
17 [1mint Cmutex_lock(void *[4m[22maddr[24m[1m, int
19[4m[22mtimeout[24m[1m);[0m
20 [1mint Cmutex_unlock(void *[4m[22maddr[24m[1m);[0m
22[1mDESCRIPTION[0m
26 [1mCmutex [22mis a common API interface for application
27compiled or not with
28 the multithread flag. If the application do never initial‐
29ize the [1mCmutex[0m
30 package, using [1mCmutex_init[22m, and two arguments that
31are the addresses of
32 the mutex lock and unlock functions, [1mlockfunction
33[22mand [1munlockfunction[0m
34 respectively, then all [1mCmutex [22mcalls are dummy oper‐
35ations.
36 Otherwise any call to [1mCmutex_lock [22mwill raise a call
38to [1mlockfunction [22m,
39 and any call to [1mCmutex_unlock [22mwill raise a call to
40[1munlockfunction.[0m
41 Please note that the [1mCmutex [22mpackage is initially
43meant to be interfaced
44 with [1mCthread [22monly.
45 [1mCmutex_lock [22mtakes as argument the address [1maddr
47[22mof anything that is
48 static in your userspace, such as a ’static int variable;’
49address (see
50 [1mEXAMPLE [22msection below), and a [1mtimeout [22mex‐
51pressed in second unit.
52 If [1mtimeout [22mis lower than zero, the operation
53will block until the
54 mutex is granted. If it is zero, the operation will
55try to have the
56 mutex and immediately return, possibly with failure. If it
57is greater
58 than zero, operation will exit if the timeout is reached.
59Please refer
60 to [1mCthread_mutex_timedlock [22mdescription in the [1mC‐
61thread [22mman page.
62 Return code of [1mCmutex_lock [22mis 0 if success, ‐1 on
63failure. If failure
64 the [1mserrno [22merror code is set appropriately.
65 [1mCmutex_unlock [22mreleases a lock that you previ‐
67ously gained using [1mCmu‐[0m
68 [1mtex_lock [22mand the same address value [1maddr.[0m
69 Return code is 0 if success and ‐1 on failure, error code
70is then in
71 the [1mserrno [22mvariable.
72[1mERRORS[0m
75 If the [1mCthread [22minterface is chosen and activated,
76the errors value are
77 in the [1mserrno [22mvariable:
78 [1mSECTHREADINIT[0m
81 LCG Thread interface initialization error
82 A thread initialisation call failed. In principle,
84on UNIX this
85 will be a call to pthread_mutex_init
86(and possibly
87 pthread_mutexattr_init) that failed, on Windows/NT
88this might be
89 a call to CreateMutex.
90 [1mSECTHREADERR[0m
92 LCG Thread interface failure in calling your thread
93library
94 A thread call to your native system library
96(like the pthread
97 one on UNIX) failed. Please note that this is dif‐
98ferentiated to
99 the Cthread initialization and can happen if you
100are using too
101 much thread keys, for example. This is really a
102run‐time error
103 only concerning your operating system thread
104interface. Any
105 other system call failure, but not a thread one,
106and not at the
107 initialisation step, will set serrno to [1mSEINTER‐
108NAL[0m
109 [1mSEOPNOTSUP[0m
111 Operation not supported
112 This can be generated only if you compiled
114Cthread with a
115 ‐DCTHREAD_PROTO flag that Cthread do not know
116about. Check your
117 LCG configuration site.def.
118 [1mSEINTERNAL[0m
120 Internal error
121 You can have more information by compiling the
123Cthread package
124 with the flag ‐DCTHREAD_DEBUG, and catching the
125printout on your
126 stderr stream. This is any system call that
127failed (like mal‐
128 loc()), except those to the thread library (for
129which SECTHREAD‐
130 ERR or SECTHREADINIT is to be found), or any
131critical internal
132 run‐time error (such as a non correct value
133found in some
134 Cthread internal structures).
135 [1mSETIMEDOUT [22m(routines with a timeout parameter only)
137 Timed out
138 You called a routine with a timeout value greater
140than zero that
141 reached the maximum number of timeout seconds in
142waiting state.
143 [1mEINVAL[0m
145 Invalid parameters
146 You called a routine with invalid parameter(s).
148Please check
149 your code.
150 [1mEDEADLK[0m
152 Deadlock
153 Mutex is already locked by the
155calling thread
156 ([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this
157is not the default
158 and should not happen via [1mCmutex[22m)
159 [1mEBUSY[0m
161 Device or resource busy
162 Mutex is already locked by another thread.
164 [1mEPERM[0m
166 Permission denied
167 Mutex is now owned by the
169calling thread
170 ([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this
171is not the default
172 and should not happen via [1mCmutex[22m)
173[1mEXAMPLE[0m
176 /*
177 * Here follows an example. The call to [1mCthread_init
178[22mroutine shows
179 * that multi‐threaded mode is explicitly activated by the
180application
181 * (you will then have to link with the thread library).
182Neverthless,
183 * you can very well call some other external library, and
184leave as it is
185 * the [1mCmutex [22mcalls.
186 */
187 #include <Cmutex.h>
188 #include <Cthread_api.h>
189 #include <serrno.h>
190 #include <stdio.h>
191 #include <stdlib.h>
192 #include <string.h>
193 #include <log.h>
194 int this;
196 extern int Cthread_debug;
197 int main() {
199 Cthread_init(); /* Comment this and Cmutex calls
200will become dummy */
201 initlog("testit",LOG_INFO,"");
203 if (Cmutex_lock(&this,10) != 0) {
205 fprintf(stderr,"### Cmutex_lock (%s)0,sstrerror(ser‐
206rno));
207 }
208 if (Cmutex_unlock(&this) != 0) {
209 fprintf(stderr,"### Cmutex_unlock (%s)0,sstrerror(ser‐
210rno));
211 }
212 }
213[1mSEE ALSO[0m
216 [1mCthread[22m, [1mserrno[0m
217[1mAUTHOR[0m
220 [1mLCG Grid Deployment [22mTeam
221LCG $Date$
225CMUTEX(3)
226