sopc_mutexes.h File Reference

#include <stdint.h>
#include "sopc_enums.h"

Go to the source code of this file.

Macros
#define	SOPC_INVALID_COND   NULL
#define	SOPC_INVALID_MUTEX   NULL

Typedefs
typedef struct SOPC_Condition_Impl	SOPC_Condition_Impl
	Provides a condition-variable mechanism that supports single and broadcast notifications. More...
typedef SOPC_Condition_Impl *	SOPC_Condition
typedef struct SOPC_Mutex_Impl	SOPC_Mutex_Impl
	Provides a mutex mechanism that supports recursive locking. More...
typedef SOPC_Mutex_Impl *	SOPC_Mutex

Functions
SOPC_ReturnStatus	SOPC_Condition_Init (SOPC_Condition *cond)
	Create a Condition variable. More...
SOPC_ReturnStatus	SOPC_Condition_Clear (SOPC_Condition *cond)
	Delete a Condition variable. More...
SOPC_ReturnStatus	SOPC_Condition_SignalAll (SOPC_Condition *cond)
	Signals the condition variable to all waiting threads. More...
SOPC_ReturnStatus	SOPC_Mutex_Initialization (SOPC_Mutex *mut)
	Create a Mutex. More...
SOPC_ReturnStatus	SOPC_Mutex_Clear (SOPC_Mutex *mut)
	Delete a Mutex. More...
SOPC_ReturnStatus	SOPC_Mutex_Lock (SOPC_Mutex *mut)
	Lock a Mutex. The function may be blocking as long as the mutex is locked by another thread. More...
SOPC_ReturnStatus	SOPC_Mutex_Unlock (SOPC_Mutex *mut)
	Release a Mutex. More...
SOPC_ReturnStatus	SOPC_Mutex_UnlockAndWaitCond (SOPC_Condition *cond, SOPC_Mutex *mut)
	Wait for a condition variable notification. More...
SOPC_ReturnStatus	SOPC_Mutex_UnlockAndTimedWaitCond (SOPC_Condition *cond, SOPC_Mutex *mut, uint32_t milliSecs)
	Timed wait for a condition variable notification. More...

Detailed Description

The platform-specific implementation for all mutex-related services. Each platform implementation shall provide the actual definition of:

• SOPC_Condition_Impl for Condition Variables. (e.g. pthread_cond_t for LINUX)
• SOPC_Mutex_Impl for Mutexes. (e.g. pthread_mutex_t for LINUX)
• All functions defined in this header file.

Macro Definition Documentation

SOPC_INVALID_COND

#define SOPC_INVALID_COND   NULL

SOPC_INVALID_MUTEX

#define SOPC_INVALID_MUTEX   NULL

Typedef Documentation

SOPC_Condition_Impl

typedef struct SOPC_Condition_Impl SOPC_Condition_Impl

Provides a condition-variable mechanism that supports single and broadcast notifications.

Note

Each platform must provide the implementation of SOPC_Condition_Impl and all related functions. in sopc_mutexes.h

SOPC_Condition

typedef SOPC_Condition_Impl* SOPC_Condition

SOPC_Mutex_Impl

typedef struct SOPC_Mutex_Impl SOPC_Mutex_Impl

Provides a mutex mechanism that supports recursive locking.

Note

Each platform must provide the implementation of SOPC_Mutex_Impl and all related functions in sopc_mutexes.h

SOPC_Mutex

typedef SOPC_Mutex_Impl* SOPC_Mutex

Function Documentation

SOPC_Condition_Init()

SOPC_ReturnStatus SOPC_Condition_Init

(

SOPC_Condition *

cond

)

Create a Condition variable.

Parameters

cond	A non-NULL pointer to a condition to be created

Returns

SOPC_STATUS_OK in case of success. In case of failure, cond is set to SOPC_INVALID_COND (if not NULL).

SOPC_Condition_Clear()

SOPC_ReturnStatus SOPC_Condition_Clear

(

SOPC_Condition *

cond

)

Delete a Condition variable.

Parameters

cond	A non-NULL pointer to a condition to be deleted

Note

The related MUTEX shall be unlocked and shall be deleted after the condition variable

Returns

SOPC_STATUS_OK in case of success

SOPC_Condition_SignalAll()

SOPC_ReturnStatus SOPC_Condition_SignalAll

(

SOPC_Condition *

cond

)

Signals the condition variable to all waiting threads.

Parameters

cond	A non-NULL pointer to a condition to be signaled

Returns

SOPC_STATUS_OK in case of success

Note

Must be called between lock and unlock of dedicated Mutex

SOPC_Mutex_Initialization()

SOPC_ReturnStatus SOPC_Mutex_Initialization

(

SOPC_Mutex *

mut

)

Create a Mutex.

Parameters

mut	A non-NULL pointer to a Mutex to be created

Returns

SOPC_STATUS_OK in case of success. In case of failure, cond is set to SOPC_INVALID_MUTEX (if not NULL).

SOPC_Mutex_Clear()

SOPC_ReturnStatus SOPC_Mutex_Clear

(

SOPC_Mutex *

mut

)

Delete a Mutex.

Parameters

mut	A non-NULL pointer to a Mutex to be deleted

Returns

SOPC_STATUS_OK in case of success

SOPC_Mutex_Lock()

SOPC_ReturnStatus SOPC_Mutex_Lock

(

SOPC_Mutex *

mut

)

Lock a Mutex. The function may be blocking as long as the mutex is locked by another thread.

Note

Mutex shall be recursive. (The same thread can lock several times the same mutex without being blocked)

Parameters

mut	A non-NULL pointer to a Mutex to be locked

Returns

SOPC_STATUS_OK in case of success

SOPC_Mutex_Unlock()

SOPC_ReturnStatus SOPC_Mutex_Unlock

(

SOPC_Mutex *

mut

)

Release a Mutex.

Parameters

mut	A non-NULL pointer to a Mutex to be unlocked

Returns

SOPC_STATUS_OK in case of success

SOPC_Mutex_UnlockAndWaitCond()

SOPC_ReturnStatus SOPC_Mutex_UnlockAndWaitCond	(	SOPC_Condition *	cond,
		SOPC_Mutex *	mut
	)

Wait for a condition variable notification.

Parameters

cond	A non-NULL pointer to a Condition variable to wait for
mut	A non-NULL pointer to the related Mutex. This Mutex shall be locked by caller before call and unlocked after return.

Returns

SOPC_STATUS_OK in case of success

SOPC_Mutex_UnlockAndTimedWaitCond()

SOPC_ReturnStatus SOPC_Mutex_UnlockAndTimedWaitCond	(	SOPC_Condition *	cond,
		SOPC_Mutex *	mut,
		uint32_t	milliSecs
	)

Timed wait for a condition variable notification.

Parameters

cond	A non-NULL pointer to a Condition variable to wait for
mut	A non-NULL pointer to the related Mutex. This Mutex shall be locked by caller before call and unlocked after return.
milliSecs	The maximum amount of wait time.

Returns

SOPC_STATUS_OK in case of success. SOPC_STATUS_TIMEOUT if the condition is not received within the requested timeout