Cmutex(3)

1CMUTEX(3)                  Common Library Functions                  CMUTEX(3)
2
3
4

NAME

6       Cmutex - LCG Mutex inferface
7

SYNOPSIS

9       #include <Cmutex.h>
10
11       void  Cmutex_init(int  (*lockroutine)(void  *addr,  int  timeout),  int
12       (*unlockroutine)(void * addr));
13
14       int Cmutex_lock(void *addr, int timeout);
15
16       int Cmutex_unlock(void *addr);
17
18
19

DESCRIPTION

21       Cmutex is a common API interface for application compiled or  not  with
22       the multithread flag. If the application do never initialize the Cmutex
23       package, using Cmutex_init, and two arguments that are the addresses of
24       the  mutex  lock  and unlock functions, lockfunction and unlockfunction
25       respectively, then all Cmutex calls are dummy operations.
26
27       Otherwise any call to Cmutex_lock will raise a call to  lockfunction  ,
28       and any call to Cmutex_unlock will raise a call to unlockfunction.
29
30       Please note that the Cmutex package is initially meant to be interfaced
31       with Cthread only.
32
33       Cmutex_lock takes as argument the address  addr  of  anything  that  is
34       static in your userspace, such as a 'static int variable;' address (see
35       EXAMPLE section below), and a timeout expressed in second unit.
36        If timeout is lower than zero, the  operation  will  block  until  the
37       mutex  is  granted.  If  it is zero, the operation will try to have the
38       mutex and immediately return, possibly with failure. If it  is  greater
39       than  zero, operation will exit if the timeout is reached. Please refer
40       to Cthread_mutex_timedlock description in the Cthread man page.
41       Return code of Cmutex_lock is 0 if success, -1 on failure.  If  failure
42       the serrno error code is set appropriately.
43
44       Cmutex_unlock  releases  a  lock  that you previously gained using Cmu‐
45       tex_lock and the same address value addr.
46        Return code is 0 if success and -1 on failure, error code is  then  in
47       the serrno variable.
48
49

ERRORS

51       If  the Cthread interface is chosen and activated, the errors value are
52       in the serrno variable:
53
54
55       SECTHREADINIT
56              LCG Thread interface initialization error
57
58              A thread initialisation call failed. In principle, on UNIX  this
59              will   be   a   call   to   pthread_mutex_init   (and   possibly
60              pthread_mutexattr_init) that failed, on Windows/NT this might be
61              a call to CreateMutex.
62
63       SECTHREADERR
64              LCG Thread interface failure in calling your thread library
65
66              A  thread  call  to your native system library (like the pthread
67              one on UNIX) failed. Please note that this is differentiated  to
68              the  Cthread  initialization and can happen if you are using too
69              much thread keys, for example. This is really a  run-time  error
70              only  concerning  your  operating  system  thread interface. Any
71              other system call failure, but not a thread one, and not at  the
72              initialisation step, will set serrno to SEINTERNAL
73
74       SEOPNOTSUP
75              Operation not supported
76
77              This  can  be  generated  only  if  you  compiled Cthread with a
78              -DCTHREAD_PROTO flag that Cthread do not know about. Check  your
79              LCG configuration site.def.
80
81       SEINTERNAL
82              Internal error
83
84              You  can  have more information by compiling the Cthread package
85              with the flag -DCTHREAD_DEBUG, and catching the printout on your
86              stderr  stream.  This  is any system call that failed (like mal‐
87              loc()), except those to the thread library (for which SECTHREAD‐
88              ERR  or SECTHREADINIT is to  be found), or any critical internal
89              run-time error (such as  a  non  correct  value  found  in  some
90              Cthread internal structures).
91
92       SETIMEDOUT (routines with a timeout parameter only)
93              Timed out
94
95              You called a routine with a timeout value greater than zero that
96              reached the maximum number of timeout seconds in waiting state.
97
98       EINVAL
99              Invalid parameters
100
101              You called a routine with  invalid  parameter(s).  Please  check
102              your code.
103
104       EDEADLK
105              Deadlock
106
107              Mutex    is    already    locked    by    the   calling   thread
108              (PTHREAD_MUTEX_ERRORCHECK mutexes only, this is not the  default
109              and should not happen via Cmutex)
110
111       EBUSY
112              Device or resource busy
113
114              Mutex is already locked by another thread.
115
116       EPERM
117              Permission denied
118
119              Mutex     is     now     owned    by    the    calling    thread
120              (PTHREAD_MUTEX_ERRORCHECK mutexes only, this is not the  default
121              and should not happen via Cmutex)
122
123

EXAMPLE

125       /*
126        * Here follows an example. The call to Cthread_init routine shows
127        * that multi-threaded mode is explicitly activated by the application
128        * (you will then have to link with the thread library). Neverthless,
129        * you can very well call some other external library, and leave as it is
130        * the Cmutex calls.
131        */
132       #include <Cmutex.h>
133       #include <Cthread_api.h>
134       #include <serrno.h>
135       #include <stdio.h>
136       #include <stdlib.h>
137       #include <string.h>
138       #include <log.h>
139
140       int this;
141       extern int Cthread_debug;
142
143       int main() {
144         Cthread_init();        /* Comment this and Cmutex calls will become dummy */
145
146         initlog("testit",LOG_INFO,"");
147
148         if (Cmutex_lock(&this,10) != 0) {
149           fprintf(stderr,"### Cmutex_lock (%s)\n",sstrerror(serrno));
150         }
151         if (Cmutex_unlock(&this) != 0) {
152           fprintf(stderr,"### Cmutex_unlock (%s)\n",sstrerror(serrno));
153         }
154       }
155
156

AUTHOR

162       LCG Grid Deployment Team
163
164
165
166LCG          $Date: 2010-04-05 09:51:26 +0200 (Mon, 05 Apr 2010) $   CMUTEX(3)

NAME

SYNOPSIS

DESCRIPTION

ERRORS

EXAMPLE

SEE ALSO

AUTHOR