os::rtos::mutex::protocol Class Reference

Mutex protocols. More...

#include <cmsis-plus/rtos/os.h>

Public Types
enum	: protocol_t {   none = 0 ,   inherit = 1 ,   protect = 2 ,   default_ = inherit ,   max_ = protect }
	Enumeration of mutex protocols. More...

Detailed Description

Mutex protocols.

Allow to define the behaviour of the mutex related to scheduling.

The mutex protocol is defined via the mx_protocol attribute of the mutex::attributes class. Valid values are:

• mutex::protocol::none
• mutex::protocol::inherit
• mutex::protocol::protect

When a thread owns a mutex with the mutex::protocol::none protocol attribute, its priority and scheduling shall not be affected by its mutex ownership.

When a thread is blocking higher priority threads because of owning one or more robust mutexes with the mutex::protocol::inherit protocol attribute, it shall execute at the higher of its priority or the priority of the highest priority thread waiting on any of the robust mutexes owned by this thread and initialised with this protocol.

When a thread is blocking higher priority threads because of owning one or more non-robust mutexes with the mutex::protocol::inherit protocol attribute, it shall execute at the higher of its priority or the priority of the highest priority thread waiting on any of the non-robust mutexes owned by this thread and initialised with this protocol.

When a thread owns one or more robust mutexes initialised with the mutex::protocol::protect protocol, it shall execute at the higher of its priority or the highest of the priority ceilings of all the robust mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these robust mutexes or not.

When a thread owns one or more non-robust mutexes initialised with the mutex::protocol::protect protocol, it shall execute at the higher of its priority or the highest of the priority ceilings of all the non-robust mutexes owned by this thread and initialised with this attribute, regardless of whether other threads are blocked on any of these non-robust mutexes or not.

If a thread simultaneously owns several mutexes initialised with different protocols, it shall execute at the highest of the priorities that it would have obtained by each of these protocols (this requirement makes most of the specific max requirements above irrelevant, a global max is easier to compute).

While a thread is holding a mutex which has been initialised with the mutex::protocol::inherit or mutex::protocol::protect protocol attributes, it shall not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed, such as by a call to thread::priority(int). Likewise, when a thread unlocks a mutex that has been initialised with the mutex::protocol::inherit or mutex::protocol::protect protocol attributes, it shall not be subject to being moved to the tail of the scheduling queue at its priority in the event that its original priority is changed (ILG: not sure what this means, currently after unlock() the thread priority returns to the assigned priority).

When a thread makes a call to mutex::lock(), the mutex was initialised with the protocol attribute having the value mutex::protocol::inherit, when the calling thread is blocked because the mutex is owned by another thread, that owner thread shall inherit the priority level of the calling thread as long as it continues to own the mutex. The implementation shall update its execution priority to the maximum of its assigned priority and all its inherited priorities. Furthermore, if this owner thread itself becomes blocked on another mutex with the protocol attribute having the value mutex::protocol::inherit, the same priority inheritance effect shall be propagated to this other owner thread, in a recursive manner.

POSIX compatibility

Inspired by pthread_mutexattr_setprotocol() from <pthread.h> (IEEE Std 1003.1, 2013 Edition).

Definition at line 79 of file os-mutex.h.

Member Enumeration Documentation

anonymous enum

anonymous enum : protocol_t

Enumeration of mutex protocols.

Enumerator
none	Priority and scheduling not affected by mutex ownership.
inherit	Inherit priority from highest priority thread.
protect	Execute at the highest priority.
default_	Default value. Differs from POSIX, which uses none.
max_	Maximum value, for validation purposes.

Definition at line 84 of file os-mutex.h.

---

The documentation for this class was generated from the following file:

• os-mutex.h