CMUTEX(3)						     Common Library Functions							 CMUTEX(3)

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 Cmu-
       tex package, using Cmutex_init, and two arguments that are the addresses of the mutex lock and unlock functions, lockfunction  and  unlock-
       function 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_mutex-
	      attr_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  con-
	      cerning  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  con-
	      figuration 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)
",sstrerror(serrno));
	 }
	 if (Cmutex_unlock(&this) != 0) {
	   fprintf(stderr,"### Cmutex_unlock (%s)
",sstrerror(serrno));
	 }
       }

SEE ALSO

       Cthread, serrno

AUTHOR

       LCG Grid Deployment Team

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