sopc_threads.h File Reference

#include <stddef.h>
#include "sopc_enums.h"
#include "sopc_mutexes.h"

Go to the source code of this file.

Macros
#define	SOPC_INVALID_THREAD   NULL

Typedefs
typedef struct SOPC_Thread_Impl	SOPC_Thread_Impl
	Provides a threading mechanism.
typedef SOPC_Thread_Impl *	SOPC_Thread

Functions
SOPC_ReturnStatus	SOPC_Thread_Create (SOPC_Thread *thread, void *(*startFct)(void *), void *startArgs, const char *taskName)
	Function to create a thread.
SOPC_ReturnStatus	SOPC_Thread_CreatePrioritized (SOPC_Thread *thread, void *(*startFct)(void *), void *startArgs, int priority, const char *taskName)
	Function to create a high priority thread.
SOPC_ReturnStatus	SOPC_Thread_Join (SOPC_Thread *thread)
	Function to wait for a thread to terminate.
void	SOPC_Sleep (unsigned int milliseconds)
	Suspend current thread execution for (at least) a millisecond interval.

Detailed Description

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

• SOPC_Thread for threads (e.g. pthread_t for linux)
• All functions defined in this header file.

Macro Definition Documentation

SOPC_INVALID_THREAD

#define SOPC_INVALID_THREAD   NULL

Typedef Documentation

SOPC_Thread_Impl

typedef struct SOPC_Thread_Impl SOPC_Thread_Impl

Provides a threading mechanism.

Note

The stack size of each thread is not configurable via the S2OPC API. Therefore, in the specific case of embedded target with limited RAM, the implementation must provide an internal mechanism to fine tune the thread stacks dimensioning.

Each platform must provide the implementation of SOPC_Thread_Impl and all related functions in this file

SOPC_Thread

typedef SOPC_Thread_Impl* SOPC_Thread

Function Documentation

SOPC_Thread_Create()

SOPC_ReturnStatus SOPC_Thread_Create	(	SOPC_Thread *	thread,
		void *(*	startFct )(void *),
		void *	startArgs,
		const char *	taskName )

Function to create a thread.

Parameters

thread	Return parameter for the created thread
startFct	Function called at thread start. The startFct function is called in a new thread context with startArgs as parameter. The return value is not relevant and shall be set to NULL.
startArgs	Arguments of the start function
taskName	Name of the created thread

Returns

SOPC_STATUS_OK if operation succeeded, SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_NOK otherwise.

Note

The created thread must be joined using SOPC_Thread_Join to ensure context deletion.

Warning

Depending on platform, the taskName length might be limited (e.g.: 16 characters including terminating null byte for POSIX). In this case the taskName will be truncated to comply with limitation.

SOPC_Thread_CreatePrioritized()

SOPC_ReturnStatus SOPC_Thread_CreatePrioritized	(	SOPC_Thread *	thread,
		void *(*	startFct )(void *),
		void *	startArgs,
		int	priority,
		const char *	taskName )

Function to create a high priority thread.

Note

Only supported under Linux for now.

See SOPC_Thread_Create. This function creates a thread with specific priority, which usually requires administrative privileges. It should only be used to create threads that require to be woken up at regular but small intervals (< 1ms). Note that this interface does not specify the 'order' of priorities regarding the value. (typically on Zephyr, lower values are the highest priorities, whereas on Linux, this is the contrary).

Parameters

thread	Return parameter for the created thread
startFct	Function called at thread start
startArgs	Arguments of the start function
priority	Priority of the thread (range depends on implementation) : Linux: 1 .. 99, FreeRTOS: 1 .. configMAX_PRIORITIES ZEPHYR: 1 .. CONFIG_NUM_COOP_PRIORITIES + CONFIG_NUM_PREEMPT_PRIORITIES. Note that this is a simple offset of (CONFIG_NUM_COOP_PRIORITIES + 1) regarding the Zephyr native priorities. This is required to ensure consistency with S2OPC interface. In prj.conf, the priorities configured MUST take into account this offset.
taskName	Name of the created thread

Note

The created thread must be joined using SOPC_Thread_Join to ensure context deletion.

Returns

SOPC_STATUS_OK if operation succeeded, SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_NOK otherwise.

SOPC_Thread_Join()

SOPC_ReturnStatus SOPC_Thread_Join

(

SOPC_Thread *

thread

)

Function to wait for a thread to terminate.

Parameters

thread

Thread to wait for, created either by SOPC_Thread_Create or SOPC_Thread_CreatePrioritized. Each thread can and shall be joined once only when terminating. In case of success the pointed thread value becomes SOPC_INVALID_THREAD

Returns

SOPC_STATUS_OK if operation succeeded, SOPC_STATUS_INVALID_PARAMETERS if thread is NULL or SOPC_STATUS_NOK otherwise.

SOPC_Sleep()

void SOPC_Sleep

(

unsigned int

milliseconds

)

Suspend current thread execution for (at least) a millisecond interval.

Parameters

milliseconds

The milliseconds interval value for which execution must be suspended