Wrapper for a Windows thread. More...

#include <thread.h>

Inheritance diagram for mlib::thread:

Public Types
enum class	state { ready , starting , running , ending , finished }
	Execution state of a thread. More...

Public Member Functions
	thread (std::function< unsigned int()> func)
	Make a thread with the given function body.

virtual	~thread ()
	Destructor.

virtual void	start ()
	Begin execution of a newly created thread.

void	fork ()
	Another name for start () function.

void	join ()
	Another name for wait () function.

DWORD	wait (DWORD time_limit=INFINITE)
	Wait for thread to finish execution.

DWORD	wait_alertable (DWORD time_limit=INFINITE)
	Wait for thread to finish or an APC, or IO completion routine to occur.

DWORD	wait_msg (DWORD time_limit=INFINITE, DWORD mask=QS_ALLINPUT)
	Wait for thread to finish or a message to be queued.

void	rethrow_exception () const
	Rethrow an exception usually in the context of another thread.

DWORD	id () const
	Return thread's ID.

UINT	result () const
	Return thread's exit code.

bool	is_running () const
	Return true if thread is running.

state	get_state () const
	Return thread's execution status.

int	priority () const
	Return thread's priority.

void	priority (int pri)
	Set thread's priority.

virtual void	name (const std::string &nam)
	Set thread's name.

virtual const std::string &	name () const
	Return object's name.

virtual void	name (const std::string &nam)
	Change object's name.

Public Member Functions inherited from mlib::syncbase
	syncbase ()
	Default constructor.

	syncbase (const syncbase &e)
	Copy constructor.

	syncbase (syncbase &&e) noexcept
	Move constructor.

virtual	~syncbase ()
	Destructor.

syncbase &	operator= (const syncbase &rhs)
	Assignment operator.

syncbase &	operator= (syncbase &&rhs) noexcept
	Move assignment operator.

int	operator== (const syncbase &rhs) const
	Equality operator.

virtual void	wait ()
	Wait for object to become signaled.

virtual DWORD	wait (std::chrono::milliseconds limit)
	Wait a number of milliseconds for the object to become signaled.

	operator bool ()
	Check if object is signaled.

virtual bool	is_signaled ()
	Try to wait on the object.

HANDLE	handle () const
	Return OS handle of this object.

Protected Member Functions
	thread (const std::string &name=std::string(), DWORD stack_size=0, PSECURITY_DESCRIPTOR sd=NULL, bool inherit=false)
	Protected constructor for use of thread-derived objects.

virtual bool	init ()
	Initialization function called before run.

virtual void	term ()
	Finalization function called after run.

virtual void	run ()
	Default run function.

Protected Member Functions inherited from mlib::syncbase
	syncbase (const std::string &name)
	Protected constructor.

void	set_handle (HANDLE h)
	Change object's handle. Closes the previous one.

Protected Attributes
unsigned int	exitcode
	exit code

Detailed Description

Wrapper for a Windows thread.

Thread objects can be created by providing a function that will be run in a separate execution thread or by deriving an new object that reimplements the thread::run() function.

Either way, thread objects are created in a "suspended animation" state. To start them use the thread::start() function.

When combining objects and multi-threading it is useful to define what member functions are foreign (i.e. can be called by another execution thread) and what functions are owned (i.e. can be called only by the same execution thread). As a general rule, "owned" functions should be made private or protected. The object's constructors and destructor are inherently foreign while the run() function is inherently owned.

Exceptions thrown while executing a thread that are not caught by user handlers are caught by a try...catch block that encompasses the thread::run() function and re-thrown by the thread::wait() function (considered a foreign function).

Member Enumeration Documentation

◆ state

enum class mlib::thread::state

strong

Execution state of a thread.

Enumerator
ready	not started
starting	in the process of starting up
running	is running
ending	in the process of finishing
finished	execution finished

Constructor & Destructor Documentation

◆ thread() [1/2]

mlib::thread::thread ( std::function< unsigned int()> func )

Make a thread with the given function body.

Uses a polymorphic function wrapper that can be a lambda expression, a bind expression or any other type of function object as a run function of the newly created thread.

When the thread is started (using the start() function), the run function is called.

The return value of the run function becomes the exit code of the thread.

◆ ~thread()

mlib::thread::~thread ( )

virtual

Destructor.

Normally the thread should have ended earlier ( !isRunning ) Anyhow we will use now brute force (TerminateThread) to end it.

◆ thread() [2/2]

mlib::thread::thread	(	const std::string &	name = `std::string ()`,
		DWORD	stack_size = `0`,
		PSECURITY_DESCRIPTOR	sd = `NULL`,
		bool	inherit = `false`
	)

protected

Protected constructor for use of thread-derived objects.

Parameters

name	thread name (mostly for debugging purposes)
stack_size	thread stack size or 0 for default size
sd	pointer to a security descriptor or NULL
inherit	if true, thread handle is inherited by child processes

Member Function Documentation

◆ init()

bool mlib::thread::init ( )

inlineprotectedvirtual

Initialization function called before run.

Reimplemented in mlib::tcpserver.

◆ name() [1/3]

virtual const std::string & mlib::syncbase::name ( ) const

inlinevirtual

Return object's name.

Reimplemented from mlib::syncbase.

◆ name() [2/3]

void mlib::syncbase::name ( const std::string & nam )

inlinevirtual

Change object's name.

Reimplemented from mlib::syncbase.

◆ name() [3/3]

void mlib::thread::name ( const std::string & nam )

virtual

Set thread's name.

Reimplemented from mlib::syncbase.

◆ run()

void mlib::thread::run ( )

protectedvirtual

Default run function.

Calls user supplied function if there is one.

Reimplemented in mlib::http_connection, and mlib::tcpserver.

◆ term()

void mlib::thread::term ( )

inlineprotectedvirtual

Finalization function called after run.

Reimplemented in mlib::http_connection.

◆ wait()

DWORD mlib::thread::wait ( DWORD time_limit = INFINITE )

virtual

Wait for thread to finish execution.

Parameters

time_limit time-out interval, in milliseconds

Returns: WAIT_OBJECT_0 thread finished; WAIT_TIMEOUT time-out interval expired

If thread has finished and an exception occurred during thread execution, it is re-thrown now.

Reimplemented from mlib::syncbase.

◆ wait_alertable()

DWORD mlib::thread::wait_alertable ( DWORD time_limit = INFINITE )

virtual

Wait for thread to finish or an APC, or IO completion routine to occur.

Parameters

time_limit time-out interval, in milliseconds

Returns: WAIT_OBJECT_0 thread finished; WAIT_TIMEOUT time-out interval expired; WAIT_IO_COMPLETION wait ended by one or more APC-es queued.

If thread has finished and an exception occurred during thread execution, it is re-thrown now.

Reimplemented from mlib::syncbase.

◆ wait_msg()

DWORD mlib::thread::wait_msg	(	DWORD	time_limit = `INFINITE`,
		DWORD	mask = `QS_ALLINPUT`
	)

virtual

Wait for thread to finish or a message to be queued.

Parameters

time_limit	time-out interval, in milliseconds
mask	input message types

Returns: WAIT_OBJECT_0 thread finished; WAIT_TIMEOUT time-out interval expired; WAIT_OBJECT_0+1 Input message received.

If an exception occurred during thread execution, it is re-thrown now.

Reimplemented from mlib::syncbase.

The documentation for this class was generated from the following files:

include/mlib/thread.h
src/thread.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ state

Constructor & Destructor Documentation

◆ thread() [1/2]

◆ ~thread()

◆ thread() [2/2]

Member Function Documentation

◆ init()

◆ name() [1/3]

◆ name() [2/3]

◆ name() [3/3]

◆ run()

◆ term()

◆ wait()

◆ wait_alertable()

◆ wait_msg()