Cmutex(3) 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));
  }
}

AUTHOR

LCG Grid Deployment Team

LAST SEARCHED