C API mutex definitions. More...

Classes
struct	os_mutex_attr_s
	Mutex attributes. More...

struct	os_mutex_s
	Mutex object storage. More...

Typedefs
typedef struct os_mutex_attr_s	os_mutex_attr_t
	Mutex attributes.

typedef struct os_mutex_s	os_mutex_t
	Mutex object storage.

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...

Mutex Attributes Functions
void	os_mutex_attr_init (os_mutex_attr_t *attr)
	Initialise the mutex attributes.

void	os_mutex_attr_recursive_init (os_mutex_attr_t *attr)
	Initialise the recursive mutex attributes.

const os_mutex_attr_t *	os_mutex_attr_get_recursive (void)
	Get a recursive mutex attributes object instance.

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.

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.

void	os_mutex_destruct (os_mutex_t *mutex)
	Destruct the statically allocated mutex object instance.

os_mutex_t *	os_mutex_new (const char name, const os_mutex_attr_t attr)
	Allocate a mutex object instance and construct it.

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.

void	os_mutex_delete (os_mutex_t *mutex)
	Destruct the mutex object instance and deallocate it.

Mutex Functions
const char *	os_mutex_get_name (os_mutex_t *mutex)
	Get the mutex name.

os_result_t	os_mutex_lock (os_mutex_t *mutex)
	Lock/acquire the mutex.

os_result_t	os_mutex_try_lock (os_mutex_t *mutex)
	Try to lock/acquire the mutex.

os_result_t	os_mutex_timed_lock (os_mutex_t *mutex, os_clock_duration_t timeout)
	Timed attempt to lock/acquire the mutex.

os_result_t	os_mutex_unlock (os_mutex_t *mutex)
	Unlock/release the mutex.

os_thread_prio_t	os_mutex_get_prio_ceiling (os_mutex_t *mutex)
	Get the priority ceiling of a mutex.

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.

os_result_t	os_mutex_mark_consistent (os_mutex_t *mutex)
	Mark mutex as consistent.

os_thread_t *	os_mutex_get_owner (os_mutex_t *mutex)
	Get the thread that owns the mutex.

os_mutex_type_t	os_mutex_get_type (os_mutex_t *mutex)
	Get the mutex type.

os_mutex_protocol_t	os_mutex_get_protocol (os_mutex_t *mutex)
	Get the mutex protocol.

os_mutex_robustness_t	os_mutex_get_robustness (os_mutex_t *mutex)
	Get the mutex robustness.

os_result_t	os_mutex_reset (os_mutex_t *mutex)
	Reset the mutex.

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

Detailed Description

C API mutex definitions.

For the complete definition, see: RTOS C++ API

Examples

int
os_main (int argc, char* argv[])
{
    {
      os_mutex_t mx1;
      os_mutex_construct (&mx1, "mx1", NULL);
 
      os_mutex_lock (&mx1);
      os_mutex_unlock (&mx1);
 
      os_mutex_try_lock (&mx1);
      os_mutex_unlock (&mx1);
 
      os_mutex_timed_lock (&mx1, 1);
      os_mutex_unlock (&mx1);
 
      name = os_mutex_get_name (&mx1);
      assert(strcmp (name, "mx1") == 0);
 
      os_thread_prio_t prio;
      prio = os_mutex_get_prio_ceiling (&mx1);
 
      os_mutex_set_prio_ceiling (&mx1, prio, NULL);
 
      os_thread_t* th;
      th = os_mutex_get_owner (&mx1);
      if (th != NULL)
        {
          os_thread_get_name (th);
        }
 
      os_mutex_reset (&mx1);
 
      os_mutex_destruct (&mx1);
    }
 
    {
      // Custom mutex, with RTC.
      os_mutex_attr_t amx2;
      os_mutex_attr_init (&amx2);
 
      amx2.mx_priority_ceiling = os_thread_priority_high;
      amx2.mx_protocol = os_mutex_protocol_protect;
      amx2.mx_type = os_mutex_type_recursive;
      amx2.mx_max_count = 7;
      amx2.mx_robustness = os_mutex_robustness_stalled;
      amx2.clock = os_clock_get_rtclock ();
 
      os_mutex_t mx2;
      os_mutex_construct (&mx2, "mx2", &amx2);
 
      os_mutex_destruct (&mx2);
    }
 
    {
      // Recursive mutex.
      os_mutex_t mx3;
      os_mutex_construct (&mx3, "mx3", os_mutex_attr_get_recursive ());
 
      os_mutex_destruct (&mx3);
    }
 
    {
      // Custom recursive mutex, with RTC.
      os_mutex_attr_t amx4;
      os_mutex_attr_init_recursive (&amx4);
 
      amx4.clock = os_clock_get_rtclock ();
 
      os_mutex_t mx4;
      os_mutex_construct (&mx4, "mx4", &amx4);
 
      os_mutex_destruct (&mx4);
    }
}

Macro Definition Documentation

◆ os_mutex_create

#define os_mutex_create os_mutex_construct

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

◆ os_mutex_destroy

#define os_mutex_destroy os_mutex_destruct

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

◆ os_mutex_recursive_create

#define os_mutex_recursive_create os_mutex_recursive_construct

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

Typedef Documentation

◆ os_mutex_attr_t

typedef struct os_mutex_attr_s os_mutex_attr_t

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

◆ os_mutex_t

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

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 829 of file os-c-decls.h.

◆ anonymous enum

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 857 of file os-c-decls.h.

◆ anonymous enum

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 880 of file os-c-decls.h.

Function Documentation

◆ os_mutex_attr_get_recursive()

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 1461 of file os-c-wrapper.cpp.

◆ os_mutex_attr_init()

void os_mutex_attr_init ( os_mutex_attr_t * attr )

Initialise the mutex attributes.

Parameters

[in] attr Pointer 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 1435 of file os-c-wrapper.cpp.

◆ os_mutex_attr_recursive_init()

void os_mutex_attr_recursive_init ( os_mutex_attr_t * attr )

Initialise the recursive mutex attributes.

Parameters

[in] attr Pointer 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 1448 of file os-c-wrapper.cpp.

◆ os_mutex_construct()

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]	mutex	Pointer to mutex object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1475 of file os-c-wrapper.cpp.

◆ os_mutex_delete()

void os_mutex_delete ( os_mutex_t * mutex )

Destruct the mutex object instance and deallocate it.

Parameters

[in] mutex Pointer 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 1585 of file os-c-wrapper.cpp.

◆ os_mutex_destruct()

void os_mutex_destruct ( os_mutex_t * mutex )

Destruct the statically allocated mutex object instance.

Parameters

[in] mutex Pointer 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 1516 of file os-c-wrapper.cpp.

◆ os_mutex_get_name()

const char * os_mutex_get_name ( os_mutex_t * mutex )

Get the mutex name.

Parameters

[in] mutex Pointer 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 1598 of file os-c-wrapper.cpp.

◆ os_mutex_get_owner()

os_thread_t * os_mutex_get_owner ( os_mutex_t * mutex )

Get the thread that owns the mutex.

Parameters

[in] mutex Pointer 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 1705 of file os-c-wrapper.cpp.

◆ os_mutex_get_prio_ceiling()

os_thread_prio_t os_mutex_get_prio_ceiling ( os_mutex_t * mutex )

Get the priority ceiling of a mutex.

Parameters

[in] mutex Pointer 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 1664 of file os-c-wrapper.cpp.

◆ os_mutex_get_protocol()

os_mutex_protocol_t os_mutex_get_protocol ( os_mutex_t * mutex )

Get the mutex protocol.

Parameters

[in] mutex Pointer 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 1731 of file os-c-wrapper.cpp.

◆ os_mutex_get_robustness()

os_mutex_robustness_t os_mutex_get_robustness ( os_mutex_t * mutex )

Get the mutex robustness.

Parameters

[in] mutex Pointer 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 1744 of file os-c-wrapper.cpp.

◆ os_mutex_get_type()

os_mutex_type_t os_mutex_get_type ( os_mutex_t * mutex )

Get the mutex type.

Parameters

[in] mutex Pointer 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 1718 of file os-c-wrapper.cpp.

◆ os_mutex_lock()

os_result_t os_mutex_lock ( os_mutex_t * mutex )

Lock/acquire the mutex.

Parameters

[in] mutex Pointer to mutex object instance.

Return values

os_ok	The mutex was locked.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The state protected by the mutex is not recoverable..
EAGAIN	The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EINVAL	The 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.
EOWNERDEAD	The 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.
EDEADLK	The 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 1611 of file os-c-wrapper.cpp.

◆ os_mutex_mark_consistent()

os_result_t os_mutex_mark_consistent ( os_mutex_t * mutex )

Mark mutex as consistent.

Parameters

[in] mutex Pointer to mutex object instance.

Return values

os_ok	The mutex was marked as consistent.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The 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 1692 of file os-c-wrapper.cpp.

◆ os_mutex_new()

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]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1536 of file os-c-wrapper.cpp.

◆ os_mutex_recursive_construct()

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]	mutex	Pointer to mutex object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1495 of file os-c-wrapper.cpp.

◆ os_mutex_recursive_new()

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]	name	Pointer to name (may be NULL).
[in]	attr	Pointer 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 1560 of file os-c-wrapper.cpp.

◆ os_mutex_reset()

os_result_t os_mutex_reset ( os_mutex_t * mutex )

Reset the mutex.

Parameters

[in] mutex Pointer to mutex object instance.

Return values

os_ok The mutex was reset.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::mutex::reset()

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

◆ os_mutex_set_prio_ceiling()

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]	mutex	Pointer to mutex object instance.
[in]	prio_ceiling	new priority.
[out]	old_prio_ceiling	pointer to location where to store the previous priority; may be `NULL`.

Return values

os_ok	The priority was changed.
EPERM	Cannot 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(os::rtos::thread::priority_t, os::rtos::thread::priority_t*)

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

◆ os_mutex_timed_lock()

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]	mutex	Pointer to mutex object instance.
[in]	timeout	Timeout to wait, in clock units (ticks or seconds).

Return values

os_ok	The mutex was locked.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The mutex could not be locked before the specified timeout expired.
ENOTRECOVERABLE	The state protected by the mutex is not recoverable.
EAGAIN	The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EDEADLK	The mutex type is `os_mutex_type_errorcheck` and the current thread already owns the mutex.
EINVAL	The process or thread would have blocked, and the timeout parameter is invalid.
EOWNERDEAD	The 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 1637 of file os-c-wrapper.cpp.

◆ os_mutex_try_lock()

os_result_t os_mutex_try_lock ( os_mutex_t * mutex )

Try to lock/acquire the mutex.

Parameters

[in] mutex Pointer to mutex object instance.

Return values

os_ok	The mutex was locked.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ENOTRECOVERABLE	The state protected by the mutex is not recoverable..
EAGAIN	The mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded.
EINVAL	The 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.
EOWNERDEAD	The 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.
EDEADLK	The mutex type is `os_mutex_type_errorcheck` and the current thread already owns the mutex.
EWOULDBLOCK	The 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 1624 of file os-c-wrapper.cpp.

◆ os_mutex_unlock()

os_result_t os_mutex_unlock ( os_mutex_t * mutex )

Unlock/release the mutex.

Parameters

[in] mutex Pointer to mutex object instance.

Return values

os_ok	The mutex was unlocked.
EPERM	Cannot 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.
ENOTRECOVERABLE	The mutex was not unlocked.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::mutex::unlock()

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

Classes

Typedefs

Enumerations

Mutex Attributes Functions

Mutex Creation Functions

Mutex Functions

Compatibility Macros

Detailed Description

Macro Definition Documentation

◆ os_mutex_create

◆ os_mutex_destroy

◆ os_mutex_recursive_create

Typedef Documentation

◆ os_mutex_attr_t

◆ os_mutex_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ os_mutex_attr_get_recursive()

◆ os_mutex_attr_init()

◆ os_mutex_attr_recursive_init()

◆ os_mutex_construct()

◆ os_mutex_delete()

◆ os_mutex_destruct()

◆ os_mutex_get_name()

◆ os_mutex_get_owner()

◆ os_mutex_get_prio_ceiling()

◆ os_mutex_get_protocol()

◆ os_mutex_get_robustness()

◆ os_mutex_get_type()

◆ os_mutex_lock()

◆ os_mutex_mark_consistent()

◆ os_mutex_new()

◆ os_mutex_recursive_construct()

◆ os_mutex_recursive_new()

◆ os_mutex_reset()

◆ os_mutex_set_prio_ceiling()

◆ os_mutex_timed_lock()

◆ os_mutex_try_lock()

◆ os_mutex_unlock()