Mutex Class Reference

The Mutex class is used to synchronize the execution of threads. More...

#include <Mutex.h>

Inheritance diagram for Mutex:

Public Member Functions
	Mutex ()
	Create and Initialize a Mutex object.
	Mutex (const char *name)
	Create and Initialize a Mutex object.
void	lock ()
	Wait until a Mutex becomes available.
bool	trylock ()
	Try to lock the mutex, and return immediately.
bool	trylock_for (uint32_t millisec)
	Try to lock the mutex for a specified time.
bool	trylock_for (Kernel::Clock::duration_u32 rel_time)
	Try to lock the mutex for a specified time.
bool	trylock_until (uint64_t millisec)
	Try to lock the mutex until specified time.
bool	trylock_until (Kernel::Clock::time_point abs_time)
	Try to lock the mutex until specified time.
void	unlock ()
	Unlock the mutex that has previously been locked by the same thread.
osThreadId_t	get_owner ()
	Get the owner the this mutex.
	~Mutex ()
	Mutex destructor.

Detailed Description

The Mutex class is used to synchronize the execution of threads.

This is, for example, used to protect access to a shared resource.

In bare-metal builds, the Mutex class is a dummy, so lock() and unlock() are no-ops.

Mbed Mutexes are recursive. So, if you call the lock() function multiple times, you must call unlock() the same number of times to unlock the mutex. This means that it's okay to lock a mutex, then call another function that also locks and unlocks the mutex, and the mutex won't actually get unlocked until your function unlocks it.

Note

You cannot use member functions of this class in ISR context. If you require Mutex functionality within ISR handler, consider using Semaphore.

Memory considerations: The mutex control structures are created on the current thread's stack, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).

Definition at line 79 of file Mutex.h.

Constructor & Destructor Documentation

Mutex() [1/2]

Mutex

(

)

Create and Initialize a Mutex object.

Note

You cannot call this function from ISR context.

Mutex() [2/2]

Mutex

(

const char *

name

)

Create and Initialize a Mutex object.

Parameters

name	name to be used for this mutex. It has to stay allocated for the lifetime of the thread.

Note

You cannot call this function from ISR context.

~Mutex()

~Mutex

(

)

Mutex destructor.

Note

You cannot call this function from ISR context.

Member Function Documentation

lock()

void lock

(

)

Wait until a Mutex becomes available.

Note

You cannot call this function from ISR context.

trylock()

bool trylock

(

)

Try to lock the mutex, and return immediately.

Returns

true if the mutex was acquired, false otherwise.

Note

equivalent to trylock_for(0)

You cannot call this function from ISR context.

trylock_for() [1/2]

bool trylock_for

(

uint32_t

millisec

)

Try to lock the mutex for a specified time.

Parameters

millisec

timeout value.

Returns

true if the mutex was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the lock attempt will time out earlier than specified.

You cannot call this function from ISR context.

Deprecated:

Pass a chrono duration, not an integer millisecond count. For example use 5s rather than 5000.

trylock_for() [2/2]

bool trylock_for

(

Kernel::Clock::duration_u32

rel_time

)

Try to lock the mutex for a specified time.

Parameters

rel_time

timeout value.

Returns

true if the mutex was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the lock attempt will time out earlier than specified.

You cannot call this function from ISR context.

trylock_until() [1/2]

bool trylock_until

(

uint64_t

millisec

)

Try to lock the mutex until specified time.

Parameters

millisec

absolute timeout time, referenced to Kernel::get_ms_count()

Returns

true if the mutex was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the lock attempt will time out earlier than specified.

You cannot call this function from ISR context.

Deprecated:

Pass a chrono time_point, not an integer millisecond count. For example use Kernel::Clock::now() + 5s rather than Kernel::get_ms_count() + 5000.

trylock_until() [2/2]

bool trylock_until

(

Kernel::Clock::time_point

abs_time

)

Try to lock the mutex until specified time.

Parameters

abs_time

absolute timeout time, referenced to Kernel::Clock

Returns

true if the mutex was acquired, false otherwise.

Note

the underlying RTOS may have a limit to the maximum wait time due to internal 32-bit computations, but this is guaranteed to work if the wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, the lock attempt will time out earlier than specified.

You cannot call this function from ISR context.

unlock()

void unlock

(

)

Unlock the mutex that has previously been locked by the same thread.

Note

You cannot call this function from ISR context.

get_owner()

osThreadId_t get_owner

(

)

Get the owner the this mutex.

Returns

the current owner of this mutex.

Note

You cannot call this function from ISR context.