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

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