Cmutex man page

CMUTEX(3) Common Library Functions CMUTEX(3)

[1mCmutex [22m- [1mLCG Mutex [22minferface

[1m#include <Cmutex.h>[0m

[1mvoid Cmutex_init(int (*[4m[22mlockroutine[24m[1m)(void *[4m[22maddr[24m[1m, int [4m[22mtimeout[24m[1m), int[0m
[1m(*[4m[22munlockroutine[24m[1m)(void * [4m[22maddr[24m[1m));[0m

[1mint Cmutex_lock(void *[4m[22maddr[24m[1m, int [4m[22mtimeout[24m[1m);[0m

[1mint Cmutex_unlock(void *[4m[22maddr[24m[1m);[0m

[1mCmutex [22mis a common API interface for application compiled or not with
the multithread flag. If the application do never initialize the [1mCmutex[0m
package, using [1mCmutex_init[22m, and two arguments that are the addresses of
the mutex lock and unlock functions, [1mlockfunction [22mand [1munlockfunction[0m
respectively, then all [1mCmutex [22mcalls are dummy operations.

Otherwise any call to [1mCmutex_lock [22mwill raise a call to [1mlockfunction [22m,
and any call to [1mCmutex_unlock [22mwill raise a call to [1munlockfunction.[0m

Please note that the [1mCmutex [22mpackage is initially meant to be interfaced
with [1mCthread [22monly.

[1mCmutex_lock [22mtakes as argument the address [1maddr [22mof anything that is
static in your userspace, such as a 'static int variable;' address (see
[1mEXAMPLE [22msection below), and a [1mtimeout [22mexpressed in second unit.
If [1mtimeout [22mis lower than zero, the operation will block until the
mutex is granted. If it is zero, the operation will try to have the
mutex and immediately return, possibly with failure. If it is greater
than zero, operation will exit if the timeout is reached. Please refer
to [1mCthread_mutex_timedlock [22mdescription in the [1mCthread [22mman page.
Return code of [1mCmutex_lock [22mis 0 if success, -1 on failure. If failure
the [1mserrno [22merror code is set appropriately.

[1mCmutex_unlock [22mreleases a lock that you previously gained using [1mCmu-[0m
[1mtex_lock [22mand the same address value [1maddr.[0m
Return code is 0 if success and -1 on failure, error code is then in
the [1mserrno [22mvariable.

If the [1mCthread [22minterface is chosen and activated, the errors value are
in the [1mserrno [22mvariable:

LCG Thread interface initialization error

A thread initialisation call failed. In principle, on UNIX this
will be a call to pthread_mutex_init (and possibly
pthread_mutexattr_init) that failed, on Windows/NT this might be
a call to CreateMutex.

LCG Thread interface failure in calling your thread library

A thread call to your native system library (like the pthread
one on UNIX) failed. Please note that this is differentiated to
the Cthread initialization and can happen if you are using too
much thread keys, for example. This is really a run-time error
only concerning your operating system thread interface. Any
other system call failure, but not a thread one, and not at the
initialisation step, will set serrno to [1mSEINTERNAL[0m

Operation not supported

This can be generated only if you compiled Cthread with a
-DCTHREAD_PROTO flag that Cthread do not know about. Check your
LCG configuration site.def.

Internal error

You can have more information by compiling the Cthread package
with the flag -DCTHREAD_DEBUG, and catching the printout on your
stderr stream. This is any system call that failed (like mal-
loc()), except those to the thread library (for which SECTHREAD-
ERR or SECTHREADINIT is to be found), or any critical internal
run-time error (such as a non correct value found in some
Cthread internal structures).

[1mSETIMEDOUT [22m(routines with a timeout parameter only)
Timed out

You called a routine with a timeout value greater than zero that
reached the maximum number of timeout seconds in waiting state.

Invalid parameters

You called a routine with invalid parameter(s). Please check
your code.


Mutex is already locked by the calling thread
([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this is not the default
and should not happen via [1mCmutex[22m)

Device or resource busy

Mutex is already locked by another thread.

Permission denied

Mutex is now owned by the calling thread
([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this is not the default
and should not happen via [1mCmutex[22m)

* Here follows an example. The call to [1mCthread_init [22mroutine shows
* that multi-threaded mode is explicitly activated by the application
* (you will then have to link with the thread library). Neverthless,
* you can very well call some other external library, and leave as it is
* the [1mCmutex [22mcalls.
#include <Cmutex.h>
#include <Cthread_api.h>
#include <serrno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <log.h>

int this;
extern int Cthread_debug;

int main() {
Cthread_init(); /* Comment this and Cmutex calls will become dummy */


if (Cmutex_lock(&this,10) != 0) {
fprintf(stderr,"### Cmutex_lock (%s)0,sstrerror(serrno));
if (Cmutex_unlock(&this) != 0) {
fprintf(stderr,"### Cmutex_unlock (%s)0,sstrerror(serrno));

[1mSEE ALSO[0m
[1mCthread[22m, [1mserrno[0m

[1mLCG Grid Deployment [22mTeam

LCG $Date: 2010-04-05 09:51:26 +0200 (Mon, 05 Apr 2010) $ CMUTEX(3)