Native thread management functions. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/results.h"
#include "gate/objects.h"
#include "gate/handles.h"

Macros
#define	GATE_THREAD_MODEL_NONE 0

#define	GATE_THREAD_MODEL_COOPERATIVE 1

#define	GATE_THREAD_MODEL_PREEMPTIVE 2

Typedefs
typedef gate_handlestore_t	gate_thread_t
	gate_thread_t holds the native thread resource handle to control it.

typedef gate_uintptr_t	gate_thread_id_t
	gate_thread_id_t represents the thread with a printable unique ID.

Functions
GATE_CORE_API unsigned int	gate_thread_model ()
	Returns the supported threading model of the implemented platform.

GATE_CORE_API gate_result_t	gate_thread_start_native (gate_thread_native_entry entry_function, gate_thread_native_param_type entry_param, gate_thread_t thread_handle, gate_thread_id_t thread_id)
	Starts a new thread and executes a platform native entry point.

GATE_CORE_API gate_result_t	gate_thread_start (gate_runnable_t executor, gate_thread_t thread_handle, gate_thread_id_t *thread_id)
	Starts a new thread and executes runnable.run function in it.

GATE_CORE_API gate_result_t	gate_thread_start_code (gate_result_t(callback)(void ), void data, gate_thread_t thread_handle, gate_thread_id_t *thread_id)
	Starts a new thread and executes the given callback function.

GATE_CORE_API gate_result_t	gate_thread_detach (gate_thread_t *thread_handle)
	Closes the given thread handle, no further thread control will be available. Handle becomes invalid in case of successful execution.

GATE_CORE_API gate_result_t	gate_thread_join (gate_thread_t thread_handle, gate_result_t result)
	Awaits thread shutdown and returns the result-code, that was returned by the executed code. Handle becomes invalid in case of successful execution.

GATE_CORE_API gate_result_t	gate_thread_current (gate_thread_t thread_handle, gate_thread_id_t thread_id)
	Returns a thread handle and ID of the currently running thread executing this function.

GATE_CORE_API gate_result_t	gate_thread_is_current (gate_thread_t thread_handle, gate_bool_t is_current)
	Returns TRUE if the given thread handle represents the currently executing thread.

GATE_CORE_API gate_bool_t	gate_thread_equals (gate_thread_t thread_handle_1, gate_thread_t thread_handle_2)
	Returns TRUE if two given thread handles identify the same thread. Notice: Returned thread handles may contain different bits but may reference only on one specific thread.

GATE_CORE_API void	gate_thread_sleep (gate_uint32_t milliseconds)
	Stops execution of the current thread and waits for the given amount of time.

GATE_CORE_API void	gate_thread_yield (void)
	Requests the current thread to give up its execution time slice to favor other threads.

GATE_CORE_API gate_bool_t	gate_thread_yield_if_preemptive (void)
	Requests the current thread to give up its execution time slice only if preemptive threading is required (e.g. in case of single-core CPUs).

GATE_CORE_API gate_result_t	gate_thread_storage_alloc (gate_thread_storage_t *ptr_store_id)
	Registeres a thread storage and returns an ID to access it.

GATE_CORE_API gate_result_t	gate_thread_storage_set (gate_thread_storage_t ptr_store_id, void data)
	Attaches a pointer value to a registered thread storage ID.

GATE_CORE_API gate_result_t	gate_thread_storage_get (gate_thread_storage_t ptr_store_id, void *ptr_data)
	Returns the value of a previously stored pointer in a registered thread storage.

GATE_CORE_API gate_result_t	gate_thread_storage_dealloc (gate_thread_storage_t *ptr_store_id)
	Unregisteres a thread storage ID and frees all associated resources.

Detailed Description

Native thread management functions.

Macro Definition Documentation

◆ GATE_THREAD_MODEL_NONE

#define GATE_THREAD_MODEL_NONE 0

mulitthreading is not supported

◆ GATE_THREAD_MODEL_COOPERATIVE

#define GATE_THREAD_MODEL_COOPERATIVE 1

cooperative threading is supported (yield() to next thread)

◆ GATE_THREAD_MODEL_PREEMPTIVE

#define GATE_THREAD_MODEL_PREEMPTIVE 2

preemptive multithreading is supported

Function Documentation

◆ gate_thread_model()

GATE_CORE_API unsigned int gate_thread_model ( )

Returns the supported threading model of the implemented platform.

Returns: returns on of GATE_THREAD_MODEL_* constants.

◆ gate_thread_start_native()

GATE_CORE_API gate_result_t gate_thread_start_native	(	gate_thread_native_entry	entry_function,
		gate_thread_native_param_type	entry_param,
		gate_thread_t *	thread_handle,
		gate_thread_id_t *	thread_id )

Starts a new thread and executes a platform native entry point.

Parameters

[in]	entry_function	pointer to native thread entry function
[in]	entry_param	native entry function parameter
[out]	thread_handle	output pointer that receives a handle to the created thread.
[out]	thread_id	output pointer that receives the ID of the created thread.

Returns: returns OK if the thread was successfully created or the reason of failure.

◆ gate_thread_start()

GATE_CORE_API gate_result_t gate_thread_start	(	gate_runnable_t *	executor,
		gate_thread_t *	thread_handle,
		gate_thread_id_t *	thread_id )

Starts a new thread and executes runnable.run function in it.

Parameters

[in]	executor	runnable object that holds the code to be executed. Pointer ownership will be shared with thread on success (refcount++).
[out]	thread_handle	output pointer that receives a handle to the created thread.
[out]	thread_id	output pointer that receives the ID of the created thread.

Returns: returns OK if the thread was successfully created or the reason of failure.

◆ gate_thread_start_code()

GATE_CORE_API gate_result_t gate_thread_start_code	(	gate_result_t(*	callback )(void *),
		void *	data,
		gate_thread_t *	thread_handle,
		gate_thread_id_t *	thread_id )

Starts a new thread and executes the given callback function.

Parameters

[in]	callback	callback function pointer to be executed in the new thread.
[in]	data	data pointer that is handed over to the callback function in the new thread.
[out]	thread_handle	output pointer that receives a handle to the created thread.
[out]	thread_id	output pointer that receives the ID of the created thread.

Returns: returns OK if the thread was successfully created or the reason of failure.

◆ gate_thread_detach()

GATE_CORE_API gate_result_t gate_thread_detach ( gate_thread_t * thread_handle )

Closes the given thread handle, no further thread control will be available. Handle becomes invalid in case of successful execution.

Parameters

[in] thread_handle Handle that was created in gate_thread_start* functions.

Returns: returns OK if the thread handle was successfully closed or the reason of failure.

◆ gate_thread_join()

GATE_CORE_API gate_result_t gate_thread_join	(	gate_thread_t *	thread_handle,
		gate_result_t *	result )

Awaits thread shutdown and returns the result-code, that was returned by the executed code. Handle becomes invalid in case of successful execution.

Parameters

[in]	thread_handle	Handle that was created in gate_thread_start* functions.
[out]	result	Pointer to output result code returned by the executed code.

Returns: returns OK if the thread was successfully joined or the reason of failure.

◆ gate_thread_current()

GATE_CORE_API gate_result_t gate_thread_current	(	gate_thread_t *	thread_handle,
		gate_thread_id_t *	thread_id )

Returns a thread handle and ID of the currently running thread executing this function.

Parameters

[out]	thread_handle	Pointer to handle that receives a thread handle of the current thread.
[out]	thread_id	Pointer to ID that receives a unique ID of the current thread.

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_is_current()

GATE_CORE_API gate_result_t gate_thread_is_current	(	gate_thread_t *	thread_handle,
		gate_bool_t *	is_current )

Returns TRUE if the given thread handle represents the currently executing thread.

Parameters

[in]	thread_handle	Captured handle of a specific thread.
[out]	is_current	Pointer to boolean that receives status.

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_equals()

GATE_CORE_API gate_bool_t gate_thread_equals	(	gate_thread_t *	thread_handle_1,
		gate_thread_t *	thread_handle_2 )

Returns TRUE if two given thread handles identify the same thread. Notice: Returned thread handles may contain different bits but may reference only on one specific thread.

Parameters

[in]	thread_handle_1	Captured thread handle of one specific thread.
[in]	thread_handle_2	Another captured thread handle.

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_sleep()

GATE_CORE_API void gate_thread_sleep ( gate_uint32_t milliseconds )

Stops execution of the current thread and waits for the given amount of time.

Parameters

[in] milliseconds Amount of milliseconds to stop thread execution.

◆ gate_thread_yield_if_preemptive()

GATE_CORE_API gate_bool_t gate_thread_yield_if_preemptive ( void )

Requests the current thread to give up its execution time slice only if preemptive threading is required (e.g. in case of single-core CPUs).

Returns: Returns TRUE if thread was yielded or FALSE if yielding is not required.

◆ gate_thread_storage_alloc()

GATE_CORE_API gate_result_t gate_thread_storage_alloc ( gate_thread_storage_t * ptr_store_id )

Registeres a thread storage and returns an ID to access it.

Parameters

[out] ptr_store_id Pointer to variable that receives an ID to access the storage.

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_storage_set()

GATE_CORE_API gate_result_t gate_thread_storage_set	(	gate_thread_storage_t *	ptr_store_id,
		void *	data )

Attaches a pointer value to a registered thread storage ID.

Parameters

[in]	ptr_store_id	Pointer to variable that contains a registered thread storage ID.
[in]	data	Data pointer to be stored

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_storage_get()

GATE_CORE_API gate_result_t gate_thread_storage_get	(	gate_thread_storage_t *	ptr_store_id,
		void **	ptr_data )

Returns the value of a previously stored pointer in a registered thread storage.

Parameters

[in]	ptr_store_id	Pointer to variable that contains a registered thread storage ID.
[out]	ptr_data	Pointer to memory that is filed with the value of the stored data pointer

Returns: returns OK if the function was successful or the reason of failure.

◆ gate_thread_storage_dealloc()

GATE_CORE_API gate_result_t gate_thread_storage_dealloc ( gate_thread_storage_t * ptr_store_id )

Unregisteres a thread storage ID and frees all associated resources.

Parameters

[in] ptr_store_id Pointer to variable that contains a registered thread storage ID.

Returns: returns OK if the function was successful or the reason of failure.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ GATE_THREAD_MODEL_NONE

◆ GATE_THREAD_MODEL_COOPERATIVE

◆ GATE_THREAD_MODEL_PREEMPTIVE

Function Documentation

◆ gate_thread_model()

◆ gate_thread_start_native()

◆ gate_thread_start()

◆ gate_thread_start_code()

◆ gate_thread_detach()

◆ gate_thread_join()

◆ gate_thread_current()

◆ gate_thread_is_current()

◆ gate_thread_equals()

◆ gate_thread_sleep()

◆ gate_thread_yield_if_preemptive()

◆ gate_thread_storage_alloc()

◆ gate_thread_storage_set()

◆ gate_thread_storage_get()

◆ gate_thread_storage_dealloc()