async.h File Reference

Asynchronous Thread and Mutex Management Functions. More...

#include "common.h"
#include <stdarg.h>

Go to the source code of this file.

Macros
#define	QSC_ASYNC_PARALLEL_MAX   128ULL
	The maximum number of threads that can be launched in parallel for a parallel for loop.

Functions
QSC_EXPORT_API void	qsc_async_launch_thread (void(*func)(void *), void *state)
	Launch a function on a new thread.
QSC_EXPORT_API void	qsc_async_launch_parallel_threads (void(*func)(void *), size_t count,...)
	Launch multiple threads in parallel using variadic arguments.
QSC_EXPORT_API qsc_mutex	qsc_async_mutex_create (void)
	Create a mutex.
QSC_EXPORT_API bool	qsc_async_mutex_destroy (qsc_mutex mtx)
	Destroy a mutex.
QSC_EXPORT_API void	qsc_async_mutex_lock (qsc_mutex mtx)
	Lock a mutex.
QSC_EXPORT_API qsc_mutex	qsc_async_mutex_lock_ex (void)
	Create and lock a mutex.
QSC_EXPORT_API void	qsc_async_mutex_unlock (qsc_mutex mtx)
	Unlock a mutex.
QSC_EXPORT_API void	qsc_async_mutex_unlock_ex (qsc_mutex mtx)
	Unlock and destroy a mutex.
QSC_EXPORT_API size_t	qsc_async_processor_count (void)
	Get the number of processor cores available.
QSC_EXPORT_API qsc_thread	qsc_async_thread_create (void(*func)(void *), void *state)
	Create a thread with one parameter.
QSC_EXPORT_API qsc_thread	qsc_async_thread_create_ex (void(*func)(void **), void **args)
	Create a thread with multiple parameters.
QSC_EXPORT_API int32_t	qsc_async_thread_resume (qsc_thread handle)
	Resume a suspended thread.
QSC_EXPORT_API void	qsc_async_thread_sleep (uint32_t msec)
	Suspend the calling thread for a specified number of milliseconds.
QSC_EXPORT_API int32_t	qsc_async_thread_suspend (qsc_thread handle)
	Suspend a thread.
QSC_EXPORT_API bool	qsc_async_thread_terminate (qsc_thread handle)
	Terminate a thread.
QSC_EXPORT_API void	qsc_async_thread_wait (qsc_thread handle)
	Wait for a thread to complete execution.
QSC_EXPORT_API void	qsc_async_thread_wait_time (qsc_thread handle, uint32_t msec)
	Wait for a thread to complete execution with a timeout.
QSC_EXPORT_API void	qsc_async_thread_wait_all (qsc_thread *handles, size_t count)
	Wait for an array of threads to complete execution.

Detailed Description

Asynchronous Thread and Mutex Management Functions.

This header defines the public API for asynchronous thread management and mutex operations. It provides functions for launching threads (both individually and in parallel), creating and managing mutexes for thread synchronization, and waiting on thread execution. The API supports both Windows and POSIX threading models.

// Example: Launch a single thread.
qsc_async_launch_thread(sample_task, (void*)arg);
 
// Example: Launch multiple threads in parallel.
qsc_async_launch_parallel_threads(sample_task, 4, (void*)arg1, (void*)arg2, (void*)arg3, (void*)arg4);
 
// Example: Create, lock, and unlock a mutex.
qsc_mutex mtx = qsc_async_mutex_create();
qsc_async_mutex_lock(mtx);
// Perform critical operations here.
qsc_async_mutex_unlock(mtx);
qsc_async_mutex_destroy(mtx);

Reference Links:

• Microsoft Windows Threading
• POSIX Threads (pthreads)

Function Documentation

qsc_async_launch_parallel_threads()

QSC_EXPORT_API void qsc_async_launch_parallel_threads	(	void(*	func )(void *),
		size_t	count,
			... )

Launch multiple threads in parallel using variadic arguments.

Spawns several threads, each executing the provided function with its respective argument.

Parameters

func	[void (*)(void*)] Pointer to the function to execute.
count	[size_t] The number of threads (and corresponding arguments) to launch.
...	[variadic] Variadic arguments representing the state for each thread.

qsc_async_launch_thread()

QSC_EXPORT_API void qsc_async_launch_thread	(	void(*	func )(void *),
		void *	state )

Launch a function on a new thread.

Spawns a new thread to execute the provided function with a single argument.

Parameters

func	[void (*)(void*)] Pointer to the function to execute.
state	[void*] Pointer to the argument to pass to the function.

qsc_async_mutex_create()

QSC_EXPORT_API qsc_mutex qsc_async_mutex_create

(

void

)

Create a mutex.

Creates a new mutex object for synchronizing threads.

Returns

[qsc_mutex] Returns a handle to the newly created mutex.

qsc_async_mutex_destroy()

QSC_EXPORT_API bool qsc_async_mutex_destroy

(

qsc_mutex

mtx

)

Destroy a mutex.

Destroys the specified mutex object.

Parameters

mtx	[qsc_mutex] The mutex handle to destroy.

Returns

[bool] Returns true on successful destruction.

qsc_async_mutex_lock()

QSC_EXPORT_API void qsc_async_mutex_lock

(

qsc_mutex

mtx

)

Lock a mutex.

Blocks until the specified mutex is acquired.

Parameters

mtx	[qsc_mutex] The mutex to lock.

qsc_async_mutex_lock_ex()

QSC_EXPORT_API qsc_mutex qsc_async_mutex_lock_ex

(

void

)

Create and lock a mutex.

Creates a mutex, locks it immediately, and returns the locked mutex.

Returns

[qsc_mutex] The locked mutex handle.

qsc_async_mutex_unlock()

QSC_EXPORT_API void qsc_async_mutex_unlock

(

qsc_mutex

mtx

)

Unlock a mutex.

Unlocks the specified mutex.

Parameters

mtx	[qsc_mutex] The mutex to unlock.

qsc_async_mutex_unlock_ex()

QSC_EXPORT_API void qsc_async_mutex_unlock_ex

(

qsc_mutex

mtx

)

Unlock and destroy a mutex.

Unlocks the specified mutex and then destroys it.

Parameters

mtx	[qsc_mutex] The mutex to unlock and destroy.

qsc_async_processor_count()

QSC_EXPORT_API size_t qsc_async_processor_count

(

void

)

Get the number of processor cores available.

Retrieves the number of CPU cores (including hyper-threads) available on the system.

Returns

[size_t] The number of processor cores.

qsc_async_thread_create()

QSC_EXPORT_API qsc_thread qsc_async_thread_create	(	void(*	func )(void *),
		void *	state )

Create a thread with one parameter.

Creates a new thread that executes the specified function with a single argument.

Parameters

func	[void (*)(void*)] Pointer to the function to execute in the new thread.
state	[void*] Pointer to the argument to pass to the thread function.

Returns

[qsc_thread] Returns a handle to the created thread, or NULL on failure.

qsc_async_thread_create_ex()

QSC_EXPORT_API qsc_thread qsc_async_thread_create_ex	(	void(*	func )(void **),
		void **	args )

Create a thread with multiple parameters.

Creates a new thread that executes the specified function with multiple arguments.

Parameters

func	[void (*)(void**)] Pointer to the function to execute in the new thread.
args	[void**] An array of pointers to the arguments.

Returns

[qsc_thread] Returns a handle to the created thread, or NULL on failure.

qsc_async_thread_resume()

QSC_EXPORT_API int32_t qsc_async_thread_resume

(

qsc_thread

handle

)

Resume a suspended thread.

Resumes execution of a thread that has been suspended.

Parameters

handle

[qsc_thread] The thread handle to resume.

Returns

[int32_t] Returns zero on success.

qsc_async_thread_sleep()

QSC_EXPORT_API void qsc_async_thread_sleep

(

uint32_t

msec

)

Suspend the calling thread for a specified number of milliseconds.

Suspends execution of the calling thread for the given duration.

Parameters

msec	[uint32_t] The number of milliseconds to sleep.

qsc_async_thread_suspend()

QSC_EXPORT_API int32_t qsc_async_thread_suspend

(

qsc_thread

handle

)

Suspend a thread.

Suspends the execution of the specified thread.

Parameters

handle

[qsc_thread] The thread handle to suspend.

Returns

[int32_t] Returns a non-negative value on success.

qsc_async_thread_terminate()

QSC_EXPORT_API bool qsc_async_thread_terminate

(

qsc_thread

handle

)

Terminate a thread.

Terminates the specified thread. On Windows, this may terminate the calling thread.

Parameters

handle

[qsc_thread] The thread handle to terminate.

Returns

[bool] Returns true if termination was successful.

qsc_async_thread_wait()

QSC_EXPORT_API void qsc_async_thread_wait

(

qsc_thread

handle

)

Wait for a thread to complete execution.

Blocks until the specified thread has finished executing.

Parameters

handle

[qsc_thread] The thread handle to wait on.

qsc_async_thread_wait_all()

QSC_EXPORT_API void qsc_async_thread_wait_all	(	qsc_thread *	handles,
		size_t	count )

Wait for an array of threads to complete execution.

Blocks until all threads in the provided array have finished executing.

Parameters

handles	[qsc_thread*] An array of thread handles.
count	[size_t] The number of threads in the array.

qsc_async_thread_wait_time()

QSC_EXPORT_API void qsc_async_thread_wait_time	(	qsc_thread	handle,
		uint32_t	msec )

Wait for a thread to complete execution with a timeout.

Blocks until the specified thread has finished executing or the timeout expires.

Parameters

handle	[qsc_thread] The thread handle to wait on.
msec	[uint32_t] The maximum number of milliseconds to wait.