Mutex
RTOS

RTOS mutex functions. More...

Functions

gos_result_t gos_rtos_mutex_init (gos_mutex_t *mutex)
Initializes a mutex. More...
gos_result_t gos_rtos_mutex_deinit (gos_mutex_t *mutex)
De-initialise a mutex. More...
gos_result_t gos_rtos_mutex_lock (gos_mutex_t *mutex)
Obtains the lock on a mutex. More...
gos_result_t gos_rtos_mutex_trylock (gos_mutex_t *mutex, uint32_t timeout_ms)
Obtains the lock on a mutex with timeout. More...
gos_result_t gos_rtos_mutex_unlock (gos_mutex_t *mutex)
Releases the lock on a mutex. More...
gos_result_t gos_rtos_mutex_current_thread_owns (const gos_mutex_t *mutex)
Determine if current thread owns the mutex. More...

Detailed Description

RTOS mutex functions.

Function Documentation

◆ gos_rtos_mutex_current_thread_owns()

gos_result_t gos_rtos_mutex_current_thread_owns ( const gos_mutex_t * mutex )

Determine if current thread owns the mutex.

This returns GOS_SUCCESS if the current thread has previously locked this mutex. It returns GOS_ERROR if the currrent thread has NOT previously locked this mutex.

Note
The provided mutex should have been previously initialized with gos_rtos_mutex_init() .
Parameters
[in] mutex : Pointer to the mutex handle to check lock status
Returns
Result of API call, gos_result_t

◆ gos_rtos_mutex_deinit()

gos_result_t gos_rtos_mutex_deinit ( gos_mutex_t * mutex )

De-initialise a mutex.

Deletes a mutex created with gos_rtos_mutex_init()

Parameters
[in] mutex : Pointer to the mutex handle
Returns
Result of API call, gos_result_t

◆ gos_rtos_mutex_init()

gos_result_t gos_rtos_mutex_init ( gos_mutex_t * mutex )

Initializes a mutex.

Initializes a recursive mutex. A mutex is different to a semaphore in that a thread that already holds the lock on the mutex can request the lock again (nested) without causing it to be suspended. Additionally, the thread that locks the mutex MUST also unlock the mutex at some point later.

Once the mutex is no longer needed, use gos_rtos_mutex_deinit() to clean up the mutex object.

Parameters
[in] mutex : Pointer to the mutex handle to be initialised
Returns
Result of API call, gos_result_t

◆ gos_rtos_mutex_lock()

gos_result_t gos_rtos_mutex_lock ( gos_mutex_t * mutex )

Obtains the lock on a mutex.

Attempts to obtain the lock on a mutex. If the lock is already held by another thread, the calling thread will be suspended until the mutex lock is released by the other thread.

Note
This API will block until the mutex is acquired. See gos_rtos_mutex_trylock() to only block for up to a maximum time.
The provided mutex should have been previously initialized with gos_rtos_mutex_init() .
Parameters
[in] mutex : Pointer to the mutex handle to be locked
Returns
Result of API call, gos_result_t

◆ gos_rtos_mutex_trylock()

gos_result_t gos_rtos_mutex_trylock ( gos_mutex_t * mutex,
uint32_t timeout_ms
)

Obtains the lock on a mutex with timeout.

This has the same functionality as gos_rtos_mutex_lock() except if it cannot obtain the lock after the specified timeout_ms then the API fails with GOS_TIMEOUT.

Note
The provided mutex should have been previously initialized with gos_rtos_mutex_init() .
Parameters
[in] mutex : Pointer to the mutex handle to be locked
[in] timeout_ms : Time in milliseconds to wait to acquire the mutex, return GOS_TIMEOUT if the timeout expires
Returns
Result of API call, gos_result_t

◆ gos_rtos_mutex_unlock()

gos_result_t gos_rtos_mutex_unlock ( gos_mutex_t * mutex )

Releases the lock on a mutex.

Releases a currently held lock on a mutex. If another thread is waiting on the mutex lock, then it will be resumed.

Note
The provided mutex should have been previously initialized with gos_rtos_mutex_init() .
Parameters
[in] mutex : Pointer to the mutex handle to be unlocked
Returns
Result of API call, gos_result_t