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

Mutex is the basic synchronization primitive. More...

#include <Mutex.hpp>

Collaboration diagram for distortos::Mutex:
[legend]

Public Types

enum  Type : uint8_t { Type::normal, Type::errorChecking, Type::recursive }
 type of mutex More...
 
using Protocol = internal::MutexControlBlock::Protocol
 mutex protocols More...
 
using RecursiveLocksCount = uint16_t
 type used for counting recursive locks More...
 

Public Member Functions

constexpr Mutex (const Type type=Type::normal, const Protocol protocol=Protocol::none, const uint8_t priorityCeiling={})
 Mutex constructor. 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)
 
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...
 
int unlock ()
 Unlocks the mutex. More...
 

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 Attributes

internal::MutexControlBlock controlBlock_
 instance of control block More...
 
RecursiveLocksCount recursiveLocksCount_
 number of recursive locks, used when mutex type is Recursive More...
 
Type type_
 type of mutex 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

◆ RecursiveLocksCount

type used for counting recursive locks

Member Enumeration Documentation

◆ Type

enum distortos::Mutex::Type : uint8_t
strong

type of mutex

Enumerator
normal 

normal mutex, similar to PTHREAD_MUTEX_NORMAL

errorChecking 

mutex with additional error checking, similar to PTHREAD_MUTEX_ERRORCHECK

recursive 

recursive mutex, similar to PTHREAD_MUTEX_RECURSIVE

Constructor & Destructor Documentation

◆ Mutex()

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

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

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

◆ 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
zero 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:

◆ 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
zero 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
zero 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
zero 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
zero 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
zero 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
zero 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
zero 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:

Member Data Documentation

◆ controlBlock_

internal::MutexControlBlock distortos::Mutex::controlBlock_
private

instance of control block

◆ recursiveLocksCount_

RecursiveLocksCount distortos::Mutex::recursiveLocksCount_
private

number of recursive locks, used when mutex type is Recursive

◆ type_

Type distortos::Mutex::type_
private

type of mutex


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