The Thread-class provides methods to execute functions and methods in a separate thread. More...

#include <Thread.hpp>

Inheritance diagram for Arp::System::Commons::Threading::Thread:

Public Types
typedef void(*	ThreadStartFunction) (void *)
	Definition of signature of function to be executed in a separate thread. More...

typedef delegate< void(void *)>	ThreadStartDelegate
	Definition of signature of class method to be executed in a separate thread. More...

Public Member Functions
template<class TInstance , class TFunction >
	Thread (TInstance &instance, TFunction fn, void *pStartParam=nullptr)
	Constructs a Thread instance for a class method. More...

template<class TInstance , class TFunction >
	Thread (const TInstance &instance, TFunction fn, void *pStartParam=nullptr)
	Constructs a Thread instance for a class method. More...

template<class TInstance , class TFunction >
	Thread (TInstance pInstance, TFunction fn, void pStartParam=nullptr)
	Constructs a Thread instance for a class method. More...

template<class TInstance , class TFunction >
	Thread (const TInstance pInstance, TFunction fn, void pStartParam=nullptr)
	Constructs a Thread instance for a class method. More...

	Thread (ThreadStartDelegate &&threadStart, void *pStartParam=nullptr)
	Constructs an Thread instance for a class method with single parameter. More...

	Thread (ThreadStartFunction threadStart, void *pStartParam=nullptr)
	Constructs a Thread instance for a function with single parameter. More...

template<class TInstance , class TFunction >
	Thread (const ThreadSettings &settings, TInstance &instance, TFunction fn, void *pStartParam=nullptr)
	Like Thread(TInstance instance, TFunction fn) but with additional thread parameters. More...

template<class TInstance , class TFunction >
	Thread (const ThreadSettings &settings, const TInstance &instance, TFunction fn, void *pStartParam=nullptr)
	Like Thread(TInstance instance, TFunction fn) but with additional thread parameters. More...

template<class TInstance , class TFunction >
	Thread (const ThreadSettings &settings, TInstance pInstance, TFunction fn, void pStartParam=nullptr)
	Like Thread(TInstance instance, TFunction fn) but with additional thread parameters. More...

template<class TInstance , class TFunction >
	Thread (const ThreadSettings &settings, const TInstance pInstance, TFunction fn, void pStartParam=nullptr)
	Like Thread(TInstance instance, TFunction fn) but with additional thread parameters. More...

	Thread (ThreadSettings &settings, ThreadStartDelegate &&threadStart, void *pStartParam=nullptr)
	Like Thread(ThreadStartDelegate&& threadStart, void* pStartParam = nullptr) but with additional thread parameters. More...

	Thread (ThreadSettings &settings, ThreadStartFunction threadStart, void *pStartParam=nullptr)
	Like Thread(ThreadStartFunction threadStart, void* pStartParam = nullptr) but with additional thread parameters. More...

	Thread (const ThreadSettings &settings, ThreadStartDelegate &&threadStart, void *pStartParam=nullptr)
	Like Thread(ThreadStartDelegate&& threadStart, void* pStartParam = nullptr) but with additional thread parameters. More...

	Thread (const ThreadSettings &settings, ThreadStartFunction threadStart, void *pStartParam=nullptr)
	Like Thread(ThreadStartFunction threadStart, void* pStartParam = nullptr) but with additional thread parameters. More...

	~Thread (void)
	Destructs this instance and frees all resources. More...

bool	IsRunning (void) const
	Determines if this thread is in running state. More...

void	SetCpuAffinity (size_t mask)
	Pins the thread to a specific CPUs inside a multiprocessor system. More...

size_t	GetCpuAffinity (void) const
	Returns the CPU affinity mask. More...

void	SetPriority (size_t value)
	Assigns a new priority to the thread. More...

size_t	GetPriority (void) const
	Returns the current priority of the thread. More...

void	SetStackSize (size_t value)
	Sets a new stack size for the thread. More...

size_t	GetStackSize (void) const
	Returns the current stack size of the thread. Returns Current size of stack in bytes.

void	SetName (const String &value)
	Sets a new name to the thread. More...

const String &	GetName (void) const
	Returns the current name of the thread. More...

ThreadState	GetState () const
	Returns the current state of the thread. More...

bool	IsJoinable (void)
	Checks if this thread is joinable. More...

void	Start (void)
	Starts the execution of the thread. More...

void	Join (void)
	Waits for the thread to terminate. More...

void	Interrupt (void)
	Interrupts the currents execution. More...

void	Terminate (void)
	Aborts the execution of this thread. More...

Static Public Member Functions
static void	Sleep (size_t milliseconds)
	Suspends the execution of the calling thread. More...

static size_t	GetCurrentThreadId (void)
	Returns the id of the calling thread. More...

static Thread *	GetCurrentThread (void)
	Returns the current thread of the calling context. More...

static void	SetAsynchronousCancelability (bool enable)
	Activates/Deactivates the asynchronous cancelability of the calling thread. More...

Static Public Attributes
static const std::size_t	CpuAffinityAll
	Use this constant to express an affinity of the thread to all available CPUs aka. cores. More...

Friends
class	AutoResetEvent

class	AutoResetEvent2

Detailed Description

The Thread-class provides methods to execute functions and methods in a separate thread.

An instance of this class is used to manage one single thread of execution. The function or method to be executed in a separate thread must thereby be provided during object instance creation. The execution is not started until Arp::System::Commons::Threading::Thread::Start is called on the newly created instance.

Consider the following class

struct ThreadWorker
{
public: // Construction
    ThreadWorker(void) : RunCount(0), Stop(false) {}
 
public: // Operations
    void RunSingle(void) { ++this->RunCount; }
    void Run(void*) { while (!this->Stop) RunSingle(); }
    static void RunStatic(void* pParam) { ((ThreadWorker*)pParam)->Run(nullptr); }
 
public: // Properties
    int RunCount;
    bool Stop;
};

If the class-method ThreadWorker::Run has to be executed in an extra thread of execution this can be done with the following code.

ThreadWorder worker;
Thread thread(&worker, &ThreadWorker::Run);
thread.Start();

Several other constructors exists to support different use-cases of threaded execution. For example, if the method ThreadWorker::Run also needs an additional parameter to work properly a corresponding thread object can be created using the following lines of code.

const char *pMessage = "message";
ThreadWorker worker;
Thread thread(make_delegate(&worker, &ThreadWorker::Run), (void*) pMessage);

See api documentation for more information how to create thread object instances.

Member Typedef Documentation

◆ ThreadStartDelegate

typedef delegate<void(void*)> Arp::System::Commons::Threading::Thread::ThreadStartDelegate

Definition of signature of class method to be executed in a separate thread.

◆ ThreadStartFunction

typedef void(* Arp::System::Commons::Threading::Thread::ThreadStartFunction) (void *)

Definition of signature of function to be executed in a separate thread.

Constructor & Destructor Documentation

◆ Thread() [1/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	TInstance &	instance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Constructs a Thread instance for a class method.

Parameters

instance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Pointer to optional parameter passed to function threadStart.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [2/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const TInstance &	instance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Constructs a Thread instance for a class method.

Parameters

instance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Pointer to optional parameter passed to function threadStart.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [3/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	TInstance *	pInstance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Constructs a Thread instance for a class method.

Parameters

pInstance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Pointer to optional parameter passed to function threadStart.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [4/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const TInstance *	pInstance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Constructs a Thread instance for a class method.

Parameters

pInstance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Pointer to optional parameter passed to function threadStart.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [5/14]

Arp::System::Commons::Threading::Thread::Thread	(	ThreadStartDelegate &&	threadStart,
		void *	pStartParam = `nullptr`
	)

inlineexplicit

Constructs an Thread instance for a class method with single parameter.

Parameters

threadStart	A delegate of a class method and a corresponding instance created using Arp::make_delegate
pStartParam	Pointer to optional parameter passed to class method referenced in the constructed delegate.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [6/14]

Arp::System::Commons::Threading::Thread::Thread	(	ThreadStartFunction	threadStart,
		void *	pStartParam = `nullptr`
	)

inline

Constructs a Thread instance for a function with single parameter.

Example:

Thread thread(&ThreadWorker::RunStatic, nullptr);

Parameters

threadStart	Function to be executed.
pStartParam	Pointer to optional parameter passed to function threadStart.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [7/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		TInstance &	instance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(TInstance instance, TFunction fn) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
instance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Optional parameter passed to function `fn` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [8/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		const TInstance &	instance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(TInstance instance, TFunction fn) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
instance	Instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Optional parameter passed to function `fn` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [9/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		TInstance *	pInstance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(TInstance instance, TFunction fn) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
pInstance	Pointer to instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Optional parameter passed to function `fn` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [10/14]

template<class TInstance , class TFunction >

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		const TInstance *	pInstance,
		TFunction	fn,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(TInstance instance, TFunction fn) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
pInstance	Pointer to instance of object whichs method should be executed in separate thread.
fn	Pointer to method that should be executed in separate thread.
pStartParam	Optional parameter passed to function `fn` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [11/14]

Arp::System::Commons::Threading::Thread::Thread	(	ThreadSettings &	settings,
		ThreadStartDelegate &&	threadStart,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(ThreadStartDelegate&& threadStart, void* pStartParam = nullptr) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
threadStart	Delegate of class instance and method to be executed in separate thread.
pStartParam	Optional parameter passed to methode in delegate `threadStart` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [12/14]

Arp::System::Commons::Threading::Thread::Thread	(	ThreadSettings &	settings,
		ThreadStartFunction	threadStart,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(ThreadStartFunction threadStart, void* pStartParam = nullptr) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
threadStart	Function to be executed in separate thread.
pStartParam	Optional parameter passed to function `threadStart` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [13/14]

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		ThreadStartDelegate &&	threadStart,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(ThreadStartDelegate&& threadStart, void* pStartParam = nullptr) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
threadStart	Delegate of class instance and method to be executed in separate thread.
pStartParam	Optional parameter passed to methode in delegate `threadStart` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ Thread() [14/14]

Arp::System::Commons::Threading::Thread::Thread	(	const ThreadSettings &	settings,
		ThreadStartFunction	threadStart,
		void *	pStartParam = `nullptr`
	)

inline

Like Thread(ThreadStartFunction threadStart, void* pStartParam = nullptr) but with additional thread parameters.

Parameters

settings	Reference to custom thread parameters.
threadStart	Function to be executed in separate thread.
pStartParam	Optional parameter passed to function `threadStart` during invocation.

Exceptions

Arp::System::Commons::InvalidOperationException if the thread could not be created.

◆ ~Thread()

Arp::System::Commons::Threading::Thread::~Thread ( void )

Destructs this instance and frees all resources.

This will not stop the underlying thread from running. To prevent the creation of zombie threads Terminate must be called before the object destructor is invoked.

Member Function Documentation

◆ GetCpuAffinity()

size_t Arp::System::Commons::Threading::Thread::GetCpuAffinity ( void ) const

Returns the CPU affinity mask.

See also: SetCpuAffinity

Returns: The CPU affinity mask for the thread.

◆ GetCurrentThread()

Thread * Arp::System::Commons::Threading::Thread::GetCurrentThread ( void )

inlinestatic

Returns the current thread of the calling context.

Returns: The calling thread or nullptr if the calling thread is not a Arp thread (e.g. main thread).

◆ GetCurrentThreadId()

static size_t Arp::System::Commons::Threading::Thread::GetCurrentThreadId ( void )

static

Returns the id of the calling thread.

Returns: The id of the calling thread.

◆ GetName()

const String& Arp::System::Commons::Threading::Thread::GetName ( void ) const

Returns the current name of the thread.

Returns: Current name of the thread.</returns.>

◆ GetPriority()

size_t Arp::System::Commons::Threading::Thread::GetPriority ( void ) const

Returns the current priority of the thread.

Returns: The current thread priority.

◆ GetState()

ThreadState Arp::System::Commons::Threading::Thread::GetState ( void ) const

inline

Returns the current state of the thread.

Returns: Current thread state.

◆ Interrupt()

void Arp::System::Commons::Threading::Thread::Interrupt ( void )

inline

Interrupts the currents execution.

If this thread is currently waiting on an event to be signaled, the waiting is interrupted and an exception is thrown inside the thread signalling the interruption of the current execution.

◆ IsJoinable()

bool Arp::System::Commons::Threading::Thread::IsJoinable ( void )

Checks if this thread is joinable.

A thread is only joinable if Start was already invoked succesfully and if no other thread has already called Join for this object.

◆ IsRunning()

bool Arp::System::Commons::Threading::Thread::IsRunning ( void ) const

inline

Determines if this thread is in running state.

◆ Join()

void Arp::System::Commons::Threading::Thread::Join ( void )

Waits for the thread to terminate.

The thread must be joinable for this method to work properly. See #Joinable for more information.

◆ SetAsynchronousCancelability()

static void Arp::System::Commons::Threading::Thread::SetAsynchronousCancelability ( bool enable )

static

Activates/Deactivates the asynchronous cancelability of the calling thread.

The default state for all new threads is that a cancellation request send by Arp::System::Commons::Threading::Thread::Terminate is deferred until the thread reaches the next cancellation point. A cancellation point is a call to function like, for example, Arp::System::Commons::Net::Socket::Accept. If a thread activates asynchronous cancelability then the thread can be canceled at any time using Arp::System::Commons::Threading::Thread::Terminate.

Parameters

enable Set to true to activate asynchronous cancelability, otherwise set to false.

◆ SetCpuAffinity()

void Arp::System::Commons::Threading::Thread::SetCpuAffinity ( size_t mask )

Pins the thread to a specific CPUs inside a multiprocessor system.

The assigned parameter is interpreted as a bit-mask to determine which CPUs are allowed to run the specific thread. So, for example, if the thread should run on the first and second CPU set mask = 3.

thread.SetCpuAffinity(3);
<code/>
By default a thread is not pinned to any CPU. If an altered affinity should be reset to this default
value call SetCpuAffinity with a parameter value of zero.
<code>
thread.SetCpuAffinity(0);
<code/>
If the thread is already running on a different CPU it is migrated to the CPU determined
by the assigned id.
</remarks>
<param name="mask">A mask determine which the CPU is allowed to execute the thread.</param>
<exception cref="Arp::Exception">with additional error information.</exception> 

◆ SetName()

void Arp::System::Commons::Threading::Thread::SetName ( const String & value )

Sets a new name to the thread.

The maximal length of the new name depends on the operating system. If the assigned char sequence is too long it is automatically truncated to this maximal allowed length.

Parameters

value New name of the thread.

Exceptions

Arp::Exception with additional error information.

◆ SetPriority()

void Arp::System::Commons::Threading::Thread::SetPriority ( size_t value )

Assigns a new priority to the thread.

Parameters

value The new priority value.

Exceptions

Arp::Exception with additional error information.

◆ SetStackSize()

void Arp::System::Commons::Threading::Thread::SetStackSize ( size_t value )

Sets a new stack size for the thread.

The stack size can only be set if the thread is not started , i.e. Start was not called yet.

Parameters

value Size in bytes for requested stack.

Exceptions

Arp::Exception with additional error information.

<deprecated> This method throws an exception now and will be removed in the future. The reason therefore is an modification of the thread startup behavior. The stack size can be set with the thread settings at the constructor. </deprecated>

◆ Sleep()

static void Arp::System::Commons::Threading::Thread::Sleep ( size_t milliseconds )

static

Suspends the execution of the calling thread.

Parameters

milliseconds Amount of milliseconds the execution of the calling thread is suspended.

◆ Start()

void Arp::System::Commons::Threading::Thread::Start ( void )

Starts the execution of the thread.

Exceptions

Arp::Exception with additional error information.

◆ Terminate()

void Arp::System::Commons::Threading::Thread::Terminate ( void )

Aborts the execution of this thread.

Member Data Documentation

◆ CpuAffinityAll

const std::size_t Arp::System::Commons::Threading::Thread::CpuAffinityAll

static

Use this constant to express an affinity of the thread to all available CPUs aka. cores.

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

Arp/System/Commons/Threading/Thread.hpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ ThreadStartDelegate

◆ ThreadStartFunction

Constructor & Destructor Documentation

◆ Thread() [1/14]

◆ Thread() [2/14]

◆ Thread() [3/14]

◆ Thread() [4/14]

◆ Thread() [5/14]

◆ Thread() [6/14]

◆ Thread() [7/14]

◆ Thread() [8/14]

◆ Thread() [9/14]

◆ Thread() [10/14]

◆ Thread() [11/14]

◆ Thread() [12/14]

◆ Thread() [13/14]

◆ Thread() [14/14]

◆ ~Thread()

Member Function Documentation

◆ GetCpuAffinity()

◆ GetCurrentThread()

◆ GetCurrentThreadId()

◆ GetName()

◆ GetPriority()

◆ GetState()

◆ Interrupt()

◆ IsJoinable()

◆ IsRunning()

◆ Join()

◆ SetAsynchronousCancelability()

◆ SetCpuAffinity()

◆ SetName()

◆ SetPriority()

◆ SetStackSize()

◆ Sleep()

◆ Start()

◆ Terminate()

Member Data Documentation

◆ CpuAffinityAll