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