Mutex is the basic synchronization primitive. More...

#include "distortos/Mutex.hpp"

Inheritance diagram for distortos::Mutex:

Collaboration diagram for distortos::Mutex:

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 Mutex &	operator= (const Mutex &)=delete

Mutex &	operator= (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...

ThreadControlBlock *	getOwner () 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

RecursiveLocksCount &	getRecursiveLocksCount ()

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

using distortos::Mutex::Protocol = MutexProtocol

mutex protocols

◆ RecursiveLocksCount

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

type used for counting recursive locks

◆ Type

using distortos::Mutex::Type = MutexType

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]	type	is the type of mutex, default - Type::normal
[in]	protocol	is the mutex protocol, default - Protocol::none
[in]	priorityCeiling	is 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]	protocol	is the mutex protocol
[in]	priorityCeiling	is 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

Rep	is type of tick counter
Period	is std::ratio type representing the tick period of the clock, seconds

Parameters

[in] duration is 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

Duration is a std::chrono::duration type used to measure duration

Parameters

[in] timePoint is 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] duration is 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

Rep	is type of tick counter
Period	is std::ratio type representing the tick period of the clock, seconds

Parameters

[in] duration is 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] timePoint is 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

Duration is a std::chrono::duration type used to measure duration

Parameters

[in] timePoint is 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:

include/distortos/Mutex.hpp
source/synchronization/Mutex.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Protocol

◆ RecursiveLocksCount

◆ Type

Constructor & Destructor Documentation

◆ Mutex() [1/2]

◆ Mutex() [2/2]

◆ ~Mutex()

Member Function Documentation

◆ getMaxRecursiveLocks()

◆ lock()

◆ try_lock()

◆ try_lock_for()

◆ try_lock_until()

◆ tryLock()

◆ tryLockFor() [1/2]

◆ tryLockFor() [2/2]

◆ tryLockInternal()

◆ tryLockUntil() [1/2]

◆ tryLockUntil() [2/2]

◆ unlock()