EtcPal
HEAD (unstable)
ETC Platform Abstraction Layer (EtcPal)
|
View other versions:
|
Mutual-exclusion (mutex) objects.
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:
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... | |
#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 PLATFORM_DEFINED etcpal_mutex_t |
The mutex identifier.
Depending on the platform, this could be a scalar type or a struct.
bool etcpal_mutex_create | ( | etcpal_mutex_t * | id | ) |
Create a new mutex.
[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. |
void etcpal_mutex_destroy | ( | etcpal_mutex_t * | id | ) |
Destroy a mutex object.
[in] | id | Identifier for the mutex to destroy. |
bool etcpal_mutex_lock | ( | etcpal_mutex_t * | id | ) |
Lock a mutex.
Blocks until the mutex is locked.
[in] | id | Identifier for the mutex to 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.
[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. |
bool etcpal_mutex_try_lock | ( | etcpal_mutex_t * | id | ) |
Try to lock a mutex.
Returns immediately either failure or success.
[in] | id | Identifier for the mutex to try to lock. |
void etcpal_mutex_unlock | ( | etcpal_mutex_t * | id | ) |
Unlock a mutex.
[in] | id | Identifier for the mutex to unlock. |