Thread.h file

Type definitions and function declarations for threading functionality.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Classes

struct CnxJThread: A CnxJThread is the handle type for OS-level threads which are automatically joined when their handle goes out of scope and use a dedicated stop token to signal to the thread when its execution should end.

Typedefs

using CnxBasicMutex = __cnx_basic_mutex: CnxBasicMutex is the basic mutual exclusion object type provided by Cnx's threading and synchronization API. Using a CnxBasicMutex to control access to shared resources will ensure that all access is synchronized and mutually exclusive between threads.
using CnxRecursiveBasicMutex = __cnx_recursive_basic_mutex: CnxRecursiveBasicMutex is the basic reentrant mutual exclusion object type provided by Cnx's threading and synchronization API. Using a CnxRecursiveBasicMutex to control access to shared resources will ensure that all access is synchronized and mutually exclusive between threads, and allows for rentrant ownership of the lock on that access.
using CnxBasicCondvar = __cnx_condvar: CnxBasicCondvar is the Condition Variable object type provided by Cnx's threading and synchronization API. Using a CnxBasicCondvar allows to block one or more threads until an event is triggered, without wasting CPU resources.
using CnxThreadID = __cnx_thread_id: A CnxThreadID uniquely identifies an indiviual thread.
using CnxThread = __cnx_thread: A CnxThread is the handle type for basic OS-level threads provided by Cnx's threading and synchronization API. CnxThread provides the facilities for creating multiple threads and ending their execution, enabling concurrent tasks and operations to be performed.
using CnxStopToken = atomic_bool: A CnxStopToken is associated with a CnxJThread and is used to signal to it when it should end its execution.
using CnxTLSKey = __cnx_tls_key: A CnxTLSKey is the key type for creating, accessing, and modifying a thread-local storage object.
using CnxOnceFlag = __cnx_exec_once_flag: A CnxOnceFlag is a synchronization flag type for use with cnx_execute_once to ensure a given function is executed exactly once, regardless of how many threads attempt to call it, as long as all threads do so through the same CnxOnceFlag and cnx_execute_once

Functions

CnxResult(CnxBasicMutex): Creates a new mutex.
CnxResult cnx_basic_mutex_init(CnxBasicMutex*restrict mutex): Initializes the mutex pointed to by mutex
CnxResult cnx_basic_mutex_lock(CnxBasicMutex*restrict mutex): Unconditionally locks the mutex pointed to by mutex
bool cnx_basic_mutex_try_lock(CnxBasicMutex*restrict mutex): Attempts to lock the mutex pointed to by mutex
CnxResult cnx_basic_mutex_unlock(CnxBasicMutex*restrict mutex): Unlocks the mutex pointed to by mutex
CnxResult cnx_basic_mutex_free(CnxBasicMutex*restrict mutex): Destroys the mutex pointed to by mutex
CnxResult(CnxRecursiveBasicMutex): Creates a new recursive mutex.
CnxResult cnx_recursive_basic_mutex_init(CnxRecursiveBasicMutex*restrict mutex): Initializes the recursive mutex pointed to by mutex
CnxResult cnx_recursive_basic_mutex_lock(CnxRecursiveBasicMutex*restrict mutex): Unconditionally locks the recursive mutex pointed to by mutex
bool cnx_recursive_basic_mutex_try_lock(CnxRecursiveBasicMutex*restrict mutex): Attempts to lock the recursive mutex pointed to by mutex
CnxResult cnx_recursive_basic_mutex_unlock(CnxRecursiveBasicMutex*restrict mutex): Unlocks the recursive mutex pointed to by mutex
CnxResult cnx_recursive_basic_mutex_free(CnxRecursiveBasicMutex*restrict mutex): Destroys the recursive mutex pointed to by mutex
CnxResult(CnxBasicCondvar): Creates a new condition variable, returning the result in a CnxResult
CnxResult cnx_basic_condvar_init(CnxBasicCondvar*restrict condvar): Initializes the condition variable pointed to by condvar
CnxResult cnx_basic_condvar_signal(CnxBasicCondvar*restrict condvar): Signals to the first thread waiting on the condition variable pointed to by condvar to wake and continue execution.
CnxResult cnx_basic_condvar_broadcast(CnxBasicCondvar*restrict condvar): Signals to every thread waiting on the condition variable pointed to by condvar to wake and continue execution.
CnxResult cnx_basic_condvar_wait(CnxBasicCondvar*restrict condvar, CnxBasicMutex*restrict mutex): Blocks on the condition variable pointed to by condvar until the thread is signalled by it.
CnxResult cnx_basic_condvar_wait_for(CnxBasicCondvar*restrict condvar, CnxBasicMutex*restrict mutex, CnxDuration to_wait) cnx_disable_if(!mutex: Blocks on the condition variable pointed to by condvar until the thread is signalled by it, or to_wait time has elapsed.
CnxResult cnx_basic_condvar_wait_until(CnxBasicCondvar*restrict condvar, CnxBasicMutex*restrict mutex, CnxTimePoint stop_point) cnx_disable_if(!mutex: Blocks on the condition variable pointed to by condvar until the thread is signalled by it, or the point in time indicated by stop_point time has been reached.
CnxResult cnx_basic_condvar_free(CnxBasicCondvar*restrict condvar): Destroys the condition variable pointed to by condvar
CnxResult cnx_execute_once(CnxOnceFlag*restrict flag, void(*)(void) function) cnx_disable_if(!flag: Executes the given function exactly once.
CnxCompare cnx_thread_id_compare(CnxThreadID lhs, CnxThreadID rhs): Compares the two CnxThreadIDs.
bool cnx_thread_id_equal(CnxThreadID lhs, CnxThreadID rhs): Returns whether the two CnxThreadIDs are equal.
bool cnx_thread_id_less_than(CnxThreadID lhs, CnxThreadID rhs): Returns whether the first CnxThreadID is less than the second.
bool cnx_thread_id_less_than_or_equal(CnxThreadID lhs, CnxThreadID rhs): Returns whether the first CnxThreadID is less than or equal to the second.
bool cnx_thread_id_greater_than(CnxThreadID lhs, CnxThreadID rhs): Returns whether the first CnxThreadID is greater than the second.
bool cnx_thread_id_greater_than_or_equal(CnxThreadID lhs, CnxThreadID rhs): Returns whether the first CnxThreadID is greater than or equal to the second.
typedef Lambda(void) CnxThreadLambda: When spawning a new thread, a Lambda(void) is used as its startup routine. This typedef allows for receiving that startup routine as a function parameter.
CnxResult(CnxThread): Spawns a new thread, with the given CnxThreadLambda as its startup routine.
CnxResult cnx_thread_init(CnxThread*restrict thread, CnxThreadLambda lambda): Spawns a new thread, with the given CnxThreadLambda as its startup routine.
bool cnx_thread_is_null(const CnxThread*restrict thread): Checks if the given thread handle is null (if it has been initialized)
CnxThreadID cnx_thread_get_id(const CnxThread*restrict thread): Gets the ID of the current thread.
CnxResult cnx_thread_join(CnxThread*restrict thread): Joins the given thread, blocking until its execution has completed.
CnxResult cnx_thread_detach(CnxThread*restrict thread): Separates execution of the thread associated with the given thread handle from the handle.
void cnx_thread_free(void* thread): Frees the given thread, blocking until it's joined or joining fails.
void cnx_this_thread_yield(void): Yields execution of the current thread, allowing the operating system to execute other threads until it decides to return execution to this one.
void cnx_this_thread_sleep_for(CnxDuration duration): Yields execution of the current thread until at least the given duration of time has passed.
CnxThreadID cnx_this_thread_get_id(void): Returns the ID of the current thread.
void cnx_stop_token_request_stop(CnxStopToken*restrict token): Requests the thread associated with the given stop token to end execution.
bool cnx_stop_token_stop_requested(const CnxStopToken*restrict token): Returns whether the thread associated with the given stop token has been requested to end execution.
typedef Lambda(void, const CnxStopToken*) CnxJThreadLambda: When spawning a new CnxJThread, a Lambda(void, const CnxStopToken*) is used as its startup routine. This typedef allows for receiving that startup routine as a function parameter.
CnxResult(CnxJThread): Spawns a new CnxJThread, with the given CnxJThreadLambda as its startup routine.
CnxResult cnx_jthread_init(CnxJThread*restrict thread, CnxJThreadLambda lambda): Spawns a new CnxJThread, with the given CnxJThreadLambda as its startup routine.
CnxResult cnx_jthread_join(CnxJThread*restrict thread): Joins the given CnxJThread, blocking until its execution has completed.
void cnx_jthread_free(void* thread): Frees the given CnxJThread, blocking until it's joined or joining fails.
CnxResult(CnxTLSKey) cnx_tls_new(void *data: Creates a new thread-local storage.
CnxResult cnx_tls_init(CnxTLSKey*restrict key, void* data, void(__CNX_TLS_DESTRUCTOR_TAG*destructor)(void*)): Initializes a thread-local storage and associates it with the key pointed to by key
void* cnx_tls_get(CnxTLSKey key): Retrieves the current value of the thread-local storage associated with key
CnxResult cnx_tls_set(CnxTLSKey key, void* data): Sets the value of the thread-local storage associated with key to data

Defines

#define thread_local: A variable declared as thread_local is local to the current thread and guaranteed to not be accessible by other threads.
#define cnx_jthread_is_null(thread): Checks if the given thread handle is null (if it has been initialized)
#define cnx_jthread_get_id(thread): Gets the ID of the current thread.
#define cnx_jthread_detach(thread): Separates execution of the thread associated with the CnxJThread thread handle from the handle.