Man Linux: Main Page and Category List


       Cmutex - LCG Mutex inferface


       #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);


       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.


       If  the Cthread interface is chosen and activated, the errors value are
       in the serrno variable:

              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 SEINTERNAL

              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
              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.

              Invalid parameters

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


              Mutex   is   already    locked    by    the    calling    thread
              (PTHREAD_MUTEX_ERRORCHECK  mutexes only, this is not the default
              and should not happen via Cmutex)

              Device or resource busy

              Mutex is already locked by another thread.

              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)


        * 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 */


         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));


       Cthread, serrno


       LCG Grid Deployment Team