Thread System Initialization, Destruction, and Information

Enumerations
enum	M_thread_model_t {   M_THREAD_MODEL_INVALID = -1 ,   M_THREAD_MODEL_NATIVE = 0 ,   M_THREAD_MODEL_COOP }

Functions
M_bool	M_thread_init (M_thread_model_t model)
M_bool	M_thread_active_model (M_thread_model_t *model, const char **model_name)
M_bool	M_thread_destructor_insert (void(*destructor)(void))
void	M_thread_destructor_remove (void(*destructor)(void))
void	M_library_cleanup (void)
void	M_library_cleanup_register (void(*cleanup_cb)(void *arg), void *arg)
size_t	M_thread_count (void)
size_t	M_thread_num_cpu_cores (void)

Detailed Description

Thread System Initialization, Destruction, and Information

Enumeration Type Documentation

M_thread_model_t

enum M_thread_model_t

Thread model.

Enumerator
M_THREAD_MODEL_INVALID	Invalid/no model.
M_THREAD_MODEL_NATIVE	System's native thread model.
M_THREAD_MODEL_COOP	Cooperative threads.

Function Documentation

M_thread_init()

M_bool M_thread_init

(

M_thread_model_t

model

)

Initialize the thread model (system).

This should be called before any other thread function is used. This will initialize the specified threading system. If this is not called before a thread function is used then the native threading model will be automatically initialized.

Only one thread model can be use at any given time.

Parameters

[in]

model

The thread model that should be used for threading.

Returns

M_TRUE if the model was successfully initialized. Otherwise M_FALSE. This can fail if called after a model has already been initialized.

M_thread_active_model()

M_bool M_thread_active_model	(	M_thread_model_t *	model,
		const char **	model_name
	)

Get the active thread model.

Parameters

[out]	model	The active model.
[out]	model_name	The textual name of the model. This will provide descriptive information such as what is the underlying native threading model.

Returns

M_TRUE if a thread model is active otherwise M_FALSE.

M_thread_destructor_insert()

M_bool M_thread_destructor_insert

(

void(*)(void)

destructor

)

Adds a function to be called each time a thread finishes.

Some libraries (OpenSSL in particular) keep their own per thread memory store. This allows registering functions to be called to handle this situation.

OpenSSL keeps a per-thread error state which must be cleaned up at thread destruction otherwise it will leak memory like crazy. Wrap ERR_remove_state(0); in a function that doesn't take any arugments, then register the function and this problem is solved.

Registered functions will be called in the order they were added.

Parameters

[in]

destructor

The function to register.

Returns

M_TRUE if the function was added. Otherwise M_FALSE. This can fail if the function was already registered. A function can only be registered once.

M_thread_destructor_remove()

void M_thread_destructor_remove

(

void(*)(void)

destructor

)

Remove a function from the list of function to be called each time a thread finished.

Parameters

[in]

destructor

The function to remove.

M_library_cleanup()

void M_library_cleanup

(

void

)

Thread-safe library cleanup.

Cleans up any initialized static/global members by the library. Useful to be called at the end of program execution to free memory or other resources, especially if running under a leak checker such as Valgrind.

M_library_cleanup_register()

void M_library_cleanup_register	(	void(*)(void *arg)	cleanup_cb,
		void *	arg
	)

Registers a callback to be called during M_library_cleanup().

There is no way to 'unregister' a callback, so it must be ensured the callback will remain valid until the end of program execution.

Parameters

[in]	cleanup_cb	Callback to call for cleanup
[in]	arg	Optional argument to be passed to the callback.

M_thread_count()

size_t M_thread_count

(

void

)

Get the number of actively running threads. This count includes the main process thread.

This count does not include the threads that have finished but are still joinable.

Returns

Thread count.

M_thread_num_cpu_cores()

size_t M_thread_num_cpu_cores

(

void

)

Retrieve the count of CPU cores that are online and usable. When using cooperative threading, only 1 cpu core is usable.

Returns

count of cores or 0 on failure.