Cmutex man page

CMUTEX(3)                  Common Library Functions                  CMUTEX(3)

[1mNAME[0m
      [1mCmutex [22m- [1mLCG Mutex [22minferface

[1mSYNOPSIS[0m
      [1m#include <Cmutex.h>[0m

      [1mvoid  Cmutex_init(int  (*[4m[22mlockroutine[24m[1m)(void  *[4m[22maddr[24m[1m,  int  [4m[22mtimeout[24m[1m),  int[0m
      [1m(*[4m[22munlockroutine[24m[1m)(void * [4m[22maddr[24m[1m));[0m

      [1mint Cmutex_lock(void *[4m[22maddr[24m[1m, int [4m[22mtimeout[24m[1m);[0m

      [1mint Cmutex_unlock(void *[4m[22maddr[24m[1m);[0m

[1mDESCRIPTION[0m
      [1mCmutex [22mis a common API interface for application compiled or  not  with
      the multithread flag. If the application do never initialize the [1mCmutex[0m
      package, using [1mCmutex_init[22m, and two arguments that are the addresses of
      the  mutex  lock  and unlock functions, [1mlockfunction [22mand [1munlockfunction[0m
      respectively, then all [1mCmutex [22mcalls are dummy operations.

      Otherwise any call to [1mCmutex_lock [22mwill raise a call to  [1mlockfunction  [22m,
      and any call to [1mCmutex_unlock [22mwill raise a call to [1munlockfunction.[0m

      Please note that the [1mCmutex [22mpackage is initially meant to be interfaced
      with [1mCthread [22monly.

      [1mCmutex_lock [22mtakes as argument the address  [1maddr  [22mof  anything  that  is
      static in your userspace, such as a 'static int variable;' address (see
      [1mEXAMPLE [22msection below), and a [1mtimeout [22mexpressed in second unit.
       If [1mtimeout [22mis 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 [1mCthread_mutex_timedlock [22mdescription in the [1mCthread [22mman page.
      Return code of [1mCmutex_lock [22mis 0 if success, -1 on failure.  If  failure
      the [1mserrno [22merror code is set appropriately.

      [1mCmutex_unlock  [22mreleases  a  lock  that you previously gained using [1mCmu-[0m
      [1mtex_lock [22mand the same address value [1maddr.[0m
       Return code is 0 if success and -1 on failure, error code is  then  in
      the [1mserrno [22mvariable.

[1mERRORS[0m
      If  the [1mCthread [22minterface is chosen and activated, the errors value are
      in the [1mserrno [22mvariable:

      [1mSECTHREADINIT[0m
             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.

      [1mSECTHREADERR[0m
             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 [1mSEINTERNAL[0m

      [1mSEOPNOTSUP[0m
             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.

      [1mSEINTERNAL[0m
             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 mal-
             loc()), except those to the thread library (for which SECTHREAD-
             ERR  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).

      [1mSETIMEDOUT [22m(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.

      [1mEINVAL[0m
             Invalid parameters

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

      [1mEDEADLK[0m
             Deadlock

             Mutex    is    already    locked    by    the   calling   thread
             ([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this is not the  default
             and should not happen via [1mCmutex[22m)

      [1mEBUSY[0m
             Device or resource busy

             Mutex is already locked by another thread.

      [1mEPERM[0m
             Permission denied

             Mutex     is     now     owned    by    the    calling    thread
             ([1mPTHREAD_MUTEX_ERRORCHECK [22mmutexes only, this is not the  default
             and should not happen via [1mCmutex[22m)

[1mEXAMPLE[0m
      /*
       * Here follows an example. The call to [1mCthread_init [22mroutine 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 [1mCmutex [22mcalls.
       */
      #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)0,sstrerror(serrno));
        }
        if (Cmutex_unlock(&this) != 0) {
          fprintf(stderr,"### Cmutex_unlock (%s)0,sstrerror(serrno));
        }
      }

[1mSEE ALSO[0m
      [1mCthread[22m, [1mserrno[0m

[1mAUTHOR[0m
      [1mLCG Grid Deployment [22mTeam

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