The kgi_mutex_t is an opaque structure. One shall use it with the following methods and never access it directly. It is OS specific and its content, its size may vary from one platform to another.


Allocate a mutex. mtx must be null. The return parameter is 0 (KGI_EOK) in case of success.

If the mutex has to be owned in the context of event synchronisation mechanisms, the number of different events has to be specified, otherwise KGI_MUTEX_NOEVENT shall be passed. Anyway nb_event can't exceed the maximum number KGI_MUTEX_MAXEVENT.

kgi_u_t kgi_mutex_alloc(

 /* Comment: pointer to the mutex to initialize */
 kgi_mutex_t *mtx,

 /* Comment: max number of events */
 kgi_u_t nb_events


Free a mutex. The mutex must have be done before free. mtx is null when returning from this function. Memory allocated for event management is also freed.

void kgi_mutex_free(

 /* Comment: pointer to the mutex to free */
 kgi_mutex_t *mtx


Initialize a pre-allocated mutex. The name passed is used for debug etc.

void kgi_mutex_init(

 /* Comment: pointer to the mutex to initialize */
 kgi_mutex_t *mtx,

 /* Comment: name of the mutex */
 const char *name


Release a mutex. Memory allocated for the mutex itself is not freed.

void kgi_mutex_done(

 /* Comment: pointer to the mutex to release */
 kgi_mutex_t *mtx


Lock the mutex. If the mutex is not free, the thread is blocked.

void kgi_mutex_lock(

 /* Comment: pointer to the mutex to lock */
 kgi_mutex_t *mtx


Unlock the mutex previously locked.

void kgi_mutex_unlock(

 /* Comment: pointer to the mutex to unlock */
 kgi_mutex_t *mtx


Wait on event e.g unlock the mutex and add the thread to the list of waiting threads on this event. When the thread is made runnable again, it owns the mutex.

Important: the mutex must be already locked by the current running thread when calling kgi_mutex_wait().

Callers are responsible for managing the relationship between event ids and their signification. the event parameter can't exceed nb_events passed when the mutex was initialized.

void kgi_mutex_wait(

 /* Comment: pointer to the mutex hold */
 kgi_mutex_t *mtx,

 /* Comment: the event to wait on */
 kgi_u_t event


Wakeup threads waiting on an event to occur with mutex ownership. If unblock_all is TRUE then unblock all waiters otherwise only one.

void kgi_mutex_signal(

 /* Comment: pointer to the mutex processes are blocked on */
 kgi_mutex_t *mtx,

 /* Comment: event to signal */
 kgi_u_t event,

 /* Comment: 1 = unblock all processes waiting on the mutex, 0 = unblock only the next one */
 int unblock_all

KgiMutexAPI (last edited 2008-06-17 21:38:26 by localhost)