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"

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

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,
                              IOT_THREAD_DEFAULT_PRIORITY,
                              IOT_THREAD_DEFAULT_STACK_SIZE ) == true )
{
    // 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]	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`.

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] pMutex The 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] pMutex The 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] pMutex The 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] pMutex The 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 intial 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]	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.

Returns: true if semaphore creation succeeds; false otherwise.

See also: IotSemaphore_Destroy

Example

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

◆ 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] pSemaphore The 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] pSemaphore The 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] pSemaphore The 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] pSemaphore The 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]	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.

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] pSemaphore The semaphore to unlock.

Functions

Detailed Description

Function Documentation

◆ Iot_CreateDetachedThread()

◆ IotMutex_Create()

◆ IotMutex_Destroy()

◆ IotMutex_Lock()

◆ IotMutex_TryLock()

◆ IotMutex_Unlock()

◆ IotSemaphore_Create()

◆ IotSemaphore_Destroy()

◆ IotSemaphore_GetCount()

◆ IotSemaphore_Wait()

◆ IotSemaphore_TryWait()

◆ IotSemaphore_TimedWait()

◆ IotSemaphore_Post()