EtcPal  HEAD (unstable)
ETC Platform Abstraction Layer (EtcPal)
View other versions:
mutex (Mutexes)

Overview

Mutual-exclusion (mutex) objects.

#include "etcpal/mutex.h"

Sometimes also referred to as a critical section. Only one thread can lock the mutex at a time using etcpal_mutex_lock(). Where possible on real-time platforms, the mutex provides priority inheritance.

Mutexes are used to synchronize access to data from different threads. For example:

static int shared_counter;
void counter_thread(void* arg)
{
for (int i = 0; i < 10000; ++i)
{
// Ensure that we are the only context conducting read-modify-write operations on
// shared_counter. No other thread can be in this block of code at the same time.
++shared_counter;
}
}
int main(void)
{
etcpal_thread_t thread_handles[5];
for (int i = 0; i < 5; ++i)
{
etcpal_thread_create(&thread_handles[i], &params, counter_thread, NULL);
}
// Wait for the threads to finish
for (int i = 0; i < 5; ++i)
{
etcpal_thread_join(&thread_handles[i]);
}
printf("The counter is: %d\n", shared_counter); // Prints "The counter is: 50000"
return 0;
}
void etcpal_mutex_destroy(etcpal_mutex_t *id)
Destroy a mutex object.
PLATFORM_DEFINED etcpal_mutex_t
The mutex identifier.
Definition: mutex.dox:84
void etcpal_mutex_unlock(etcpal_mutex_t *id)
Unlock a mutex.
bool etcpal_mutex_create(etcpal_mutex_t *id)
Create a new mutex.
bool etcpal_mutex_lock(etcpal_mutex_t *id)
Lock a mutex.
etcpal_error_t etcpal_thread_create(etcpal_thread_t *id, const EtcPalThreadParams *params, void(*thread_fn)(void *), void *thread_arg)
Create a new thread.
PLATFORM_DEFINED etcpal_thread_t
The thread handle.
Definition: thread.dox:35
etcpal_error_t etcpal_thread_join(etcpal_thread_t *id)
Wait for a thread to finish execution.
#define ETCPAL_THREAD_PARAMS_INIT
A default initializer value for an EtcPalThreadParams structure.
Definition: thread.h:191
etcpal_error_t etcpal_thread_sleep(unsigned int sleep_ms)
Provides a platform-neutral sleep.
A set of parameters for an etcpal_thread.
Definition: thread.h:130

Mutexes are not recursive; if the same mutex object is locked twice from the same thread before being unlocked, a deadlock will result.

etcpal_mutex implementations use different constructs under the hood on various platforms. Also, different platforms affect the behavior of certain functions.

Platform ETCPAL_MUTEX_HAS_TIMED_LOCK Underlying Type
FreeRTOS Yes Mutexes
Linux No pthread_mutex
macOS No pthread_mutex
MQX Yes Lightweight Semaphores
Windows No SRWLocks
Zephyr Yes Mutexes

Macros

#define ETCPAL_MUTEX_HAS_TIMED_LOCK   /* platform-defined */
 Whether etcpal_mutex_timed_lock() is meaningful on this platform. More...
 

Typedefs

typedef PLATFORM_DEFINED etcpal_mutex_t
 The mutex identifier. More...
 

Functions

bool etcpal_mutex_create (etcpal_mutex_t *id)
 Create a new mutex. More...
 
bool etcpal_mutex_lock (etcpal_mutex_t *id)
 Lock a mutex. More...
 
bool etcpal_mutex_try_lock (etcpal_mutex_t *id)
 Try to lock a mutex. More...
 
bool etcpal_mutex_timed_lock (etcpal_mutex_t *id, int timeout_ms)
 Try to lock a mutex, giving up after a timeout. More...
 
void etcpal_mutex_unlock (etcpal_mutex_t *id)
 Unlock a mutex. More...
 
void etcpal_mutex_destroy (etcpal_mutex_t *id)
 Destroy a mutex object. More...
 

Macro Definition Documentation

◆ ETCPAL_MUTEX_HAS_TIMED_LOCK

#define ETCPAL_MUTEX_HAS_TIMED_LOCK   /* platform-defined */

Whether etcpal_mutex_timed_lock() is meaningful on this platform.

If defined to 0, etcpal_mutex_timed_lock() executes the equivalent of etcpal_mutex_try_lock() if given a timeout of 0, or etcpal_mutex_lock() otherwise.

Typedef Documentation

◆ etcpal_mutex_t

typedef PLATFORM_DEFINED etcpal_mutex_t

The mutex identifier.

Depending on the platform, this could be a scalar type or a struct.

Function Documentation

◆ etcpal_mutex_create()

bool etcpal_mutex_create ( etcpal_mutex_t id)

Create a new mutex.

Parameters
[out]idMutex identifier on which to create a mutex. If this function returns true, id becomes valid for calls to other etcpal_mutex API functions.
Returns
true: The mutex was created.
false: The mutex was not created.

◆ etcpal_mutex_destroy()

void etcpal_mutex_destroy ( etcpal_mutex_t id)

Destroy a mutex object.

Parameters
[in]idIdentifier for the mutex to destroy.

◆ etcpal_mutex_lock()

bool etcpal_mutex_lock ( etcpal_mutex_t id)

Lock a mutex.

Blocks until the mutex is locked.

Parameters
[in]idIdentifier for the mutex to lock.
Returns
true: The mutex is locked.
false: The mutex is invalid or an error occurred.

◆ etcpal_mutex_timed_lock()

bool etcpal_mutex_timed_lock ( etcpal_mutex_t id,
int  timeout_ms 
)

Try to lock a mutex, giving up after a timeout.

This function is not honored on all platforms. The value of ETCPAL_MUTEX_HAS_TIMED_LOCK can be used to determine whether this function is honored on the current platform. If it is defined to 0, this function executes the equivalent of etcpal_mutex_try_lock() if timeout_ms is 0, or etcpal_mutex_lock() otherwise.

Parameters
[in]idIdentifier for the mutex to try to acquire.
[in]timeout_msMaximum amount of time to wait for the mutex to become available, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_mutex_lock() was called.
Returns
true: The mutex is locked.
false: The timeout expired while waiting to lock the mutex, the mutex is invalid or an error occurred.

◆ etcpal_mutex_try_lock()

bool etcpal_mutex_try_lock ( etcpal_mutex_t id)

Try to lock a mutex.

Returns immediately either failure or success.

Parameters
[in]idIdentifier for the mutex to try to lock.
Returns
true: The mutex is locked.
false: The mutex is locked by another thread, the mutex is invalid or an error occurred.

◆ etcpal_mutex_unlock()

void etcpal_mutex_unlock ( etcpal_mutex_t id)

Unlock a mutex.

Parameters
[in]idIdentifier for the mutex to unlock.