bionic (3) Cmutex.3.gz

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