NAME
Cthread - LCG Thread inferface
SYNOPSIS
#include <Cthread_api.h>
int Cthread_create(void *(*startroutine)(void *), void * arg);
int Cthread_create_detached(void *(*startroutine)(void *),void *arg);
int Cthread_join(int cid, int **status);
int Cthread_mutex_lock(void *addr);
int Cthread_mutex_trylock(void *addr);
int Cthread_mutex_timedlock(void *addr, int timeout);
int Cthread_mutex_unlock(void *addr);
int Cthread_mutex_destroy(void *addr);
int Cthread_cond_wait(void *addr);
int Cthread_cond_timedwait(void *addr, int timeout);
int Cthread_cond_signal(void *addr);
int Cthread_cond_broadcast(void *addr);
int Cthread_detach(int cid);
int Cthread_kill(int cid, int signo);
int Cthread_exit(void *status);
int Cthread_self(void);
int Cthread_getspecific(int *global_key, void **addr);
int Cthread_setspecific(int *global_key, void * addr);
DESCRIPTION
Cthread is a common API interface for multithreaded programs, although
there is also support for nonthreaded application, where some of the
Cthread functions then becomes useless.
For non-thread applications see the section NON-THREAD ENVIRONMENT
Any created thread is identified uniquely with a cid, standing for
Cthread identifier.
In multithread environment, Cthread is an interface to pthread
functions on UNIX, and an interface to Win32 C-runtime library on
Windows/NT.
Cthread_create is creating a thread given its starting point
startroutine and its arguments arg address. The thread is created with
the default parameters, e.g. it is a joinable thread.
Return value is the Cthread identifier cid , greater or equal to zero,
or -1 on error.
Cthread_create_detached takes the same arguments as Cthread_create and
(tries) to create a detachable thread, which will then make it act as a
daemon. This means that ressources used by this thread will be freed
immediately when it terminates. On the other hand, such thread cannot
be synchronized with other threads using the Cthread_join method.
You have to remind that creating a detachable thread do not work
immediately at the creation step on every thread implementation, in
particular in the DCE threads. If the implementation do not allow this
at creation time, then Cthread_create_detached calls Cthread_create.
Please have a look at Cthread_detach section.
Return value is the Cthread identifier cid , greater or equal to zero,
or -1 on error.
Cthread_exit makes current thread exiting. If status isn’t NULL, it is
assumed to point to an integer whose value if the status that a
Cthread_join would received, in case the thread is joinable. Please
note that Cthread_exit is dangerous and non-recommended on Windows
platform.
Return value is 0 on success, or -1 on error.
Cthread_kill sends signo signal number to the thread cid. This affect
the status that a Cthread_join would received, in case the thread to be
killed is joinable. Please note that Cthread_kill is not supported on
DCE threads.
Return value is 0 on success, or -1 on error.
Cthread_join suspends the calling thread until the one identified with
the Cthread identifier cid terminates. If the status parameter is not
NULL, the status of the terminating thread cid is stored there. This
status is the pointer returned by thread cid at its end.
Return value is 0 on success, or -1 on error.
Cthread_mutex_lock is an alias for Cthread_mutex_timedlock with a
timeout of -1.
Cthread_mutex_trylock is an alias for Cthread_mutex_timedlock with a
timeout of 0.
Cthread_mutex_timedlock is acquiring a mutex, creating it if necessary,
on the addr address. The second parameter is the eventual timeout in
seconds. If this parameter is < 0, the calling thread is suspended
until it is granted access to addr , if it is zero, the calling thread
will try to gain the lock, and if it is greater than zero the calling
thread will wait up to timeout seconds.
Please note that, in Cthread, a creation of a mutex is always
associated with a creation of a conditionnal variable. See
Cthread_cond_timedwait and Cthread_cond_broadcast_.
Return value is 0 on success, or -1 on error.
Cthread_mutex_unlock is unlocking the mutex that the calling thread is
assumed to have acquired previously, calling Cthread_mutex_timedlock on
the addr address.
Cthread_cond_wait is an alias for Cthread_cond_timedwait with a timeout
of -1.
Cthread_cond_timedwait is waiting for a condition variable, which is,
by default in Cthread, broadcasted, associated with a mutex previously
created on the addr address. Calling this function before the creation
and the lock of a mutex, with Cthread_mutex_timedlock is a programming
error.
While the thread is waiting on a condition to arise on the addr
address, the corresponding lock is released. It will be acquired as
soon as the condition happens. Please note that the use of condition is
subject to normal thread programming rules, e.g. the lock, a loop on a
predicate, a wait inside the loop, and the unlock.
If the timeout parameter, in seconds, is greater than zero, then the
function will not suspend the calling thread more than this limit.
Return value is 0 on success, or -1 on error.
Cthread_cond_signal is an alias for Cthread_cond_broadcast.
Cthread_cond_broadcast restarts threads that are waiting on a condition
variable vs. addr address.
Return value is 0 on success, or -1 on error.
Cthread_detach is detaching the calling thread, identified with cid
Cthread identifier. Whereas the normal thread packages that allow a
thread to be detached at the creation step, see
Cthread_create_detached, returns an error if such a detached thread
tries to detach himself again, Cthread_detach will not, because of this
different behaviour vs. different thread implementations: it is not
possible everywhere to create a detached thread immediately, like in
DCE threads.
This means that if a user is creating a thread with Cthread_create or
Cthread_create_detached, the created thread will, in any case, be
allowed to call Cthread_detach: if the calling thread is not yet
detached, it will be changed so forth, and if the calling thread is
already detached, the return value will be 0.
Return value is 0 on success, or -1 on error.
Cthread_mutex_destroy is removing its corresponding entry in Cthread
internal linked list, freeing all thread associated stuff, like the
mutex itself, and the conditionnal variable (see
Cthread_mutex_timedlock).
Return value is 0 on success, or -1 on error.
Cthread_self is returning the Cthread identifier cid of the calling
thread.
Return value is the cid (greater or equal to zero) on success, or -1 on
error.
Cthread_getspecific is creating and/or getting a thread-specific
storage address for every instance of the global_key address, storing
its result in addr location. The first time it is called, the stored
result is NULL, next time it will be the address of the memory the user
would have previously allocated and associated with the key using
Cthread_setspecific.
Return value is 0 on success, or -1 on error.
Cthread_setspecific is associating a memory, starting at addr that he
have previously allocated, with the global_key address. If he tries to
do so without calling previously Cthread_getspecific, then such a call
will be done internally.
Return value is 0 on success, or -1 on error.
ERRORS
Beyond the errno value, Cthread is setting the serrno value to generic
values that can be:
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.
EXAMPLES
Here is an example with thread-specific data
#include <Cthread_api.h> /* Cthread include file */
#include <stdio.h> /* For I/O functions and definitions */
#define NTHREADS 5 /* Number of threads */
#define NLOOP 5 /* Number of loops in threads */
static int global_key;
/* Internal Prototypes */
void *mythread(void *);
void testit();
int main() {
int i, n;
for (i=1; i <= NTHREADS; i++) {
if ((n = Cthread_create(&mythread,NULL)) < 0) {
exit(EXIT_FAILURE);
} else {
fprintf(stderr,"[main] --> Created Cthread ID %d\n",n);
}
}
sleep(NTHREADS);
exit(EXIT_SUCCESS);
}
void *mythread(void *arg) {
int i;
/* Call the same routine NLOOP times */
for (i=1; i <= NLOOP; i++) {
testit();
}
return(NULL);
}
void testit() {
char *addr = NULL;
int n;
if ((n = Cthread_detach(Cthread_self())))
exit(EXIT_FAILURE);
if ((n = Cthread_getspecific(&global_key,(void **) &addr)))
exit(EXIT_FAILURE);
if (addr == NULL) {
addr = malloc(100);
fprintf(stderr,"[%d] --> new 0x%x\n",
Cthread_self(),addr);
if (Cthread_setspecific(&global_key,addr))
exit(EXIT_FAILURE);
} else {
fprintf(stderr,"[%d] --> old 0x%x\n",
Cthread_self(),addr);
}
sprintf(addr,"[%d] Print with TSD buffer : Cthread ID=%d\n",
Cthread_self(),Cthread_self());
fprintf(stderr,addr);
return;
}
NON-THREAD ENVIRONMENT
In such an environment, almost all methods becomes no-op, except:
Creation of process(es):
Cthread_create
Cthread_create_detached (equivalent to Cthread_create)
Cthread_join
Use of "Process"-specific variables:
Cthread_getspecific
Cthread_setspecific
For these two last functions, Cthread will garbage itself its
eventual list of "Process"-specific variables. This means that,
as in a thread environment, the user will not have to free
memory allocated and registered with a call to
Cthread_setspecific.
SEE ALSO
pthread, DCE, LinuxThreads, Win32
AUTHOR
LCG Grid Deployment Team