Concurrency.

Files
file	global_state.hpp
	An atomic access global variable for quick access to state of the system.
file	subsystem.hpp
	Functions for starting and stopping subsystems.
file	thread.hpp
	Functions and types for accessing operating system threads.
file	unfair_mutex.hpp
	Definition of the unfair_mutex.
file	unfair_recursive_mutex.hpp
	Definition of the unfair_recursive_mutex.

Data Structures
class	hi::v1::unfair_mutex_impl< UseDeadLockDetector >
	An unfair mutex This is a fast implementation of a mutex which does not fairly arbitrate between multiple blocking threads. More...
class	hi::v1::unfair_recursive_mutex
	An unfair recursive-mutex This is a fast implementation of a recursive-mutex which does not fairly arbitrate between multiple blocking threads. More...

Enumerations
enum class	hi::v1::global_state_type : uint64_t {   log_debug = 0x01 , log_info = 0x02 , log_statistics = 0x04 , log_trace = 0x08 ,   log_audit = 0x10 , log_warning = 0x20 , log_error = 0x40 , log_fatal = 0x80 ,   log_mask = log_debug | log_info | log_statistics | log_trace | log_audit | log_warning | log_error | log_fatal , log_level_default = log_audit | log_error | log_fatal , log_level_fatal = log_audit | log_fatal , log_level_error = log_trace | log_error | log_level_fatal ,   log_level_warning = log_warning | log_level_error , log_level_info = log_info | log_statistics | log_level_warning , log_level_debug = log_debug | log_level_info , log_is_running = 0x1'00 ,   time_stamp_utc_is_running = 0x2'00 , system_is_running = 0x1'000000'00 , system_is_shutting_down = 0x2'000000'00 , system_mask = system_is_running | system_is_shutting_down }
	The flag-type used for global state. More...

Functions
bool	hi::v1::is_system_running () noexcept
	Check if the HikoGUI system is running.
bool	hi::v1::is_system_shutting_down () noexcept
	Check if the HikoGUI system is being shut down.
void	hi::v1::set_log_level (global_state_type log_level) noexcept
	Set the logging level.
bool	hi::v1::global_state_disable (global_state_type subsystem, std::memory_order order=std::memory_order::seq_cst) noexcept
	Disable a subsystem.
bool	hi::v1::global_state_enable (global_state_type subsystem, std::memory_order order=std::memory_order::seq_cst) noexcept
	Enable a subsystem.
template<typename T > requires (is_atomic_v<T>)
T::value_type	hi::v1::start_subsystem (T &check_variable, typename T::value_type off_value, typename T::value_type(*init_function)(), void(*deinit_function)())
	Start a sub-system.
bool	hi::v1::start_subsystem (global_state_type state_bit, bool(*init_function)(), void(*deinit_function)())
	Start a sub-system.
template<typename T > requires (is_atomic_v<T>)
T::value_type	hi::v1::start_subsystem_or_terminate (T &check_variable, typename T::value_type off_value, typename T::value_type(*init_function)(), void(*deinit_function)())
	Start a sub-system.
void	hi::v1::stop_subsystem (void(*deinit_function)())
	Stop a sub-system.
void	hi::v1::start_system () noexcept
	Start the system.
void	hi::v1::shutdown_system () noexcept
	Shutdown the system.
thread_id	hi::v1::current_thread_id () noexcept
	Get the current thread id.
void	hi::v1::set_thread_name (std::string_view name) noexcept
	Set the name of the current thread.
std::string	hi::v1::get_thread_name (thread_id id) noexcept
	Get the thread name of a thread id.
std::vector< bool >	hi::v1::process_affinity_mask ()
	Get the current process CPU affinity mask.
std::vector< bool >	hi::v1::set_thread_affinity_mask (std::vector< bool > const &mask)
	Set the current thread CPU affinity mask.
std::vector< bool >	hi::v1::set_thread_affinity (std::size_t cpu_id)
	Set the current thread CPU affinity to a single CPU.
std::size_t	hi::v1::advance_thread_affinity (std::size_t &cpu) noexcept
	Advance thread affinity to the next CPU.
std::size_t	hi::v1::current_cpu_id () noexcept
	Get the current CPU id.

Variables
std::atomic< global_state_type >	hi::v1::global_state = global_state_type::log_level_default
	The global state of the hikogui framework.

Detailed Description

Types and functions for handling multiple threads of execution.

Enumeration Type Documentation

global_state_type

enum class hi::v1::global_state_type : uint64_t

strong

The flag-type used for global state.

Function Documentation

advance_thread_affinity()

std::size_t hi::v1::advance_thread_affinity ( std::size_t & cpu )

inlinenoexcept

Advance thread affinity to the next CPU.

It is possible to detect when advance_thread_affinity() is at the last cpu; in that case the cpu parameter is less than or equal to the return value.

Parameters

[in,out]

cpu

On input The cpu to start a search in the available-cpu list. On output the cpu next on the available-cpu list.

Returns

The cpu that was selected to run on.

current_cpu_id()

std::size_t hi::v1::current_cpu_id ( )

noexcept

Get the current CPU id.

Returns

The current CPU id.

current_thread_id()

thread_id hi::v1::current_thread_id ( )

noexcept

Get the current thread id.

Get the current thread id quickly.

get_thread_name()

std::string hi::v1::get_thread_name ( thread_id id )

inlinenoexcept

Get the thread name of a thread id.

This function is designed to be reasonably fast, so that it can be used in the logger thread.

Note

Can only read names that where set using set_thread_name().

Parameters

id	The thread id.

Returns

Name of the thread set with set_hread_name(). Or the numeric thread-id as string.

global_state_disable()

bool hi::v1::global_state_disable ( global_state_type subsystem, std::memory_order order = std::memory_order::seq_cst )

inlinenoexcept

Disable a subsystem.

Parameters

subsystem	The subsystem to disable.
order	Memory order to use on the global_state variable.

Returns

True if the subsystem was enabled.

global_state_enable()

bool hi::v1::global_state_enable ( global_state_type subsystem, std::memory_order order = std::memory_order::seq_cst )

inlinenoexcept

Enable a subsystem.

Parameters

subsystem	The subsystem to disable.
order	Memory order to use on the global_state variable.

Returns

True if the subsystem was enabled.

is_system_running()

bool hi::v1::is_system_running ( )

inlinenoexcept

Check if the HikoGUI system is running.

The system is running when it is allowed to start subsystems.

is_system_shutting_down()

bool hi::v1::is_system_shutting_down ( )

inlinenoexcept

Check if the HikoGUI system is being shut down.

When the system is being shut down no subsystems are allowed to start.

process_affinity_mask()

std::vector< bool > hi::v1::process_affinity_mask

(

)

Get the current process CPU affinity mask.

Returns

A bit mask on which CPUs the process is allowed to run on. Or zero on failure.

set_log_level()

void hi::v1::set_log_level ( global_state_type log_level )

inlinenoexcept

Set the logging level.

Parameters

log_level

A mask of which log levels should be logged.

set_thread_affinity()

std::vector< bool > hi::v1::set_thread_affinity ( std::size_t cpu_id )

inline

Set the current thread CPU affinity to a single CPU.

The given processor index must be a part of the mask returned from process_affinity_mask().

Parameters

cpu_id

The index of the CPU the thread should run on.

Returns

The previous bit mask. Or zero on failure.

Exceptions

std::os_error

When unable to set the thread affinity to the given index

set_thread_affinity_mask()

std::vector< bool > hi::v1::set_thread_affinity_mask

(

std::vector< bool > const &

mask

)

Set the current thread CPU affinity mask.

The given mask must be a strict subset of the mask returned from process_affinity_mask().

Parameters

mask	A bit mask on which CPUs the thread should run on.

Exceptions

std::os_error

When unable to set the thread affinity to the given index

Returns

The previous bit mask. Or zero on failure.

set_thread_name()

void hi::v1::set_thread_name ( std::string_view name )

noexcept

Set the name of the current thread.

This function will set the name of the thread so that it is available by the operating system and debugger.

Every thread should call this function exactly once.

shutdown_system()

void hi::v1::shutdown_system ( )

inlinenoexcept

Shutdown the system.

This will shutdown all the registered deinit functions.

Any attempts at registering deinit functions after this call will fail and the deinit function will be called directly.

start_subsystem() [1/2]

bool hi::v1::start_subsystem ( global_state_type state_bit, bool(*)() init_function, void(*)() deinit_function )

inline

Start a sub-system.

Initialize a subsystem. The subsystem is not started if the following conditions are true:

• System shutdown is in progress.
• The subsystem is already initialized.

This will also register the deinit function to be called on system shutdown.

Parameters

state_bit	The global state bit to check if the subsystem is already initialized.
init_function	The init function to call to initialize the subsystem
deinit_function	the deinit function to call when shutting down the system.

Returns

return value from the init_function; off_value if the system is shutting down.

start_subsystem() [2/2]

template<typename T >
requires (is_atomic_v<T>)

T::value_type hi::v1::start_subsystem	(	T &	check_variable,
		typename T::value_type	off_value,
		typename T::value_type(*)()	init_function,
		void(*)()	deinit_function )

Start a sub-system.

Initialize a subsystem. The subsystem is not started if the following conditions are true:

• System shutdown is in progress.
• The subsystem is already initialized.

This will also register the deinit function to be called on system shutdown.

Parameters

check_variable	The variable to check before initializing.
off_value	The value of the check_variable when the subsystem is off.
init_function	The init function to call to initialize the subsystem
deinit_function	the deinit function to call when shutting down the system.

Returns

return value from the init_function; off_value if the system is shutting down.

start_subsystem_or_terminate()

template<typename T >
requires (is_atomic_v<T>)

T::value_type hi::v1::start_subsystem_or_terminate	(	T &	check_variable,
		typename T::value_type	off_value,
		typename T::value_type(*)()	init_function,
		void(*)()	deinit_function )

Start a sub-system.

Initialize a subsystem. The subsystem is not started if the following conditions are true:

• System shutdown is in progress.
• The subsystem is already initialized.

If the subsystem was unable to be started because of the previous conditions then this function will std::terminate() the program.

This will also register the deinit function to be called on system shutdown.

Parameters

check_variable	The variable to check before initializing.
off_value	The value of the check_variable when the subsystem is off.
init_function	The init function to call to initialize the subsystem
deinit_function	the deinit function to call when shutting down the system.

Returns

return value from the init_function; off_value if the system is shutting down.

start_system()

void hi::v1::start_system ( )

inlinenoexcept

Start the system.

Subsystems will only initialize once the system is started.

stop_subsystem()

void hi::v1::stop_subsystem ( void(*)() deinit_function )

inline

Stop a sub-system.

De-initialize a subsystem.

This will unregister and call the deinit function.

Parameters

deinit_function

the deinit function to call.

Variable Documentation

global_state

std::atomic<global_state_type> hi::v1::global_state = global_state_type::log_level_default

inline

The global state of the hikogui framework.

This variable contains state in use by multiple systems inside hikogui. This is done so that this variable is likely to be in a cache line and may stay in a register.

In many cases using std::memory_order::relaxed loads are enough of a guarantee to read this variable.