AWS IoT Device SDK C: Platform
Platform portability layer
Return to main page ↑
iot_threads.h File Reference

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...
 

Detailed Description

Threading and synchronization functions used by libraries in this SDK.

Function Documentation

◆ Iot_CreateDetachedThread()

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.

Parameters
[in]threadRoutineThe function this thread should run.
[in]pArgumentThe argument passed to threadRoutine.
[in]priorityRepresents 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]stackSizeRepresents 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.
Returns
true if the new thread was successfully created; false otherwise.
// Thread routine.
void threadRoutine( void * pArgument );
// Run threadRoutine in a detached thread, using default priority and stack size.
if( Iot_CreateDetachedThread( threadRoutine,
NULL,
{
// Success
}
else
{
// Failure, no thread was created.
}

◆ IotMutex_Create()

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.

Parameters
[in]pNewMutexPointer to the memory that will hold the new mutex.
[in]recursiveSet 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.
Returns
true if mutex creation succeeds; false otherwise.
See also
IotMutex_Destroy

Example

IotMutex_t mutex;
// Create non-recursive mutex.
if( IotMutex_Create( &mutex, false ) == true )
{
// Lock and unlock the mutex...
// Destroy the mutex when it's no longer needed.
IotMutex_Destroy( &mutex );
}

◆ IotMutex_Destroy()

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).

Parameters
[in]pMutexThe mutex to destroy.
Warning
This function must not be called on a locked mutex.
See also
IotMutex_Create

◆ IotMutex_Lock()

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.

Parameters
[in]pMutexThe mutex to lock.
See also
IotMutex_TryLock for a nonblocking lock.

◆ IotMutex_TryLock()

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.

Parameters
[in]pMutexThe mutex to lock.
Returns
true if the mutex was successfully locked; false if the mutex was not available.
See also
IotMutex_Lock for a blocking lock.

◆ IotMutex_Unlock()

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.

Parameters
[in]pMutexThe mutex to unlock.
Note
This function should not be called on a mutex that is already unlocked.

◆ IotSemaphore_Create()

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.

Parameters
[in]pNewSemaphorePointer to the memory that will hold the new semaphore.
[in]initialValueThe semaphore should be initialized with this value.
[in]maxValueThe maximum value the semaphore will reach.
Returns
true if semaphore creation succeeds; false otherwise.
See also
IotSemaphore_Destroy

Example

// Create a locked binary semaphore.
if( IotSemaphore_Create( &sem, 0, 1 ) == true )
{
// Unlock the semaphore.
// Destroy the semaphore when it's no longer needed.
}

◆ IotSemaphore_Destroy()

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).

Parameters
[in]pSemaphoreThe semaphore to destroy.
Warning
This function must not be called on a semaphore with waiting threads.
See also
IotSemaphore_Create

◆ IotSemaphore_GetCount()

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.

Parameters
[in]pSemaphoreThe semaphore to query.
Returns
The current count of the semaphore. This function should not fail.

◆ IotSemaphore_Wait()

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.

Parameters
[in]pSemaphoreThe semaphore to lock.
See also
IotSemaphore_TryWait for a nonblocking wait; IotSemaphore_TimedWait for a wait with timeout.

◆ IotSemaphore_TryWait()

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.

Parameters
[in]pSemaphoreThe semaphore to lock.
Returns
true if the semaphore wait succeeded; false if the semaphore has a count of 0.
See also
IotSemaphore_Wait for a blocking wait; IotSemaphore_TimedWait for a wait with timeout.

◆ IotSemaphore_TimedWait()

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.

Parameters
[in]pSemaphoreThe semaphore to lock.
[in]timeoutMsRelative timeout of semaphore lock. This function returns false if the semaphore couldn't be locked within this timeout.
Returns
true if the semaphore wait succeeded; false if it timed out.
See also
IotSemaphore_TryWait for a nonblocking wait; IotSemaphore_Wait for a blocking wait.

◆ IotSemaphore_Post()

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.

Parameters
[in]pSemaphoreThe semaphore to unlock.