Unison/NANO: mutex

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_timedlock(pthread_mutex_t *mp,: const struct timespec *abs_timeout);
int pthread_mutex_trylock(pthread_mutex_t *mp);
int pthread_mutex_unlock(pthread_mutex_t *mp);
int pthread_mutex_getlock_np(pthread_mutex_t *mp); - non POSIX function
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 attr. If attr is NULL, the default mutex attributes are used.

In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated:
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 mp. 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.

The pthread_mutex_timedlock() function locks the mutex object referenced by mp. If the mutex is already locked, the calling thread blocks until the mutex becomes available as in the pthread_mutex_lock() function. If the mutex cannot be locked without waiting for another thread to unlock the mutex, this wait will be terminated when the specified timeout expires.
The timeout will expire when the absolute time specified by abs_timeout passes, as measured by the CLOCK_REALTIME clock (that is, when the value of that clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time of the call.
Under no circumstance will the function fail with a timeout if the mutex can be locked immediately. The validity of the abs_timeout parameter will not be checked if the mutex can be locked immediately.

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 a thread attempts to unlock a mutex that is unlocked, it will return with an error.

pthread_mutex_getlock_np() is the non POSIX function. It returns mutex mp lock state.

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.

Mutex types

When the mutex has specific type attribute, it behavior may be different. The mutex types are described below:

PTHREAD_MUTEX_NORMAL: A normal type mutex does not detect deadlock. Attempting to relock the mutex causes deadlock. The mutex is either in a locked or unlocked state for a thread.
PTHREAD_MUTEX_ERRORCHECK: An errorcheck type mutex provides error checking. If a thread attempts to relock a mutex that it has already locked, an error will be returned. If a thread attempts to unlock a mutex and the thread in not the owner of the mutex, an error will be returned.
PTHREAD_MUTEX_RECURSIVE: A recursive type mutex permits a thread to lock many times. When a thread successfully acquires a mutex for the first time, the lock count will be set to one. Every time a thread relocks this mutex, the lock count will be incremented by one. Each time the thread unlocks the mutex, the lock count will be decremented by one. When the lock count reaches zero, the mutex will become available for other threads to acquire. If a thread attempts to unlock a mutex and the thread in not the owner of the mutex, an error will be returned.
PTHREAD_MUTEX_DEFAULT: The default type mutex is mapped to a normal type mutex.

RETURN VALUES

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

ERRORS

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

EDEADLK: The mutex pointed to by mp was already locked.

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

EDEADLK: The mutex pointed to by mp was already locked.
EINVAL: The thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
ETIMEDOUT: The mutex could not be locked before the specified timeout expired.

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

EBUSY: The mutex could not be acquired because it was already locked.

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

EPERM: The mutex type is not locked or locked by another thread.

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.