Client Library - Thread API

Detailed Description

s_thread_* api is an abstract layer for system calls.

programmer should not use s_thread_sem_* calls, becouse they are designed to be used internally - especially for mutex and condition variable emulation -, and not supported for every operating system.

Example:
 s_thread_mutex_t *mut;
 s_thread_cond_t *cond;

 void * thread_function (void *arg)
 {
        int quit = 0;
        int *val = (int *) arg;
        while (!quit) {
                s_thread_mutex_lock(mut);
                if (*val == 0) {
                        quit = 1;
                } else {
                        *val = *val + 1;
                }
                s_thread_cond_signal(cond);
                s_thread_mutex_unlock(mut);
                sleep(3);
        }
        return NULL;
 }

 {
        int arg;
        int barg;
        int quit = 0;
        s_thread_t *tid;

        arg = 1;
        if (s_thread_mutex_init(&mut)) {
                // error
        }
        if (s_thread_cond_init(&cond)) {
                // error
        }
        if (s_thread_mutex_lock(mut)) {
                // error
        }
        tid = s_thread_create(&thread_function, &arg);
        if (tid == NULL) {
                // error
        }
        barg = arg;
        if (s_thread_mutex_unlock(mut)) {
                // error
        }
        while (!quit) {
                if (s_thread_mutex_lock(mut)) {
                        // error
                }
                while (barg == arg) {
                        if (s_thread_cond_wait(cond, mut)) {
                                // error
                        }
                }
                if (arg == 10) {
                        arg = 0;
                        quit = 1;
                }
                barg = arg;
                if (s_thread_mutex_unlock(mut)) {
                        // error
                }
        }
        if (s_thread_mutex_destroy(mut)) {
                // error
        }
        if (s_thread_cond_destroy(cond)) {
                // error
        }
 }


Functions

int s_thread_sem_create (s_thread_sem_t **sem, int initial)
 initialize the semaphore struct with an initial value
int s_thread_sem_destroy (s_thread_sem_t *sem)
 destroys the given semaphore
int s_thread_sem_wait (s_thread_sem_t *sem)
 waits on given semaphore
int s_thread_sem_wait_timeout (s_thread_sem_t *sem, int msec)
 waits on given semaphore with timeout
int s_thread_sem_post (s_thread_sem_t *sem)
 unlocks given semaphore
int s_thread_mutex_init (s_thread_mutex_t **mut)
 initialize the mutex struct
int s_thread_mutex_destroy (s_thread_mutex_t *mut)
 destroys the given mutex
int s_thread_mutex_lock (s_thread_mutex_t *mut)
 locks the given mutex
int s_thread_mutex_trylock (s_thread_mutex_t *mut)
 tries to lock the given mutex
int s_thread_mutex_unlock (s_thread_mutex_t *mut)
 unlocks the given mutex
int s_thread_cond_init (s_thread_cond_t **cond)
 initialize the condition variable struct
int s_thread_cond_destroy (s_thread_cond_t *cond)
 destroys the given condition variable
int s_thread_cond_signal (s_thread_cond_t *cond)
 signals waiter on given condition variable
int s_thread_cond_broadcast (s_thread_cond_t *cond)
 signals all waiters on given condition variable
int s_thread_cond_wait (s_thread_cond_t *cond, s_thread_mutex_t *mut)
 waits on condition variable
int s_thread_cond_timedwait (s_thread_cond_t *cond, s_thread_mutex_t *mut, int msec)
 waits on condition variable, with timeout
s_thread_t * s_thread_create (void *(*f)(void *), void *farg)
 creates a new thread of control that executes concurrently with the calling thread.
int s_thread_cancel (s_thread_t *tid)
 cancels the thread.
int s_thread_join (s_thread_t *tid, void **ret)
 suspends the execution of the calling thread until the thread identified by tid terminates, either by calling s_thread_exit or by being cancelled.
int s_thread_self (void)
 returns the thread identifier for the calling thread.
void s_thread_exit (void *ret)
 terminates the execution of the calling thread.

Function Documentation

int s_thread_cancel ( s_thread_t *  tid  ) 

cancels the thread.

Parameters:
*tid - thread id of the thread to cancel.
Returns:
0 on success, 1 on error.

int s_thread_cond_broadcast ( s_thread_cond_t *  cond  ) 

signals all waiters on given condition variable

Parameters:
*cond - address of the condition variable pointer.
Returns:
0 on success, 1 on error.

int s_thread_cond_destroy ( s_thread_cond_t *  cond  ) 

destroys the given condition variable

Parameters:
*cond - address of the condition variable pointer.
Returns:
0 on success, 1 on error.

int s_thread_cond_init ( s_thread_cond_t **  cond  ) 

initialize the condition variable struct

Parameters:
**cond - address of the condition variable pointer.
Returns:
0 on success, 1 on error.

int s_thread_cond_signal ( s_thread_cond_t *  cond  ) 

signals waiter on given condition variable

Parameters:
*cond - address of the condition variable pointer.
Returns:
0 on success, 1 on error.

int s_thread_cond_timedwait ( s_thread_cond_t *  cond,
s_thread_mutex_t *  mut,
int  msec 
)

waits on condition variable, with timeout

Parameters:
*cond - address of the condition variable pointer.
*mut - address of the mutex pointer.
*msec - timeout value in mili seconds.
Returns:
0 on success, 1 on error.

int s_thread_cond_wait ( s_thread_cond_t *  cond,
s_thread_mutex_t *  mut 
)

waits on condition variable

Parameters:
*cond - address of the condition variable pointer.
*mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

s_thread_t* s_thread_create ( void *(*)(void *)  f,
void *  farg 
)

creates a new thread of control that executes concurrently with the calling thread.

The new thread applies the function passing it as first argument.

Parameters:
*f - pointer to the function.
*farg - argument to pass to function.
Returns:
NULL on error, otherwise address of the thread id.

int s_thread_join ( s_thread_t *  tid,
void **  ret 
)

suspends the execution of the calling thread until the thread identified by tid terminates, either by calling s_thread_exit or by being cancelled.

Parameters:
*tid - thread id of the thread to cancel.
**ret - return value of the thread.
Returns:
0 on success, 1 on error.

int s_thread_mutex_destroy ( s_thread_mutex_t *  mut  ) 

destroys the given mutex

Parameters:
*mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

int s_thread_mutex_init ( s_thread_mutex_t **  mut  ) 

initialize the mutex struct

Parameters:
**mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

int s_thread_mutex_lock ( s_thread_mutex_t *  mut  ) 

locks the given mutex

Parameters:
*mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

int s_thread_mutex_trylock ( s_thread_mutex_t *  mut  ) 

tries to lock the given mutex

Parameters:
*mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

int s_thread_mutex_unlock ( s_thread_mutex_t *  mut  ) 

unlocks the given mutex

Parameters:
*mut - address of the mutex pointer.
Returns:
0 on success, 1 on error.

int s_thread_self ( void   ) 

returns the thread identifier for the calling thread.

Returns:
th thread id.

int s_thread_sem_create ( s_thread_sem_t **  sem,
int  initial 
)

initialize the semaphore struct with an initial value

Parameters:
**sem - address of the semaphore pointer.
initial - initial value.
Returns:
0 on success, 1 on error.

int s_thread_sem_destroy ( s_thread_sem_t *  sem  ) 

destroys the given semaphore

Parameters:
*sem - address of the semaphore pointer.
Returns:
0 on success, 1 on error.

int s_thread_sem_post ( s_thread_sem_t *  sem  ) 

unlocks given semaphore

Parameters:
*sem - address of the semaphore pointer.
Returns:
0 on success, 1 on error.

int s_thread_sem_wait ( s_thread_sem_t *  sem  ) 

waits on given semaphore

Parameters:
*sem - address of the semaphore pointer.
Returns:
0 on success, 1 on error.

int s_thread_sem_wait_timeout ( s_thread_sem_t *  sem,
int  msec 
)

waits on given semaphore with timeout

Parameters:
*sem - address of the semaphore pointer.
msec - timeout in mili seconds.
Returns:
0 on success, 1 on timeout, -1 on error.

Generated on Wed Dec 27 17:53:06 2006 for xynth-0.8.40 by  doxygen 1.4.7