async.h File Reference

Asynchronous Thread and Mutex Management Functions. More...

#include "qsccommon.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 bool	qsc_async_atomic_bool_load (volatile bool *target)
	Atomically load the current value of a boolean.
QSC_EXPORT_API void	qsc_async_atomic_bool_store (volatile bool *target, bool value)
	Atomically store a value into a boolean.
QSC_EXPORT_API bool	qsc_async_atomic_bool_exchange (volatile bool *target, bool value)
	Atomically swap a boolean with a new value.
QSC_EXPORT_API bool	qsc_async_atomic_bool_compare_exchange (volatile bool *target, bool expected, bool desired)
	Atomically compare a boolean and conditionally store a new value.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_load (volatile int32_t *target)
	Atomically load an int32_t value.
QSC_EXPORT_API void	qsc_async_atomic_int32_store (volatile int32_t *target, int32_t value)
	Atomically store an int32_t value.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_exchange (volatile int32_t *target, int32_t value)
	Atomically exchange an int32_t value.
QSC_EXPORT_API bool	qsc_async_atomic_int32_compare_exchange (volatile int32_t *target, int32_t expected, int32_t desired)
	Atomically compare and conditionally exchange an int32_t value.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_add (volatile int32_t *target, int32_t value)
	Atomically add a value to an int32_t.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_subtract (volatile int32_t *target, int32_t value)
	Atomically subtract a value from an int32_t.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_increment (volatile int32_t *target)
	Atomically increment an int32_t by one.
QSC_EXPORT_API int32_t	qsc_async_atomic_int32_decrement (volatile int32_t *target)
	Atomically decrement an int32_t by one.
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 qsc_thread	qsc_async_thread_create_noargs (void(*func)(void))
	Create a thread with no arguments parameter.
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_atomic_bool_compare_exchange()

QSC_EXPORT_API bool qsc_async_atomic_bool_compare_exchange	(	volatile bool *	target,
		bool	expected,
		bool	desired )

Atomically compare a boolean and conditionally store a new value.

Reads target and compares it to expected. If they are equal, desired is written to target and the function returns true. If they differ, the target is left unchanged and the function returns false. The comparison and the conditional store are performed as a single indivisible operation.

Parameters

target	[volatile bool*] Pointer to the boolean to test and update. Must not be NULL.
expected	[bool] The value the caller expects target to currently hold.
desired	[bool] The value to store if the comparison succeeds.

Returns

[bool] True if the store was performed; false if target did not equal expected.

qsc_async_atomic_bool_exchange()

QSC_EXPORT_API bool qsc_async_atomic_bool_exchange	(	volatile bool *	target,
		bool	value )

Atomically swap a boolean with a new value.

Stores value into target and returns the value that target held immediately before the swap. The read and the write occur as a single indivisible operation; no other thread can observe an intermediate state.

Parameters

target	[volatile bool*] Pointer to the boolean to swap. Must not be NULL.
value	[bool] The new value to store.

Returns

[bool] The previous value of target before the swap.

qsc_async_atomic_bool_load()

QSC_EXPORT_API bool qsc_async_atomic_bool_load

(

volatile bool *

target

)

Atomically load the current value of a boolean.

Reads the value at target using a sequentially consistent atomic load. The operation is equivalent to acquiring the value without the possibility of observing a partial write from a concurrent store.

Parameters

target

[volatile bool*] Pointer to the boolean to read. Must not be NULL.

Returns

[bool] The value held by target at the time of the load.

qsc_async_atomic_bool_store()

QSC_EXPORT_API void qsc_async_atomic_bool_store	(	volatile bool *	target,
		bool	value )

Atomically store a value into a boolean.

Writes value to target using a sequentially consistent atomic store. Any thread that subsequently calls qsc_async_atomic_bool_load on the same target is guaranteed to observe value or any later write.

Parameters

target	[volatile bool*] Pointer to the boolean to write. Must not be NULL.
value	[bool] The value to store.

qsc_async_atomic_int32_add()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_add	(	volatile int32_t *	target,
		int32_t	value )

Atomically add a value to an int32_t.

Adds value to *target and returns the value AFTER the addition.

Parameters

target	[volatile int32_t*] Pointer to the atomic integer.
value	[int32_t] The amount to add.

Returns

[int32_t] The new value of *target after the addition.

qsc_async_atomic_int32_compare_exchange()

QSC_EXPORT_API bool qsc_async_atomic_int32_compare_exchange	(	volatile int32_t *	target,
		int32_t	expected,
		int32_t	desired )

Atomically compare and conditionally exchange an int32_t value.

If *target equals expected, stores desired into *target. The comparison and store occur as a single atomic operation.

Parameters

target	[volatile int32_t*] Pointer to the atomic integer.
expected	[int32_t] The value the caller expects *target to hold.
desired	[int32_t] The value to store if the comparison succeeds.

Returns

[bool] True if the exchange was performed; false otherwise.

qsc_async_atomic_int32_decrement()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_decrement

(

volatile int32_t *

target

)

Atomically decrement an int32_t by one.

Decrements *target by one and returns the value AFTER the decrement.

Parameters

target

[volatile int32_t*] Pointer to the atomic integer.

Returns

[int32_t] The new value of *target after the decrement.

qsc_async_atomic_int32_exchange()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_exchange	(	volatile int32_t *	target,
		int32_t	value )

Atomically exchange an int32_t value.

Writes value to *target and returns the previous value.

Parameters

target	[volatile int32_t*] Pointer to the atomic integer.
value	[int32_t] The new value to store.

Returns

[int32_t] The previous value of *target.

qsc_async_atomic_int32_increment()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_increment

(

volatile int32_t *

target

)

Atomically increment an int32_t by one.

Increments *target by one and returns the value AFTER the increment.

Parameters

target

[volatile int32_t*] Pointer to the atomic integer.

Returns

[int32_t] The new value of *target after the increment.

qsc_async_atomic_int32_load()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_load

(

volatile int32_t *

target

)

Atomically load an int32_t value.

Reads the current value of *target with sequential consistency.

Parameters

target

[volatile int32_t*] Pointer to the atomic integer.

Returns

[int32_t] The current value.

qsc_async_atomic_int32_store()

QSC_EXPORT_API void qsc_async_atomic_int32_store	(	volatile int32_t *	target,
		int32_t	value )

Atomically store an int32_t value.

Writes value to *target with sequential consistency.

Parameters

target	[volatile int32_t*] Pointer to the atomic integer.
value	[int32_t] The value to store.

qsc_async_atomic_int32_subtract()

QSC_EXPORT_API int32_t qsc_async_atomic_int32_subtract	(	volatile int32_t *	target,
		int32_t	value )

Atomically subtract a value from an int32_t.

Subtracts value from *target and returns the value AFTER the subtraction.

Parameters

target	[volatile int32_t*] Pointer to the atomic integer.
value	[int32_t] The amount to subtract.

Returns

[int32_t] The new value of *target after the subtraction.

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_create_noargs()

QSC_EXPORT_API qsc_thread qsc_async_thread_create_noargs

(

void(*

func )(void)

)

Create a thread with no arguments parameter.

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.

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.