chsvthrd.h File Reference

An interface for the portable implementation of threads as defined in C11 standard supplemented with some extensions. More...

#include "chsvbase.h"
#include "chsvsal.h"
#include "chsverr.h"
#include <cstdint>
#include <thread>
#include <mutex>
#include <condition_variable>
#include <atomic>

Classes
struct	chsv_xtime
	A structure type to hold a time given in seconds and nanoseconds passed since the Epoch. See chsv_xtime_get for details. More...
class	shared_mutex
	An implementation of C++17 shared_mutex primitive for read-write lock. See C++17 shared_mutex and N2406. More...
class	shared_lock< Mutex >
	Implements std::shared_lock interface of C++14. More...
class	latch
	Implements a single-use barrier synchronization. More...
struct	barrier_default_completion
	Default class of a completion routine object called by a default instantiation of barrier upon opening. More...
class	barrier< CompletionFunction >
	Implements a reusable barrier synchronization primitive. More...

Namespaces
	Chusov
	Basic chsvlib namespace.
	Chusov::ExecutionControl
	A namespace of execution control facilities.

Macros
#define	EXECUTION_CONTROL_BEGIN   namespace ExecutionControl {
	Defines the beginning of the Chusov::ExecutionControl namespace without defining the encapsulating namespaces. More...
#define	EXECUTION_CONTROL_END   }
	Defines the end of the Chusov::ExecutionControl namespace. More...
#define	chsv_thread_local(type, name)   thread_local type name
	A macro simplifying work with thread-specific storages. It is introduced to implement syntax similar to the one defined by the C++11 thread_local keyword. More...
#define	chsv_thread_local_get(name)   name
	Resolves a name of a thread-local variable. More...

Typedefs
typedef struct Implementation ::OnceFlagImpl	chsv_once_t
	A type of a flag used by chsv_once.

Functions
template<class SharedMutex >
void	swap (shared_lock< SharedMutex > &left, shared_lock< SharedMutex > &right) noexcept
	Swaps states of two shared_lock objects. More...

Synchronized one-time calling primitive
Portable implementation of the call-once concept.
#define	CHSV_ONCE_INIT   RESOLVE_NAMESPACE(::Chusov::ExecutionControl::Implementation) ImplOnceFlagInit()
	A macro which is expanded to a value used to initialize a flag of type chsv_once_t. More...
void	chsv_once (chsv_once_t *flag, void(*func)(void))
	The function uses a specified once flag to ensure that a specified function is called exactly once, the first time the function is called with that value of the flag. More...
bool	chsv_once_ex (chsv_once_t *flag, void(*func)(void *), void *pParam)
	The function uses a specified once flag to ensure that a specified function is called exactly once, the first time the function is called with that value of the flag. This is an extension to the C11 standard conforming chsv_once function. More...

Miscellaneous thread management components
General and auxiliary functions and definitions used by the portable thread managing functions
#define	CHSV_TIME_UTC   1
	Currently the only possible base of time specified by chsv_xtime objects. Corresponds to C11 TIME_UTC.
enum	chsv_thread_return_constants {   chsv_thrd_success , chsv_thrd_timeout , chsv_thrd_busy , chsv_thrd_error ,   chsv_thrd_nomem }
	Possible integer codes that are returned by the thread managing functions. More...
int	chsv_xtime_get (chsv_xtime *xt, int base) noexcept
	Sets the specified chsv_xtime object to hold the current time based on the specified time base. More...
unsigned	chsv_cpu_num () noexcept
	Returns a number of logical processors in the running system. This is a chsvlib extension.

Thread management
Portable implementation of thread management functions.
#define	CHSV_THREAD_STACK_SIZE   (1024 * 1024)
	A size of a stack memory allocated for created threads.
typedef struct Implementation ::chsv_thrd_impl_t	chsv_thrd_t
	A type of a thread identifier.
typedef int(*	chsv_thrd_start_t) (void *)
	A type of a pointer to a user defined thread procedure.
int	chsv_thrd_create (chsv_thrd_t *pThread, chsv_thrd_start_t pStartAddress, void *pArg) noexcept
	Creates a new thread executing the specified function with the specified argument. More...
chsv_thrd_t	chsv_thrd_current (void) noexcept
	Returns an identifier of the calling thread. More...
int	chsv_thrd_detach (chsv_thrd_t thr) noexcept
	Specifies that the specified thread has to be disposed by the host operating system when the thread terminates. More...
int	chsv_thrd_equal (chsv_thrd_t thr0, chsv_thrd_t thr1) noexcept
	Determines whether the two identifies refer to the same thread. More...
void	chsv_thrd_exit (int res) noexcept
	Terminates execution of the calling thread setting its result code to the specified value. More...
int	chsv_thrd_join (chsv_thrd_t thr, int *res) noexcept
	Joins the specified thread to the current one blocking until its completion. More...
void	chsv_thrd_sleep (const chsv_xtime *xt) noexcept
	Suspends an execution of the calling thread until the specified time has passed. More...
void	chsv_thrd_sleepfor (unsigned long cMilliseconds) noexcept
	Suspends an execution of the calling thread for the specified amount of time. More...
void	chsv_thrd_yield (void) noexcept
	Endeavours to permit other threads to run, even if the current thread would ordinarily continue to run. More...

Thread-Specific Storage management functions
Portable implementation of thread-specific storage mechanisms.
#define	CHSV_TSS_DTOR_ITERATIONS   4
	A number of iterations of thread-specific storage destruction loop. See chsv_tss_create.
typedef void(*	chsv_tss_dtor_t) (void *)
	A type of a pointer to a user-defined function used as a destructor for a thread-specific storage.
typedef unsigned long	chsv_tss_t
	A type of an object identifying a thread-specific storage key.
int	chsv_tss_create (chsv_tss_t *pKey, chsv_tss_dtor_t dtor) noexcept
	Creates a thread-specific storage (TSS) key with an optional destructor used during releasing thread specific storages associated with the key. More...
void	chsv_tss_delete (chsv_tss_t key) noexcept
	Deletes the specified key of the thread-specific storage (TSS) and releases any associated resources. More...
void *	chsv_tss_get (chsv_tss_t key) noexcept
	Returns the value for the current thread held in the thread-specific storage (TSS) identified by the specified key. More...
int	chsv_tss_set (chsv_tss_t key, void *pData) noexcept
	Sets the value for the current thread held in the thread-specific storage identified by the specified key. More...

Mutex synchronization primitive
Portable implementation of a mutex synchronization primitive.
enum	chsv_mutex_constants { chsv_mtx_plain = 0 , chsv_mtx_try = 1 , chsv_mtx_timed = 3 , chsv_mtx_recursive = 4 }
	<Flags specifying a type of a mutex More...
typedef struct Implementation ::impl_mutex	chsv_mtx_t
	A type of an object identifying a mutex.
int	chsv_mtx_init (chsv_mtx_t *mtx, int nType) noexcept
	Creates a mutex object with the specified properties. More...
void	chsv_mtx_destroy (chsv_mtx_t *mtx) noexcept
	Closes a mutex and releases any used resources. More...
int	chsv_mtx_lock (chsv_mtx_t *mtx) noexcept
	Blocks the calling thread until the function locks a mutex. More...
int	chsv_mtx_timedlock (chsv_mtx_t *mtx, const chsv_xtime *xt) noexcept
	Endeavours to block until it locks the specified mutex or until the absolute time specified by the chsv_xtime object xt has passed. More...
int	chsv_mtx_timedlockfor (chsv_mtx_t *mtx, unsigned long cMilliseconds) noexcept
	Endeavors to block until it locks the specified mutex or until the time, specified in milliseconds elapses. More...
int	chsv_mtx_trylock (chsv_mtx_t *mtx) noexcept
	Endeavors to lock the specified mutex and returns without blocking even if the mutex ownership cannot be acquired. More...
int	chsv_mtx_unlock (chsv_mtx_t *mtx) noexcept
	Unlocks the specified mutex. More...

Condition variable synchronization primitive
Portable implementation of a condition-variable primitive.
typedef struct Implementation ::impl_cnd	chsv_cnd_t
	A type of an object identifying a condition variable.
int	chsv_cnd_init (chsv_cnd_t *pCnd) noexcept
	Creates a condition variable and writes its descriptor to a specified location. More...
void	chsv_cnd_destroy (chsv_cnd_t *pCnd) noexcept
	Closes a specified condition variable object and releases associated resources. More...
int	chsv_cnd_signal (chsv_cnd_t *pCnd) noexcept
	Unblocks one of the threads that are blocked on the specified condition variable at the time of the call. More...
int	chsv_cnd_broadcast (chsv_cnd_t *pCnd) noexcept
	Unblocks all of the threads that are blocked on the specified condition variable at the time of the call. More...
int	chsv_cnd_wait (chsv_cnd_t *pCnd, chsv_mtx_t *pMtx) noexcept
	Atomically unlocks the specified mutex and endeavours to block until the specified condition variable is signalled by a call to chsv_cnd_signal or to chsv_cnd_broadcast. More...
int	chsv_cnd_timedwait (chsv_cnd_t *pCnd, chsv_mtx_t *pMtx, const chsv_xtime *pXt) noexcept
	Atomically unlocks the specified mutex and endeavours to block until the specified condition variable is signalled by a call to chsv_cnd_signal or to chsv_cnd_broadcast, or until after the time specified by the chsv_xtime object. More...
int	chsv_cnd_timedwaitfor (chsv_cnd_t *pCnd, chsv_mtx_t *pMtx, unsigned long cMilliseconds) noexcept
	Atomically unlocks the specified mutex and endeavours to block until the specified condition variable is signalled by a call to chsv_cnd_signal or to chsv_cnd_broadcast, or until the specified time elapses. More...

Event synchronization primitive
Portable implementation of event synchronization primitive.
typedef struct ::Chusov::ExecutionControl::Implementation ::impl_event	chsv_event_t
	A type of an event identifier. This is a chsvlib extension.
int	chsv_event_init (chsv_event_t *pEvent, bool fManualReset, bool fInitialState) noexcept
	Creates an event object of the specified type. More...
int	chsv_event_wait (chsv_event_t *pEvent) noexcept
	Blocks the calling thread until the specified event is signalled. More...
int	chsv_event_timedwait (chsv_event_t *pEvent, chsv_xtime *xt) noexcept
	Blocks the calling thread until either the specified event is signalled or until after the time specified by the chsv_xtime object. More...
int	chsv_event_timedwaitfor (chsv_event_t *pEvent, unsigned long cMilliseconds) noexcept
	Blocks the calling thread until either the specified event is signalled or until the specified amount of time elapses. More...
int	chsv_event_set (chsv_event_t *pEvent) noexcept
	Sets the specified event to a signalled state. More...
int	chsv_event_reset (chsv_event_t *pEvent) noexcept
	Sets the specified event to a nonsignalled state. More...
int	chsv_event_pulse (chsv_event_t *pEvent) noexcept
	Sets the specified event to the signalled state, releasing appropriate number of threads that are waiting for the signal, and resets the event back to the nonsignalled state. More...
void	chsv_event_destroy (chsv_event_t *pEvent) noexcept
	Releases resources associated with the specified event object. More...

Detailed Description

An interface for the portable implementation of threads as defined in C11 standard supplemented with some extensions.

See Process management and initialization. ("Execution control group") for more detailed information.