distortos  v0.6.0
object-oriented C++ RTOS for microcontrollers

Mutex-related C-API of distortos. More...

Collaboration diagram for Mutex C-API:

Classes

struct  distortos_Mutex
 C-API equivalent of distortos::Mutex. More...
 

Macros

#define DISTORTOS_MUTEX_INITIALIZER(self, type, protocol, priorityCeiling)
 Initializer for distortos_Mutex. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT_3(name, type, protocol, priorityCeiling)   struct distortos_Mutex name = DISTORTOS_MUTEX_INITIALIZER(name, type, protocol, priorityCeiling)
 C-API equivalent of distortos::Mutex's constructor. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT_2PC(name, protocol, priorityCeiling)   DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, protocol, priorityCeiling)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT_2TP(name, type, protocol)   DISTORTOS_MUTEX_CONSTRUCT_3(name, type, protocol, 0)
 C-API equivalent of distortos::Mutex's constructor, priorityCeiling = 0. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT_1P(name, protocol)   DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, protocol, 0)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, priorityCeiling = 0. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT_1T(name, type)   DISTORTOS_MUTEX_CONSTRUCT_3(name, type, distortos_Mutex_Protocol_none, 0)
 C-API equivalent of distortos::Mutex's constructor, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0. More...
 
#define DISTORTOS_MUTEX_CONSTRUCT(name)   DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, distortos_Mutex_Protocol_none, 0)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0. More...
 

Enumerations

enum  { distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect }
 
enum  { distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive }
 
enum  { distortos_Mutex_typeShift = 0 }
 
enum  { distortos_Mutex_protocolShift = 4 }
 

Functions

int distortos_Mutex_construct_3 (struct distortos_Mutex *mutex, uint8_t type, uint8_t protocol, uint8_t priorityCeiling)
 C-API equivalent of distortos::Mutex's constructor. More...
 
static int distortos_Mutex_construct_2pc (struct distortos_Mutex *const mutex, const uint8_t protocol, const uint8_t priorityCeiling)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal. More...
 
static int distortos_Mutex_construct_2tp (struct distortos_Mutex *const mutex, const uint8_t type, const uint8_t protocol)
 C-API equivalent of distortos::Mutex's constructor, priorityCeiling = 0. More...
 
static int distortos_Mutex_construct_1p (struct distortos_Mutex *const mutex, const uint8_t protocol)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, priorityCeiling = 0. More...
 
static int distortos_Mutex_construct_1t (struct distortos_Mutex *const mutex, const uint8_t type)
 C-API equivalent of distortos::Mutex's constructor, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0. More...
 
static int distortos_Mutex_construct (struct distortos_Mutex *const mutex)
 C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0. More...
 
int distortos_Mutex_destruct (struct distortos_Mutex *mutex)
 C-API equivalent of distortos::Mutex's destructor. More...
 
int distortos_Mutex_lock (struct distortos_Mutex *mutex)
 C-API equivalent of distortos::Mutex::lock() More...
 
int distortos_Mutex_tryLock (struct distortos_Mutex *mutex)
 C-API equivalent of distortos::Mutex::tryLock() More...
 
int distortos_Mutex_tryLockFor (struct distortos_Mutex *mutex, int64_t duration)
 C-API equivalent of distortos::Mutex::tryLockFor() More...
 
int distortos_Mutex_tryLockUntil (struct distortos_Mutex *mutex, int64_t timePoint)
 C-API equivalent of distortos::Mutex::tryLockUntil() More...
 
int distortos_Mutex_unlock (struct distortos_Mutex *mutex)
 C-API equivalent of distortos::Mutex::unlock() More...
 

Detailed Description

Mutex-related C-API of distortos.

Macro Definition Documentation

◆ DISTORTOS_MUTEX_CONSTRUCT

#define DISTORTOS_MUTEX_CONSTRUCT (   name)    DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, distortos_Mutex_Protocol_none, 0)

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated

◆ DISTORTOS_MUTEX_CONSTRUCT_1P

#define DISTORTOS_MUTEX_CONSTRUCT_1P (   name,
  protocol 
)    DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, protocol, 0)

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, priorityCeiling = 0.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}

◆ DISTORTOS_MUTEX_CONSTRUCT_1T

#define DISTORTOS_MUTEX_CONSTRUCT_1T (   name,
  type 
)    DISTORTOS_MUTEX_CONSTRUCT_3(name, type, distortos_Mutex_Protocol_none, 0)

C-API equivalent of distortos::Mutex's constructor, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}

◆ DISTORTOS_MUTEX_CONSTRUCT_2PC

#define DISTORTOS_MUTEX_CONSTRUCT_2PC (   name,
  protocol,
  priorityCeiling 
)    DISTORTOS_MUTEX_CONSTRUCT_3(name, distortos_Mutex_Type_normal, protocol, priorityCeiling)

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != distortos_Mutex_Protocol_priorityProtect

◆ DISTORTOS_MUTEX_CONSTRUCT_2TP

#define DISTORTOS_MUTEX_CONSTRUCT_2TP (   name,
  type,
  protocol 
)    DISTORTOS_MUTEX_CONSTRUCT_3(name, type, protocol, 0)

C-API equivalent of distortos::Mutex's constructor, priorityCeiling = 0.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}

◆ DISTORTOS_MUTEX_CONSTRUCT_3

#define DISTORTOS_MUTEX_CONSTRUCT_3 (   name,
  type,
  protocol,
  priorityCeiling 
)    struct distortos_Mutex name = DISTORTOS_MUTEX_INITIALIZER(name, type, protocol, priorityCeiling)

C-API equivalent of distortos::Mutex's constructor.

See also
distortos::Mutex::Mutex()
Parameters
[in]nameis the name of the object that will be instantiated
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != distortos_Mutex_Protocol_priorityProtect

◆ DISTORTOS_MUTEX_INITIALIZER

#define DISTORTOS_MUTEX_INITIALIZER (   self,
  type,
  protocol,
  priorityCeiling 
)
Value:
NULL, 0, (priorityCeiling), \
(uint8_t)(((type) == distortos_Mutex_Type_normal || (type) == distortos_Mutex_Type_errorChecking || \
(uint8_t)(type) : (uint8_t)distortos_Mutex_Type_normal) << distortos_Mutex_typeShift | \
(uint8_t)(protocol) : (uint8_t)distortos_Mutex_Protocol_none) << distortos_Mutex_protocolShift)}
Definition: Mutex.h:91
#define ESTD_INTRUSIVELIST_INITIALIZER(self)
Initializer for estd_IntrusiveList.
Definition: IntrusiveList.h:50
Definition: Mutex.h:81
Definition: Mutex.h:85
Definition: Mutex.h:97
Definition: Mutex.h:71
#define ESTD_INTRUSIVELISTNODE_INITIALIZER(self)
Initializer for estd_IntrusiveListNode.
Definition: IntrusiveListNode.h:51

Initializer for distortos_Mutex.

See also
distortos::Mutex::Mutex()
Parameters
[in]selfis an equivalent of this hidden argument
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != distortos_Mutex_Protocol_priorityProtect

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
distortos_Mutex_Protocol_none 

no protocol, similar to PTHREAD_PRIO_NONE

distortos_Mutex_Protocol_priorityInheritance 

priority inheritance protocol, similar to PTHREAD_PRIO_INHERIT

distortos_Mutex_Protocol_priorityProtect 

priority protection protocol (Immediate Ceiling Priority Protocol), similar to PTHREAD_PRIO_PROTECT

◆ anonymous enum

anonymous enum
Enumerator
distortos_Mutex_Type_normal 

normal mutex, similar to PTHREAD_MUTEX_NORMAL

distortos_Mutex_Type_errorChecking 

mutex with additional error checking, similar to PTHREAD_MUTEX_ERRORCHECK

distortos_Mutex_Type_recursive 

recursive mutex, similar to PTHREAD_MUTEX_RECURSIVE

◆ anonymous enum

anonymous enum
Enumerator
distortos_Mutex_typeShift 

shift of "type" subfield, bits

◆ anonymous enum

anonymous enum
Enumerator
distortos_Mutex_protocolShift 

shift of "protocol" subfield, bits

Function Documentation

◆ distortos_Mutex_construct()

static int distortos_Mutex_construct ( struct distortos_Mutex *const  mutex)
inlinestatic

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
Returns
0 on success, error code otherwise:
  • EINVAL - mutex is invalid;
Here is the call graph for this function:

◆ distortos_Mutex_construct_1p()

static int distortos_Mutex_construct_1p ( struct distortos_Mutex *const  mutex,
const uint8_t  protocol 
)
inlinestatic

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal, priorityCeiling = 0.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
Returns
0 on success, error code otherwise:
  • EINVAL - mutex and/or protocol are invalid;
Here is the call graph for this function:

◆ distortos_Mutex_construct_1t()

static int distortos_Mutex_construct_1t ( struct distortos_Mutex *const  mutex,
const uint8_t  type 
)
inlinestatic

C-API equivalent of distortos::Mutex's constructor, protocol = distortos_Mutex_Protocol_none, priorityCeiling = 0.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
Returns
0 on success, error code otherwise:
  • EINVAL - mutex and/or type are invalid;
Here is the call graph for this function:

◆ distortos_Mutex_construct_2pc()

static int distortos_Mutex_construct_2pc ( struct distortos_Mutex *const  mutex,
const uint8_t  protocol,
const uint8_t  priorityCeiling 
)
inlinestatic

C-API equivalent of distortos::Mutex's constructor, type = distortos_Mutex_Type_normal.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != distortos_Mutex_Protocol_priorityProtect
Returns
0 on success, error code otherwise:
  • EINVAL - mutex and/or protocol are invalid;
Here is the call graph for this function:

◆ distortos_Mutex_construct_2tp()

static int distortos_Mutex_construct_2tp ( struct distortos_Mutex *const  mutex,
const uint8_t  type,
const uint8_t  protocol 
)
inlinestatic

C-API equivalent of distortos::Mutex's constructor, priorityCeiling = 0.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
Returns
0 on success, error code otherwise:
  • EINVAL - mutex and/or type and/or protocol are invalid;
Here is the call graph for this function:

◆ distortos_Mutex_construct_3()

int distortos_Mutex_construct_3 ( struct distortos_Mutex mutex,
uint8_t  type,
uint8_t  protocol,
uint8_t  priorityCeiling 
)

C-API equivalent of distortos::Mutex's constructor.

Similar to std::mutex::mutex() - http://en.cppreference.com/w/cpp/thread/mutex/mutex Similar to pthread_mutex_init() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html

See also
distortos::Mutex::Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]typeis the type of mutex, {distortos_Mutex_Type_normal, distortos_Mutex_Type_errorChecking, distortos_Mutex_Type_recursive}
[in]protocolis the mutex protocol, {distortos_Mutex_Protocol_none, distortos_Mutex_Protocol_priorityInheritance, distortos_Mutex_Protocol_priorityProtect}
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != distortos_Mutex_Protocol_priorityProtect
Returns
0 on success, error code otherwise:
  • EINVAL - mutex and/or type and/or protocol are invalid;
Here is the caller graph for this function:

◆ distortos_Mutex_destruct()

int distortos_Mutex_destruct ( struct distortos_Mutex mutex)

C-API equivalent of distortos::Mutex's destructor.

Similar to std::mutex::~mutex() - http://en.cppreference.com/w/cpp/thread/mutex/~mutex Similar to pthread_mutex_destroy() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_destroy.html

See also
distortos::Mutex::~Mutex()
Parameters
[in]mutexis a pointer to distortos_Mutex object
Returns
0 on success, error code otherwise:
  • EINVAL - mutex is invalid;
Here is the call graph for this function:

◆ distortos_Mutex_lock()

int distortos_Mutex_lock ( struct distortos_Mutex mutex)

C-API equivalent of distortos::Mutex::lock()

Similar to std::mutex::lock() - http://en.cppreference.com/w/cpp/thread/mutex/lock Similar to pthread_mutex_lock() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html#

See also
distortos::Mutex::lock()
Warning
This function must not be called from interrupt context!
Parameters
[in]mutexis a pointer to distortos_Mutex object
Returns
0 on success, error code otherwise:
  • EAGAIN - the mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded;
  • EDEADLK - the mutex type is errorChecking and the current thread already owns the mutex;
  • EINVAL - the mutex was created with the protocol attribute having the value priorityProtect and the calling thread's priority is higher than the mutex's current priority ceiling;
  • EINVAL - mutex value is invalid;
Here is the call graph for this function:

◆ distortos_Mutex_tryLock()

int distortos_Mutex_tryLock ( struct distortos_Mutex mutex)

C-API equivalent of distortos::Mutex::tryLock()

Similar to std::mutex::try_lock() - http://en.cppreference.com/w/cpp/thread/mutex/try_lock Similar to pthread_mutex_trylock() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html#

See also
distortos::Mutex::tryLock()
Warning
This function must not be called from interrupt context!
Parameters
[in]mutexis a pointer to distortos_Mutex object
Returns
0 if the caller successfully locked the mutex, error code otherwise:
  • EAGAIN - the mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded;
  • EBUSY - the mutex could not be acquired because it was already locked;
  • EINVAL - the mutex was created with the protocol attribute having the value priorityProtect and the calling thread's priority is higher than the mutex's current priority ceiling;
  • EINVAL - mutex value is invalid;
Here is the call graph for this function:

◆ distortos_Mutex_tryLockFor()

int distortos_Mutex_tryLockFor ( struct distortos_Mutex mutex,
int64_t  duration 
)

C-API equivalent of distortos::Mutex::tryLockFor()

Similar to std::timed_mutex::try_lock_for() - http://en.cppreference.com/w/cpp/thread/timed_mutex/try_lock_for Similar to pthread_mutex_timedlock() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_timedlock.html#

See also
distortos::Mutex::tryLockFor()
Warning
This function must not be called from interrupt context!
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]durationis the duration in system ticks after which the wait will be terminated without locking the mutex
Returns
0 if the caller successfully locked the mutex, error code otherwise:
  • EAGAIN - the mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded;
  • EDEADLK - the mutex type is errorChecking and the current thread already owns the mutex;
  • EINVAL - the mutex was created with the protocol attribute having the value priorityProtect and the calling thread's priority is higher than the mutex's current priority ceiling;
  • EINVAL - mutex value is invalid;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ distortos_Mutex_tryLockUntil()

int distortos_Mutex_tryLockUntil ( struct distortos_Mutex mutex,
int64_t  timePoint 
)

C-API equivalent of distortos::Mutex::tryLockUntil()

Similar to std::timed_mutex::try_lock_until() - http://en.cppreference.com/w/cpp/thread/timed_mutex/try_lock_until Similar to pthread_mutex_timedlock() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_timedlock.html#

See also
distortos::Mutex::tryLockUntil()
Warning
This function must not be called from interrupt context!
Parameters
[in]mutexis a pointer to distortos_Mutex object
[in]timePointis the time point in system ticks at which the wait will be terminated without locking the mutex
Returns
0 if the caller successfully locked the mutex, error code otherwise:
  • EAGAIN - the mutex could not be acquired because the maximum number of recursive locks for mutex has been exceeded;
  • EDEADLK - the mutex type is errorChecking and the current thread already owns the mutex;
  • EINVAL - the mutex was created with the protocol attribute having the value priorityProtect and the calling thread's priority is higher than the mutex's current priority ceiling;
  • EINVAL - mutex value is invalid;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ distortos_Mutex_unlock()

int distortos_Mutex_unlock ( struct distortos_Mutex mutex)

C-API equivalent of distortos::Mutex::unlock()

Similar to std::mutex::unlock() - http://en.cppreference.com/w/cpp/thread/mutex/unlock Similar to pthread_mutex_unlock() - http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html#

See also
distortos::Mutex::unlock()
Warning
This function must not be called from interrupt context!
Parameters
[in]mutexis a pointer to distortos_Mutex object
Returns
0 if the caller successfully unlocked the mutex, error code otherwise:
  • EINVAL - mutex value is invalid;
  • EPERM - the mutex type is errorChecking or recursive, and the current thread does not own the mutex;
Here is the call graph for this function: