NAME

pthread_mutex_init, pthread,mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, pthread_mutex_destroy – mutual exclusion locks

SYNOPSIS

#include <pthread.h>

int pthread_mutex_init(pthread_mutex_t *mp,

const pthread_mutexattr_t *attr );

int pthread_mutex_lock(pthread_mutex_t *mp );

int pthread_mutex_trylock(pthread_mutex_t *mp );

int pthread_mutex_unlock(pthread_mutex_t *mp );

int pthread_mutex_destroy(pthread_mutex_t *mp );

pthread_mutex_trylock() and pthread_mutex_unlock() are callable from an ISR.

DESCRIPTION

Mutual exclusion locks (mutexes) prevent multiple threads from simultaneously executing critical sections of code which access shared data (i.e., mutexes are used to serialize the execution of threads). All mutexes must be global. A successful call for a mutex lock via pthread_mutex_lock() will cause another thread that is also trying to lock the same mutex to block until the owner thread unlocks it via pthread_mutex_unlock()

Initialize

A mutex must be initialized with a call to pthread_mutex_init() before it can be used. The pthread_mutex_init() function initializes the mutex referenced by mp with attributes specified by:

pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER(mut);

Lock and Unlock

A critical section of code is enclosed by a the call to lock the mutex and the call to unlock the mutex to protect it from simultaneous access by multiple threads. Only one thread at a time may possess mutually exclusive access to the critical section of code that is enclosed by the mutex-locking call and the mutex-unlocking call to protect the shared data. A thread calling to lock the mutex either gets exclusive access to the code starting from the successful locking until its call to unlock the mutex, or it waits until the mutex is unlocked by the thread that locked it.

Mutexes have ownership, unlike semaphores. Although any thread, within the scope of a mutex, can get an unlocked mutex and lock access to the same critical section of code, only the thread that locked a mutex can unlock it.

A call to pthread_mutex_lock() locks the mutex object referenced by If the mutex is already locked, the calling thread blocks until the mutex is freed; this will return with the mutex object referenced by mp in the locked state with the calling thread as its owner. If the current owner of a mutex tries to relock the mutex, it will result in deadlock.

pthread_mutex_trylock() is the same as pthread_mutex_lock() except that if the mutex object referenced by mp is locked (by any thread, including the current thread), the call returns immediately with an error.

pthread_mutex_unlock() is called by the owner of the mutex object referenced by mp to release it. The mutex must be locked and the calling thread must be the one that last locked the mutex (the owner). If there are threads blocked on the mutex object referenced by mp when pthread_mutex_unlock() is called, the mp is freed, and the scheduling policy will determine which thread gets the mutex. If the calling thread is not the owner of the lock, no error status is returned, and the behavior of the program is undefined.

Destroy

If there is no waiting threads, pthread_mutex_destroy() destroys the mutex object referenced by the mutex object and it becomes uninitialized. The space used by the destroyed mutex variable is not freed. It needs to be explicitly reclaimed if it was dynamically allocated. Stack based allocation is common and does not permit deallocation until the stack frame is destoyed.

RETURN VALUES

If successful, all of these functions return 0 ; otherwise, an error number is returned.

ERRORS

These functions fail and return the corresponding value if any of the following conditions are detected: pthread_mutex_trylock() fails and returns the corresponding value if any of the following conditions occur:

EBUSY

The mutex pointed to by mp was already locked.

pthread_mutex_destroy() fails and returns the corresponding value if any of the following conditions occur:

EBUSY

The mutex pointed to by mp has threads waiting on it.