distortos  v0.7.0
object-oriented C++ RTOS for microcontrollers
distortos::Mutex Class Reference

Mutex is the basic synchronization primitive. More...

#include "distortos/Mutex.hpp"

Inheritance diagram for distortos::Mutex:
[legend]
Collaboration diagram for distortos::Mutex:
[legend]

Public Types

using Protocol = MutexProtocol
 mutex protocols More...
 
using RecursiveLocksCount = MutexControlBlock::RecursiveLocksCount
 type used for counting recursive locks More...
 
using Type = MutexType
 type of mutex More...
 

Public Member Functions

constexpr Mutex (const Type type=Type::normal, const Protocol protocol=Protocol::none, const uint8_t priorityCeiling={})
 Mutex's constructor. More...
 
constexpr Mutex (const Protocol protocol, const uint8_t priorityCeiling={})
 Mutex's constructor, overload for "normal" type. More...
 
 ~Mutex ()=default
 Mutex's destructor. More...
 
int lock ()
 Locks the mutex. More...
 
int tryLock ()
 Tries to lock the mutex. More...
 
int tryLockFor (TickClock::duration duration)
 Tries to lock the mutex for given duration of time. More...
 
template<typename Rep , typename Period >
int tryLockFor (const std::chrono::duration< Rep, Period > duration)
 Tries to lock the mutex for given duration of time. More...
 
int tryLockUntil (TickClock::time_point timePoint)
 Tries to lock the mutex until given time point. More...
 
template<typename Duration >
int tryLockUntil (const std::chrono::time_point< TickClock, Duration > timePoint)
 Tries to lock the mutex until given time point. More...
 
bool try_lock ()
 Tries to lock the mutex. More...
 
template<typename Rep , typename Period >
bool try_lock_for (const std::chrono::duration< Rep, Period > duration)
 Tries to lock the mutex for given duration of time. More...
 
template<typename Duration >
bool try_lock_until (const std::chrono::time_point< TickClock, Duration > timePoint)
 Tries to lock the mutex until given time point. More...
 
int unlock ()
 Unlocks the mutex. More...
 
 Mutex (const Mutex &)=delete
 
 Mutex (Mutex &&)=default
 
const Mutexoperator= (const Mutex &)=delete
 
Mutexoperator= (Mutex &&)=delete
 

Static Public Member Functions

static constexpr RecursiveLocksCount getMaxRecursiveLocks ()
 Gets the maximum number of recursive locks possible before returning EAGAIN. More...
 

Private Member Functions

int tryLockInternal ()
 Internal version of tryLock(). More...
 
- Private Member Functions inherited from distortos::internal::MutexControlBlock
uint8_t getBoostedPriority () const
 Gets "boosted priority" of the mutex. More...
 
ThreadControlBlockgetOwner () const
 
constexpr MutexControlBlock (const Type type, const Protocol protocol, const uint8_t priorityCeiling)
 MutexControlBlock's constructor. More...
 
int doBlock ()
 Blocks current thread, transferring it to blockedList_. More...
 
int doBlockUntil (TickClock::time_point timePoint)
 Blocks current thread with timeout, transferring it to blockedList_. More...
 
void doLock ()
 Performs actual locking of previously unlocked mutex. More...
 
void doUnlockOrTransferLock ()
 Performs unlocking or transfer of lock from current owner to next thread on the list. More...
 
uint8_t getPriorityCeiling () const
 
Protocol getProtocol () const
 
RecursiveLocksCountgetRecursiveLocksCount ()
 
Type getType () const
 
- Private Member Functions inherited from distortos::internal::MutexListNode
constexpr MutexListNode ()
 MutexListNode's constructor. More...
 

Additional Inherited Members

- Private Types inherited from distortos::internal::MutexControlBlock
using Protocol = MutexProtocol
 mutex protocols More...
 
using RecursiveLocksCount = uint16_t
 type used for counting recursive locks More...
 
using Type = MutexType
 type of mutex More...
 
- Private Attributes inherited from distortos::internal::MutexListNode
estd::IntrusiveListNode node
 node for intrusive list More...
 
- Static Private Attributes inherited from distortos::internal::MutexControlBlock
static constexpr uint8_t typeShift {0}
 shift of "type" subfield, bits More...
 
static constexpr uint8_t typeWidth {CHAR_BIT / 2}
 width of "type" subfield, bits More...
 
static constexpr uint8_t protocolShift {typeShift + typeWidth}
 shift of "protocol" subfield, bits More...
 
static constexpr uint8_t protocolWidth {CHAR_BIT / 2}
 width of "protocol" subfield, bits More...
 

Detailed Description

Mutex is the basic synchronization primitive.

Similar to std::mutex - http://en.cppreference.com/w/cpp/thread/mutex Similar to POSIX pthread_mutex_t - http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_09 -> 2.9.3 Thread Mutexes

Member Typedef Documentation

◆ Protocol

mutex protocols

◆ RecursiveLocksCount

using distortos::Mutex::RecursiveLocksCount = MutexControlBlock::RecursiveLocksCount

type used for counting recursive locks

◆ Type

type of mutex

Constructor & Destructor Documentation

◆ Mutex() [1/2]

constexpr distortos::Mutex::Mutex ( const Type  type = Type::normal,
const Protocol  protocol = Protocol::none,
const uint8_t  priorityCeiling = {} 
)
inlineexplicit

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

Parameters
[in]typeis the type of mutex, default - Type::normal
[in]protocolis the mutex protocol, default - Protocol::none
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != Protocol::priorityProtect, default - 0

◆ Mutex() [2/2]

constexpr distortos::Mutex::Mutex ( const Protocol  protocol,
const uint8_t  priorityCeiling = {} 
)
inlineexplicit

Mutex's constructor, overload for "normal" type.

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

Parameters
[in]protocolis the mutex protocol
[in]priorityCeilingis the priority ceiling of mutex, ignored when protocol != Protocol::priorityProtect, default - 0

◆ ~Mutex()

distortos::Mutex::~Mutex ( )
default

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

It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex, or a mutex that another thread is attempting to lock, or a mutex that is currently being used by a condition variable in another thread, results in undefined behavior.

Member Function Documentation

◆ getMaxRecursiveLocks()

static constexpr RecursiveLocksCount distortos::Mutex::getMaxRecursiveLocks ( )
inlinestatic

Gets the maximum number of recursive locks possible before returning EAGAIN.

Note
Actual number of lock() operations possible is getMaxRecursiveLocks() + 1.
Returns
maximum number of recursive locks possible before returning EAGAIN
Here is the caller graph for this function:

◆ lock()

int distortos::Mutex::lock ( )

Locks the mutex.

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#

If the mutex is already locked by another thread, the calling thread shall block until the mutex becomes available. This function shall return with the mutex in the locked state with the calling thread as its owner. If a thread attempts to relock a mutex that it has already locked, deadlock occurs.

Warning
This function must not be called from interrupt context!
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;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ try_lock()

bool distortos::Mutex::try_lock ( )
inline

Tries to lock the mutex.

Wrapper for tryLock() which implements std::mutex::try_lock() API.

Warning
This function must not be called from interrupt context!
Returns
true if the caller successfully locked the mutex, false otherwise
Here is the call graph for this function:

◆ try_lock_for()

template<typename Rep , typename Period >
bool distortos::Mutex::try_lock_for ( const std::chrono::duration< Rep, Period >  duration)
inline

Tries to lock the mutex for given duration of time.

Wrapper for tryLockFor() which implements std::timed_mutex::try_lock_for() API.

Warning
This function must not be called from interrupt context!
Template Parameters
Repis type of tick counter
Periodis std::ratio type representing the tick period of the clock, seconds
Parameters
[in]durationis the duration after which the wait will be terminated without locking the mutex
Returns
true if the caller successfully locked the mutex, false otherwise
Here is the call graph for this function:

◆ try_lock_until()

template<typename Duration >
bool distortos::Mutex::try_lock_until ( const std::chrono::time_point< TickClock, Duration >  timePoint)
inline

Tries to lock the mutex until given time point.

Wrapper for tryLockUntil() which implements std::timed_mutex::try_lock_until() API.

Warning
This function must not be called from interrupt context!
Template Parameters
Durationis a std::chrono::duration type used to measure duration
Parameters
[in]timePointis the time point at which the wait will be terminated without locking the mutex
Returns
true if the caller successfully locked the mutex, false otherwise
Here is the call graph for this function:

◆ tryLock()

int distortos::Mutex::tryLock ( )

Tries to lock the mutex.

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#

This function shall be equivalent to lock(), except that if the mutex is currently locked (by any thread, including the current thread), the call shall return immediately.

Warning
This function must not be called from interrupt context!
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;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryLockFor() [1/2]

int distortos::Mutex::tryLockFor ( TickClock::duration  duration)

Tries to lock the mutex for given duration of time.

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#

If the mutex is already locked, the calling thread shall block until the mutex becomes available as in lock() function. If the mutex cannot be locked without waiting for another thread to unlock the mutex, this wait shall be terminated when the specified timeout expires.

Under no circumstance shall the function fail with a timeout if the mutex can be locked immediately. The validity of the duration parameter need not be checked if the mutex can be locked immediately.

Warning
This function must not be called from interrupt context!
Parameters
[in]durationis the duration 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;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryLockFor() [2/2]

template<typename Rep , typename Period >
int distortos::Mutex::tryLockFor ( const std::chrono::duration< Rep, Period >  duration)
inline

Tries to lock the mutex for given duration of time.

Template variant of tryLockFor(TickClock::duration duration).

Warning
This function must not be called from interrupt context!
Template Parameters
Repis type of tick counter
Periodis std::ratio type representing the tick period of the clock, seconds
Parameters
[in]durationis the duration 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;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ tryLockInternal()

int distortos::Mutex::tryLockInternal ( )
private

Internal version of tryLock().

Internal version with no interrupt masking and additional code for errorChecking type (which is not required for tryLock()).

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;
  • 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;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryLockUntil() [1/2]

int distortos::Mutex::tryLockUntil ( TickClock::time_point  timePoint)

Tries to lock the mutex until given time point.

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#

If the mutex is already locked, the calling thread shall block until the mutex becomes available as in lock() function. If the mutex cannot be locked without waiting for another thread to unlock the mutex, this wait shall be terminated when the specified timeout expires.

Under no circumstance shall the function fail with a timeout if the mutex can be locked immediately. The validity of the timePoint parameter need not be checked if the mutex can be locked immediately.

Warning
This function must not be called from interrupt context!
Parameters
[in]timePointis the time point 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;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:
Here is the caller graph for this function:

◆ tryLockUntil() [2/2]

template<typename Duration >
int distortos::Mutex::tryLockUntil ( const std::chrono::time_point< TickClock, Duration >  timePoint)
inline

Tries to lock the mutex until given time point.

Template variant of tryLockUntil(TickClock::time_point timePoint).

Warning
This function must not be called from interrupt context!
Template Parameters
Durationis a std::chrono::duration type used to measure duration
Parameters
[in]timePointis the time point 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;
  • ETIMEDOUT - the mutex could not be locked before the specified timeout expired;
Here is the call graph for this function:

◆ unlock()

int distortos::Mutex::unlock ( )

Unlocks the mutex.

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#

The mutex must be locked by the current thread, otherwise, the behavior is undefined. If there are threads blocked on this mutex, the highest priority waiting thread shall be unblocked, and if there is more than one highest priority thread blocked waiting, then the highest priority thread that has been waiting the longest shall be unblocked.

Warning
This function must not be called from interrupt context!
Returns
0 if the caller successfully unlocked the mutex, error code otherwise:
  • 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:
Here is the caller graph for this function:

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