\fBCmutex\fP is a common API interface for application compiled or not with the multithread flag. If the application do never initialize the \fBCmutex\fP package, using \fBCmutex_init\fP, and two arguments that are the addresses of the mutex lock and unlock functions,
.BI lockfunction
and
.BI unlockfunction
respectively, then all \fBCmutex\fP calls are dummy operations.
.P
Otherwise any call to \fBCmutex_lock\fP will raise a call to
.BI lockfunction
, and any call to \fBCmutex_unlock\fP will raise a call to
.BI unlockfunction.
.P
Please note that the \fBCmutex\fP package is initially meant to be interfaced with \fBCthread\fP only.
.P
\fBCmutex_lock\fP takes as argument the adress
.BI addr
of anything that is static in your userspace, such as a 'static int variable;' address (see \fBEXAMPLE\fP section below), and a
.BI timeout
expressed in second unit.
.br
If
.BI 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 \fBCthread_mutex_timedlock\fP description in the \fBCthread\fP man page.
.br
Return code of \fBCmutex_lock\fP is 0 if success, -1 on failure. If failure the \fBserrno\fP error code is set appropriately.
.P
\fBCmutex_unlock\fP releases a lock that you previously gained using \fBCmutex_lock\fP and the same address value
.BI addr.
.br
Return code is 0 if success and -1 on failure, error code is then in the \fBserrno\fP variable.
.SH ERRORS
If the \fBCthread\fP interface is chosen and activated, the errors value are in the \fBserrno\fP variable:
...
...
@@ -80,38 +113,6 @@ Permission denied
Mutex is now owned by the calling thread (\fBPTHREAD_MUTEX_ERRORCHECK\fP mutexes only, this is not the default and should not happen via \fBCmutex\fP)
.RE
.SH DESCRIPTION
\fBCmutex\fP is a common API interface for application compiled or not with the multithread flag. If the application do never initialize the \fBCmutex\fP package, using \fBCmutex_init\fP, and two arguments that are the addresses of the mutex lock and unlock functions,
.BI lockfunction
and
.BI unlockfunction
respectively, then all \fBCmutex\fP calls are dummy operations.
.P
Otherwise any call to \fBCmutex_lock\fP will raise a call to
.BI lockfunction
, and any call to \fBCmutex_unlock\fP will raise a call to
.BI unlockfunction.
.P
Please note that the \fBCmutex\fP package is initially meant to be interfaced with \fBCthread\fP only.
.P
\fBCmutex_lock\fP takes as argument the adress
.BI addr
of anything that is static in your userspace, such as a 'static int variable;' address (see \fBEXAMPLE\fP section below), and a
.BI timeout
expressed in second unit.
.br
If
.BI timeout
is lower than zero, the operation will block until the mutex is granted. If it is zero, the operation will try to have to mutex and immediately return, possibly with failure. If it is greated than zero, operation will exit if the timeout is reached. Please refer to \fBCthread_mutex_timedlock\fP description in the \fBCthread\fP man page.
.br
Return code of \fBCmutex_lock\fP is 0 if success, -1 on failure. If failure the \fBserrno\fP error code is set appropriately.
.P
\fBCmutex_unlock\fP releases a lock that you previously gained using \fBCmutex_lock\fP and the same address value
.BI addr.
.br
Return code is 0 if success and -1 on failure, error code is then in the \fBserrno\fP variable.
Beyond the errno value, \fBCthread\fP is setting the serrno value to generic values that can be:
.P
.B SECTHREADINIT
.RS
CASTOR Thread interface initialization error
.P
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.
.RE
.P
.B SECTHREADERR
.RS
CASTOR Thread interface failure in calling your thread library
.P
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 \fBSEINTERNAL\fP
.RE
.P
.B SEOPNOTSUP
.RS
Operation not supported
.P
This can be generated only if you compiled Cthread with a -DCTHREAD_PROTO flag that Cthread do not know about. Check your CASTOR configuration site.def.
.RE
.P
.B SEINTERNAL
.RS
Internal error
.P
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).
.RE
.P
.B SETIMEDOUT
(routines with a timeout parameter only)
.RS
Timed out
.P
You called a routine with a timeout value greater than zero that reached the maximum number of timeout seconds in waiting state.
.RE
.P
.B EINVAL
.RS
Invalid parameters
.P
You called a routine with invalid parameter(s). Please check your code.
.RE
.SH DESCRIPTION
\fBCthread\fP is a common API interface for multithreaded programs, although there is also support for nonthreaded application, where some of the \fBCthread\fP functions then becomes useless.
...
...
@@ -230,6 +184,53 @@ that he have previously allocated, with the
address. If he tries to do so without calling previously \fBCthread_getspecific\fP, then such a call will be done internally.
.P
Return value is 0 on success, or -1 on error.
.SH ERRORS
Beyond the errno value, \fBCthread\fP is setting the serrno value to generic values that can be:
.P
.B SECTHREADINIT
.RS
CASTOR Thread interface initialization error
.P
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.
.RE
.P
.B SECTHREADERR
.RS
CASTOR Thread interface failure in calling your thread library
.P
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 \fBSEINTERNAL\fP
.RE
.P
.B SEOPNOTSUP
.RS
Operation not supported
.P
This can be generated only if you compiled Cthread with a -DCTHREAD_PROTO flag that Cthread do not know about. Check your CASTOR configuration site.def.
.RE
.P
.B SEINTERNAL
.RS
Internal error
.P
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).
.RE
.P
.B SETIMEDOUT
(routines with a timeout parameter only)
.RS
Timed out
.P
You called a routine with a timeout value greater than zero that reached the maximum number of timeout seconds in waiting state.
.RE
.P
.B EINVAL
.RS
Invalid parameters
.P
You called a routine with invalid parameter(s). Please check your code.
