AWS IoT Device SDK C:
Platform
Platform portability layer
|
Return to main page ↑ |
Threading and synchronization functions used by libraries in this SDK. More...
#include "iot_config.h"
#include <stdbool.h>
#include <stdint.h>
#include "types/iot_platform_types.h"
Go to the source code of this file.
Functions | |
bool | Iot_CreateDetachedThread (IotThreadRoutine_t threadRoutine, void *pArgument, int32_t priority, size_t stackSize) |
Create a new detached thread, i.e. a thread that cleans up after itself. More... | |
bool | IotMutex_Create (IotMutex_t *pNewMutex, bool recursive) |
Create a new mutex. More... | |
void | IotMutex_Destroy (IotMutex_t *pMutex) |
Free resources used by a mutex. More... | |
void | IotMutex_Lock (IotMutex_t *pMutex) |
Lock a mutex. This function should only return when the mutex is locked; it is not expected to fail. More... | |
bool | IotMutex_TryLock (IotMutex_t *pMutex) |
Attempt to lock a mutex. Return immediately if the mutex is not available. More... | |
void | IotMutex_Unlock (IotMutex_t *pMutex) |
Unlock a mutex. This function should only return when the mutex is unlocked; it is not expected to fail. More... | |
bool | IotSemaphore_Create (IotSemaphore_t *pNewSemaphore, uint32_t initialValue, uint32_t maxValue) |
Create a new counting semaphore. More... | |
void | IotSemaphore_Destroy (IotSemaphore_t *pSemaphore) |
Free resources used by a semaphore. More... | |
uint32_t | IotSemaphore_GetCount (IotSemaphore_t *pSemaphore) |
Query the current count of the semaphore. More... | |
void | IotSemaphore_Wait (IotSemaphore_t *pSemaphore) |
Wait on (lock) a semaphore. This function should only return when the semaphore wait succeeds; it is not expected to fail. More... | |
bool | IotSemaphore_TryWait (IotSemaphore_t *pSemaphore) |
Attempt to wait on (lock) a semaphore. Return immediately if the semaphore is not available. More... | |
bool | IotSemaphore_TimedWait (IotSemaphore_t *pSemaphore, uint32_t timeoutMs) |
Attempt to wait on (lock) a semaphore with a timeout. More... | |
void | IotSemaphore_Post (IotSemaphore_t *pSemaphore) |
Post to (unlock) a semaphore. This function should only return when the semaphore post succeeds; it is not expected to fail. More... | |
Threading and synchronization functions used by libraries in this SDK.
bool Iot_CreateDetachedThread | ( | IotThreadRoutine_t | threadRoutine, |
void * | pArgument, | ||
int32_t | priority, | ||
size_t | stackSize | ||
) |
Create a new detached thread, i.e. a thread that cleans up after itself.
This function creates a new thread. Threads created by this function exit upon returning from the thread routine. Any resources taken must be freed by the exiting thread.
[in] | threadRoutine | The function this thread should run. |
[in] | pArgument | The argument passed to threadRoutine . |
[in] | priority | Represents the priority of the new thread, as defined by the system. The value IOT_THREAD_DEFAULT_PRIORITY (i.e. 0 ) must be used to represent the system default for thread priority. IOT_THREAD_IGNORE_PRIORITY should be passed if this parameter is not relevant for the port implementation. |
[in] | stackSize | Represents the stack size of the new thread, as defined by the system. The value IOT_THREAD_DEFAULT_STACK_SIZE (i.e. 0 ) must be used to represent the system default for stack size. IOT_THREAD_IGNORE_STACK_SIZE should be passed if this parameter is not relevant for the port implementation. |
true
if the new thread was successfully created; false
otherwise.bool IotMutex_Create | ( | IotMutex_t * | pNewMutex, |
bool | recursive | ||
) |
Create a new mutex.
This function creates a new, unlocked mutex. It must be called on an uninitialized IotMutex_t. This function must not be called on an already-initialized IotMutex_t.
[in] | pNewMutex | Pointer to the memory that will hold the new mutex. |
[in] | recursive | Set to true to create a recursive mutex, i.e. a mutex that may be locked multiple times by the same thread. If the system does not support recursive mutexes, this function should do nothing and return false . |
true
if mutex creation succeeds; false
otherwise.Example
void IotMutex_Destroy | ( | IotMutex_t * | pMutex | ) |
Free resources used by a mutex.
This function frees resources used by a mutex. It must be called on an initialized IotMutex_t. No other mutex functions should be called on pMutex
after calling this function (unless the mutex is re-created).
[in] | pMutex | The mutex to destroy. |
void IotMutex_Lock | ( | IotMutex_t * | pMutex | ) |
Lock a mutex. This function should only return when the mutex is locked; it is not expected to fail.
This function blocks and waits until a mutex is available. It waits forever (deadlocks) if pMutex
is already locked and never unlocked.
[in] | pMutex | The mutex to lock. |
bool IotMutex_TryLock | ( | IotMutex_t * | pMutex | ) |
Attempt to lock a mutex. Return immediately if the mutex is not available.
If pMutex
is available, this function immediately locks it and returns. Otherwise, this function returns without locking pMutex
.
[in] | pMutex | The mutex to lock. |
true
if the mutex was successfully locked; false
if the mutex was not available.void IotMutex_Unlock | ( | IotMutex_t * | pMutex | ) |
Unlock a mutex. This function should only return when the mutex is unlocked; it is not expected to fail.
Unlocks a locked mutex. pMutex
must have been locked by the thread calling this function.
[in] | pMutex | The mutex to unlock. |
bool IotSemaphore_Create | ( | IotSemaphore_t * | pNewSemaphore, |
uint32_t | initialValue, | ||
uint32_t | maxValue | ||
) |
Create a new counting semaphore.
This function creates a new counting semaphore with a given initial and maximum value. It must be called on an uninitialized IotSemaphore_t. This function must not be called on an already-initialized IotSemaphore_t.
[in] | pNewSemaphore | Pointer to the memory that will hold the new semaphore. |
[in] | initialValue | The semaphore should be initialized with this value. |
[in] | maxValue | The maximum value the semaphore will reach. |
true
if semaphore creation succeeds; false
otherwise.Example
void IotSemaphore_Destroy | ( | IotSemaphore_t * | pSemaphore | ) |
Free resources used by a semaphore.
This function frees resources used by a semaphore. It must be called on an initialized IotSemaphore_t. No other semaphore functions should be called on pSemaphore
after calling this function (unless the semaphore is re-created).
[in] | pSemaphore | The semaphore to destroy. |
uint32_t IotSemaphore_GetCount | ( | IotSemaphore_t * | pSemaphore | ) |
Query the current count of the semaphore.
This function queries a counting semaphore for its current value. A counting semaphore's value is always 0 or positive.
[in] | pSemaphore | The semaphore to query. |
void IotSemaphore_Wait | ( | IotSemaphore_t * | pSemaphore | ) |
Wait on (lock) a semaphore. This function should only return when the semaphore wait succeeds; it is not expected to fail.
This function blocks and waits until a counting semaphore is positive. It waits forever (deadlocks) if pSemaphore
has a count 0
that is never incremented.
[in] | pSemaphore | The semaphore to lock. |
bool IotSemaphore_TryWait | ( | IotSemaphore_t * | pSemaphore | ) |
Attempt to wait on (lock) a semaphore. Return immediately if the semaphore is not available.
If the count of pSemaphore
is positive, this function immediately decrements the semaphore and returns. Otherwise, this function returns without decrementing pSemaphore
.
[in] | pSemaphore | The semaphore to lock. |
true
if the semaphore wait succeeded; false
if the semaphore has a count of 0
.bool IotSemaphore_TimedWait | ( | IotSemaphore_t * | pSemaphore, |
uint32_t | timeoutMs | ||
) |
Attempt to wait on (lock) a semaphore with a timeout.
This function blocks and waits until a counting semaphore is positive or its timeout expires (whichever is sooner). It decrements pSemaphore
and returns true
if the semaphore is positive at some time during the wait. If pSemaphore
is always 0
during the wait, this function returns false
.
[in] | pSemaphore | The semaphore to lock. |
[in] | timeoutMs | Relative timeout of semaphore lock. This function returns false if the semaphore couldn't be locked within this timeout. |
true
if the semaphore wait succeeded; false
if it timed out.void IotSemaphore_Post | ( | IotSemaphore_t * | pSemaphore | ) |
Post to (unlock) a semaphore. This function should only return when the semaphore post succeeds; it is not expected to fail.
This function increments the count of a semaphore. Any thread may call this function to increment a semaphore's count.
[in] | pSemaphore | The semaphore to unlock. |