µOS++ IIIe / CMSIS++ / POSIX++ Reference  v6.3.11
“Perfekt ist nicht gut genug”
The third edition of µOS++ and CMSIS++, a proposal for the next generation CMSIS, written in C++.

C API mutex definitions. More...

Classes

struct  os_mutex_attr_s
 Mutex attributes. More...
 
struct  os_mutex_s
 Mutex object storage. More...
 

Types

typedef struct os_mutex_attr_s os_mutex_attr_t
 Mutex attributes. More...
 
typedef struct os_mutex_s os_mutex_t
 Mutex object storage. More...
 

Enumerations

enum  {
  os_mutex_protocol_none = 0,
  os_mutex_protocol_inherit = 1,
  os_mutex_protocol_protect = 2,
  os_mutex_protocol_default = os_mutex_protocol_inherit
}
 An enumeration with mutex protocols. More...
 
enum  {
  os_mutex_robustness_stalled = 0,
  os_mutex_robustness_robust = 1,
  os_mutex_robustness_default = os_mutex_robustness_stalled
}
 An enumeration with mutex robustness. More...
 
enum  {
  os_mutex_type_normal = 0,
  os_mutex_type_errorcheck = 1,
  os_mutex_type_recursive = 2,
  os_mutex_type_default = os_mutex_type_normal
}
 An enumeration with mutex types. More...
 

Compatibility Macros

#define os_mutex_create   os_mutex_construct
 
#define os_mutex_recursive_create   os_mutex_recursive_construct
 
#define os_mutex_destroy   os_mutex_destruct
 

Mutex Attributes Functions

void os_mutex_attr_init (os_mutex_attr_t *attr)
 Initialise the mutex attributes. More...
 
void os_mutex_attr_recursive_init (os_mutex_attr_t *attr)
 Initialise the recursive mutex attributes. More...
 
const os_mutex_attr_tos_mutex_attr_get_recursive (void)
 Get a recursive mutex attributes object instance. More...
 

Mutex Creation Functions

void os_mutex_construct (os_mutex_t *mutex, const char *name, const os_mutex_attr_t *attr)
 Construct a statically allocated mutex object instance. More...
 
void os_mutex_recursive_construct (os_mutex_t *mutex, const char *name, const os_mutex_attr_t *attr)
 Construct a statically allocated recursive mutex object instance. More...
 
void os_mutex_destruct (os_mutex_t *mutex)
 Destruct the statically allocated mutex object instance. More...
 
os_mutex_tos_mutex_new (const char *name, const os_mutex_attr_t *attr)
 Allocate a mutex object instance and construct it. More...
 
os_mutex_tos_mutex_recursive_new (const char *name, const os_mutex_attr_t *attr)
 Allocated a recursive mutex object instance and construct it. More...
 
void os_mutex_delete (os_mutex_t *mutex)
 Destruct the mutex object instance and deallocate it. More...
 

Mutex Functions

const char * os_mutex_get_name (os_mutex_t *mutex)
 Get the mutex name. More...
 
os_result_t os_mutex_lock (os_mutex_t *mutex)
 Lock/acquire the mutex. More...
 
os_result_t os_mutex_try_lock (os_mutex_t *mutex)
 Try to lock/acquire the mutex. More...
 
os_result_t os_mutex_timed_lock (os_mutex_t *mutex, os_clock_duration_t timeout)
 Timed attempt to lock/acquire the mutex. More...
 
os_result_t os_mutex_unlock (os_mutex_t *mutex)
 Unlock/release the mutex. More...
 
os_thread_prio_t os_mutex_get_prio_ceiling (os_mutex_t *mutex)
 Get the priority ceiling of a mutex. More...
 
os_result_t os_mutex_set_prio_ceiling (os_mutex_t *mutex, os_thread_prio_t prio_ceiling, os_thread_prio_t *old_prio_ceiling)
 Change the priority ceiling of a mutex. More...
 
os_result_t os_mutex_mark_consistent (os_mutex_t *mutex)
 Mark mutex as consistent. More...
 
os_thread_tos_mutex_get_owner (os_mutex_t *mutex)
 Get the thread that owns the mutex. More...
 
os_mutex_type_t os_mutex_get_type (os_mutex_t *mutex)
 Get the mutex type. More...
 
os_mutex_protocol_t os_mutex_get_protocol (os_mutex_t *mutex)
 Get the mutex protocol. More...
 
os_mutex_robustness_t os_mutex_get_robustness (os_mutex_t *mutex)
 Get the mutex robustness. More...
 
os_result_t os_mutex_reset (os_mutex_t *mutex)
 Reset the mutex. More...
 

Detailed Description

C API mutex definitions.

For the complete definition, see
RTOS C++ API
Examples
int
os_main (int argc, char* argv[])
{
{
os_mutex_construct (&mx1, "mx1", NULL);
os_mutex_lock (&mx1);
name = os_mutex_get_name (&mx1);
assert(strcmp (name, "mx1") == 0);
os_mutex_set_prio_ceiling (&mx1, prio, NULL);
th = os_mutex_get_owner (&mx1);
if (th != NULL)
{
}
}
{
// Custom mutex, with RTC.
amx2.mx_max_count = 7;
os_mutex_construct (&mx2, "mx2", &amx2);
}
{
// Recursive mutex.
}
{
// Custom recursive mutex, with RTC.
os_mutex_attr_init_recursive (&amx4);
os_mutex_construct (&mx4, "mx4", &amx4);
}
}

Macro Definition Documentation

#define os_mutex_create   os_mutex_construct

Definition at line 1445 of file os-c-api.h.

#define os_mutex_destroy   os_mutex_destruct

Definition at line 1447 of file os-c-api.h.

#define os_mutex_recursive_create   os_mutex_recursive_construct

Definition at line 1446 of file os-c-api.h.

Types

Mutex attributes.

Initialise this structure with os_mutex_attr_init() and then set any of the individual members directly.

See also
os::rtos::mutex::attributes
typedef struct os_mutex_s os_mutex_t

Mutex object storage.

This C structure has the same size as the C++ os::rtos::mutex object and must be initialised with os_mutex_create().

Later on a pointer to it can be used both in C and C++ to refer to the mutex object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also
os::rtos::mutex

Enumeration Type Documentation

anonymous enum

An enumeration with mutex protocols.

See also
os::rtos::mutex::protocol
Enumerator
os_mutex_protocol_none 

Priority and scheduling not affected by mutex ownership.

os_mutex_protocol_inherit 

Inherit priority from highest priority thread.

os_mutex_protocol_protect 

Execute at the highest priority.

os_mutex_protocol_default 

Default mutex protocol.

Definition at line 824 of file os-c-decls.h.

anonymous enum

An enumeration with mutex robustness.

See also
os::rtos::mutex::robustness
Enumerator
os_mutex_robustness_stalled 

Normal robustness.

os_mutex_robustness_robust 

Enhanced robustness at thread termination.

os_mutex_robustness_default 

Default mutex robustness.

Definition at line 852 of file os-c-decls.h.

anonymous enum

An enumeration with mutex types.

See also
os::rtos::mutex::type
Enumerator
os_mutex_type_normal 

Normal mutex behaviour.

os_mutex_type_errorcheck 

Check mutex behaviour.

os_mutex_type_recursive 

Recursive mutex behaviour.

os_mutex_type_default 

Default mutex type.

Definition at line 875 of file os-c-decls.h.

Function Documentation

const os_mutex_attr_t* os_mutex_attr_get_recursive ( void  )

Get a recursive mutex attributes object instance.

Returns
Pointer to mutex attributes object instance.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::initializer_recursive

Definition at line 1578 of file os-c-wrapper.cpp.

void os_mutex_attr_init ( os_mutex_attr_t attr)

Initialise the mutex attributes.

Parameters
[in]attrPointer to mutex attributes object instance.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::attributes

Definition at line 1548 of file os-c-wrapper.cpp.

void os_mutex_attr_recursive_init ( os_mutex_attr_t attr)

Initialise the recursive mutex attributes.

Parameters
[in]attrPointer to mutex attributes object instance.
Returns
Nothing.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::attributes_recursive

Definition at line 1563 of file os-c-wrapper.cpp.

void os_mutex_construct ( os_mutex_t mutex,
const char *  name,
const os_mutex_attr_t attr 
)

Construct a statically allocated mutex object instance.

Parameters
[in]mutexPointer to mutex object instance storage.
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Nothing.
Note
Must be paired with os_mutex_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex

Definition at line 1594 of file os-c-wrapper.cpp.

void os_mutex_delete ( os_mutex_t mutex)

Destruct the mutex object instance and deallocate it.

Parameters
[in]mutexPointer to dynamically allocated mutex object instance.
Returns
Nothing.

Destruct the mutex and deallocate the dynamically allocated space using the RTOS system allocator.

Note
Equivalent of C++ delete ptr_mutex.
Must be paired with os_mutex_new() or os_mutex_recursive_new().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex

Definition at line 1711 of file os-c-wrapper.cpp.

void os_mutex_destruct ( os_mutex_t mutex)

Destruct the statically allocated mutex object instance.

Parameters
[in]mutexPointer to mutex object instance storage.
Returns
Nothing.
Note
Must be paired with os_mutex_construct() or os_mutex_recursive_construct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex

Definition at line 1639 of file os-c-wrapper.cpp.

const char* os_mutex_get_name ( os_mutex_t mutex)

Get the mutex name.

Parameters
[in]mutexPointer to mutex object instance.
Returns
Null terminated string.
Note
Can be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::name()

Definition at line 1726 of file os-c-wrapper.cpp.

os_thread_t* os_mutex_get_owner ( os_mutex_t mutex)

Get the thread that owns the mutex.

Parameters
[in]mutexPointer to mutex object instance.
Returns
Pointer to thread or NULL if not owned.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::owner()

Definition at line 1849 of file os-c-wrapper.cpp.

os_thread_prio_t os_mutex_get_prio_ceiling ( os_mutex_t mutex)

Get the priority ceiling of a mutex.

Parameters
[in]mutexPointer to mutex object instance.
Returns
The priority ceiling.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::prio_ceiling()

Definition at line 1802 of file os-c-wrapper.cpp.

os_mutex_protocol_t os_mutex_get_protocol ( os_mutex_t mutex)

Get the mutex protocol.

Parameters
[in]mutexPointer to mutex object instance.
Returns
An integer encoding the os::rtos::mutex::protocol.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::protocol()

Definition at line 1879 of file os-c-wrapper.cpp.

os_mutex_robustness_t os_mutex_get_robustness ( os_mutex_t mutex)

Get the mutex robustness.

Parameters
[in]mutexPointer to mutex object instance.
Returns
An integer encoding the os::rtos::mutex::robustness.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::robustness()

Definition at line 1894 of file os-c-wrapper.cpp.

os_mutex_type_t os_mutex_get_type ( os_mutex_t mutex)

Get the mutex type.

Parameters
[in]mutexPointer to mutex object instance.
Returns
An integer encoding the os::rtos::mutex::type.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::type()

Definition at line 1864 of file os-c-wrapper.cpp.

os_result_t os_mutex_lock ( os_mutex_t mutex)

Lock/acquire the mutex.

Parameters
[in]mutexPointer to mutex object instance.
Return values
os_okThe mutex was locked.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLEThe state protected by the mutex is not recoverable..
EAGAINThe mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EINVALThe mutex was created with the protocol attribute having the value os_mutex_protocol_protect and the calling thread's priority is higher than the mutex's current priority ceiling.
EOWNERDEADThe mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The mutex lock shall be acquired by the calling thread and it is up to the new owner to make the state consistent.
EDEADLKThe mutex type is os_mutex_type_errorcheck and the current thread already owns the mutex.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::lock()

Definition at line 1741 of file os-c-wrapper.cpp.

os_result_t os_mutex_mark_consistent ( os_mutex_t mutex)

Mark mutex as consistent.

Parameters
[in]mutexPointer to mutex object instance.
Return values
os_okThe mutex was marked as consistent.
EPERMCannot be invoked from an Interrupt Service Routines.
EINVALThe mutex object referenced by mutex is not robust or does not protect an inconsistent state.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::consistent()

Definition at line 1834 of file os-c-wrapper.cpp.

os_mutex_t* os_mutex_new ( const char *  name,
const os_mutex_attr_t attr 
)

Allocate a mutex object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Pointer to new mutex object instance.

Dynamically allocate the mutex object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new mutex(...).
Must be paired with os_mutex_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex

Definition at line 1660 of file os-c-wrapper.cpp.

void os_mutex_recursive_construct ( os_mutex_t mutex,
const char *  name,
const os_mutex_attr_t attr 
)

Construct a statically allocated recursive mutex object instance.

Parameters
[in]mutexPointer to mutex object instance storage.
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Nothing.
Note
Must be paired with os_mutex_destruct().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex_recursive

Definition at line 1616 of file os-c-wrapper.cpp.

os_mutex_t* os_mutex_recursive_new ( const char *  name,
const os_mutex_attr_t attr 
)

Allocated a recursive mutex object instance and construct it.

Parameters
[in]namePointer to name (may be NULL).
[in]attrPointer to attributes (may be NULL).
Returns
Pointer to new recursive mutex object instance.

Dynamically allocate the recursive mutex object instance using the RTOS system allocator and construct it.

Note
Equivalent of C++ new mutex_recursive(...).
Must be paired with os_mutex_delete().
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex_recursive

Definition at line 1685 of file os-c-wrapper.cpp.

os_result_t os_mutex_reset ( os_mutex_t mutex)

Reset the mutex.

Parameters
[in]mutexPointer to mutex object instance.
Return values
os_okThe mutex was reset.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::reset()

Definition at line 1909 of file os-c-wrapper.cpp.

os_result_t os_mutex_set_prio_ceiling ( os_mutex_t mutex,
os_thread_prio_t  prio_ceiling,
os_thread_prio_t old_prio_ceiling 
)

Change the priority ceiling of a mutex.

Parameters
[in]mutexPointer to mutex object instance.
[in]prio_ceilingnew priority.
[out]old_prio_ceilingpointer to location where to store the previous priority; may be NULL.
Return values
os_okThe priority was changed.
EPERMCannot be invoked from an Interrupt Service Routines.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::prio_ceiling(thread::priority_t, thread::priority_t*)

Definition at line 1817 of file os-c-wrapper.cpp.

os_result_t os_mutex_timed_lock ( os_mutex_t mutex,
os_clock_duration_t  timeout 
)

Timed attempt to lock/acquire the mutex.

Parameters
[in]mutexPointer to mutex object instance.
[in]timeoutTimeout to wait, in clock units (ticks or seconds).
Return values
os_okThe mutex was locked.
EPERMCannot be invoked from an Interrupt Service Routines.
ETIMEDOUTThe mutex could not be locked before the specified timeout expired.
ENOTRECOVERABLEThe state protected by the mutex is not recoverable.
EAGAINThe mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EDEADLKThe mutex type is os_mutex_type_errorcheck and the current thread already owns the mutex.
EINVALThe process or thread would have blocked, and the timeout parameter is invalid.
EOWNERDEADThe mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The mutex lock shall be acquired by the calling thread and it is up to the new owner to make the state consistent.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::timed_lock()

Definition at line 1771 of file os-c-wrapper.cpp.

os_result_t os_mutex_try_lock ( os_mutex_t mutex)

Try to lock/acquire the mutex.

Parameters
[in]mutexPointer to mutex object instance.
Return values
os_okThe mutex was locked.
EPERMCannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLEThe state protected by the mutex is not recoverable..
EAGAINThe mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EINVALThe mutex was created with the protocol attribute having the value os_mutex_protocol_protect and the calling thread's priority is higher than the mutex's current priority ceiling.
EOWNERDEADThe mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The mutex lock shall be acquired by the calling thread and it is up to the new owner to make the state consistent.
EDEADLKThe mutex type is os_mutex_type_errorcheck and the current thread already owns the mutex.
EWOULDBLOCKThe mutex could not be acquired because it was already locked.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::try_lock()

Definition at line 1756 of file os-c-wrapper.cpp.

os_result_t os_mutex_unlock ( os_mutex_t mutex)

Unlock/release the mutex.

Parameters
[in]mutexPointer to mutex object instance.
Return values
os_okThe mutex was unlocked.
EPERMCannot be invoked from an Interrupt Service Routine; the mutex type is os_mutex_type_errorcheck or os_mutex_type_recursive, or the mutex is a robust mutex, and the current thread does not own the mutex.
ENOTRECOVERABLEThe mutex was not unlocked.
Warning
Cannot be invoked from Interrupt Service Routines.
For the complete definition, see
os::rtos::mutex::unlock()

Definition at line 1787 of file os-c-wrapper.cpp.