TNeoKernel  v1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Enumerations | Functions
tn_mutex.h File Reference

Detailed Description

A mutex is an object used to protect shared resource.

There is a lot of confusion about differences between semaphores and mutexes, so, it's quite recommended to read small article by Michael Barr: Mutexes and Semaphores Demystified.

Very short:

While mutex is seemingly similar to a semaphore with maximum count of 1 (the so-called binary semaphore), their usage is very different: the purpose of mutex is to protect shared resource. A locked mutex is "owned" by the task that locked it, and only the same task may unlock it. This ownership allows to implement algorithms to prevent priority inversion. So, mutex is a locking mechanism.

Semaphore, on the other hand, is signaling mechanism. It's quite legal and encouraged for semaphore to be acquired in the task A, and then signaled from task B or even from ISR. It may be used in situations like "producer and consumer", etc.

In addition to the article mentioned above, you may want to look at the related question on

Mutex features in TNeoKernel:

A discussion about strengths and weaknesses of each protocol as well as priority inversions problem is beyond the scope of this document.

The priority inheritance protocol solves the priority inversions problem but doesn't prevents deadlocks, although the kernel can notify you if a deadlock has occured (see TN_MUTEX_DEADLOCK_DETECT).

The priority ceiling protocol prevents deadlocks and chained blocking but it is slower than the priority inheritance protocol.

See also

Definition in file tn_mutex.h.

Go to the source code of this file.

Data Structures

struct  TN_Mutex
 Mutex. More...


 Mutex protocol for avoid priority inversion. More...


enum TN_RCode tn_mutex_create (struct TN_Mutex *mutex, enum TN_MutexProtocol protocol, int ceil_priority)
 Construct the mutex. More...
enum TN_RCode tn_mutex_delete (struct TN_Mutex *mutex)
 Destruct mutex. More...
enum TN_RCode tn_mutex_lock (struct TN_Mutex *mutex, TN_Timeout timeout)
 Lock mutex. More...
enum TN_RCode tn_mutex_lock_polling (struct TN_Mutex *mutex)
 The same as tn_mutex_lock() with zero timeout. More...
enum TN_RCode tn_mutex_unlock (struct TN_Mutex *mutex)
 Unlock mutex. More...

Enumeration Type Documentation

Mutex protocol for avoid priority inversion.


Mutex uses priority ceiling protocol.


Mutex uses priority inheritance protocol.

Definition at line 109 of file tn_mutex.h.

Function Documentation

enum TN_RCode tn_mutex_create ( struct TN_Mutex mutex,
enum TN_MutexProtocol  protocol,
int  ceil_priority 

Construct the mutex.

The field id_mutex should not contain TN_ID_MUTEX, otherwise, TN_RC_WPARAM is returned.

(refer to Legend for details)

mutexPointer to already allocated struct TN_Mutex
protocolMutex protocol: priority ceiling or priority inheritance. See enum TN_MutexProtocol.
ceil_priorityUsed if only protocol is TN_MUTEX_PROT_CEILING: maximum priority of the task that may lock the mutex.
enum TN_RCode tn_mutex_delete ( struct TN_Mutex mutex)

Destruct mutex.

All tasks that wait for lock the mutex become runnable with TN_RC_DELETED code returned.

(refer to Legend for details)

mutexmutex to destruct
enum TN_RCode tn_mutex_lock ( struct TN_Mutex mutex,
TN_Timeout  timeout 

Lock mutex.

  • If the mutex is not locked, function immediately locks the mutex and returns TN_RC_OK.
  • If the mutex is already locked by the same task, lock count is merely incremented and TN_RC_OK is returned immediately.
  • If the mutex is locked by different task, behavior depends on timeout value: refer to TN_Timeout.
(refer to Legend for details)

mutexmutex to lock
timeoutrefer to TN_Timeout
See also
enum TN_RCode tn_mutex_lock_polling ( struct TN_Mutex mutex)

The same as tn_mutex_lock() with zero timeout.

(refer to Legend for details)

enum TN_RCode tn_mutex_unlock ( struct TN_Mutex mutex)

Unlock mutex.

  • If mutex is not locked or locked by different task, TN_RC_ILLEGAL_USE is returned.
  • If mutex is already locked by calling task, lock count is decremented. Now, if lock count is zero, mutex gets unlocked (and if there are task(s) waiting for mutex, the first one from the wait queue locks the mutex). Otherwise, mutex remains locked with lock count decremented and function returns TN_RC_OK.
(refer to Legend for details)