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;
etcpal_mutex_t mutex;
 
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.
    etcpal_mutex_lock(&mutex);
    ++shared_counter;
    etcpal_mutex_unlock(&mutex);
  }
}
 
int main(void)
{
  etcpal_mutex_create(&mutex);
 
  EtcPalThreadParams thread_params = ETCPAL_THREAD_PARAMS_INIT;
  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
  etcpal_thread_sleep(1000);
  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"
 
  etcpal_mutex_destroy(&mutex);
  return 0;
}

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]

id

Mutex 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]

id

Identifier 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]

id

Identifier 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]	id	Identifier for the mutex to try to acquire.
[in]	timeout_ms	Maximum 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]

id

Identifier 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]

id

Identifier for the mutex to unlock.