Initialize a pre-allocated mutex. The name passed is used for debug etc. 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.

void kgi_mutex_init(

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

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

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

Release a mutex. Memory allocated for the mutex itself is not freed. But memory allocated for event management is.

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
);