NAME
Cmutex - LCG Mutex inferface
SYNOPSIS
#include <Cmutex.h>
void Cmutex_init(int (*lockroutine)(void *addr, int timeout), int
(*unlockroutine)(void * addr));
int Cmutex_lock(void *addr, int timeout);
int Cmutex_unlock(void *addr);
DESCRIPTION
Cmutex is a common API interface for application compiled or not with
the multithread flag. If the application do never initialize the Cmutex
package, using Cmutex_init, and two arguments that are the addresses of
the mutex lock and unlock functions, lockfunction and unlockfunction
respectively, then all Cmutex calls are dummy operations.
Otherwise any call to Cmutex_lock will raise a call to lockfunction ,
and any call to Cmutex_unlock will raise a call to unlockfunction.
Please note that the Cmutex package is initially meant to be interfaced
with Cthread only.
Cmutex_lock takes as argument the address addr of anything that is
static in your userspace, such as a ’static int variable;’ address (see
EXAMPLE section below), and a timeout expressed in second unit.
If timeout is 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 Cthread_mutex_timedlock description in the Cthread man page.
Return code of Cmutex_lock is 0 if success, -1 on failure. If failure
the serrno error code is set appropriately.
Cmutex_unlock releases a lock that you previously gained using
Cmutex_lock and the same address value addr.
Return code is 0 if success and -1 on failure, error code is then in
the serrno variable.
ERRORS
If the Cthread interface is chosen and activated, the errors value are
in the serrno variable:
SECTHREADINIT
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.
SECTHREADERR
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 SEINTERNAL
SEOPNOTSUP
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.
SEINTERNAL
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
malloc()), except those to the thread library (for which
SECTHREADERR 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).
SETIMEDOUT (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.
EINVAL
Invalid parameters
You called a routine with invalid parameter(s). Please check
your code.
EDEADLK
Deadlock
Mutex is already locked by the calling thread
(PTHREAD_MUTEX_ERRORCHECK mutexes only, this is not the default
and should not happen via Cmutex)
EBUSY
Device or resource busy
Mutex is already locked by another thread.
EPERM
Permission denied
Mutex is now owned by the calling thread
(PTHREAD_MUTEX_ERRORCHECK mutexes only, this is not the default
and should not happen via Cmutex)
EXAMPLE
/*
* Here follows an example. The call to Cthread_init routine 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 Cmutex calls.
*/
#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 */
initlog("testit",LOG_INFO,"");
if (Cmutex_lock(&this,10) != 0) {
fprintf(stderr,"### Cmutex_lock (%s)\n",sstrerror(serrno));
}
if (Cmutex_unlock(&this) != 0) {
fprintf(stderr,"### Cmutex_unlock (%s)\n",sstrerror(serrno));
}
}
SEE ALSO
Cthread, serrno
AUTHOR
LCG Grid Deployment Team