Description:

This class provides a limited (minimal) abstraction of C++ type std::thread. As elaborated in the module's documentation, this class is not considered full featured but - as of today- is meant for simple use cases only.

For general information of multi-threading support provided by ALib, please consult the ALib Module Threads - Programmer's Manual.

Friends

function Bootstrap function Shutdown

See also: For this class, a pretty printer for the GNU debugger is provided.

Definition at line 102 of file thread.hpp.

#include <thread.hpp>

Inheritance diagram for Thread:

[legend]

Collaboration diagram for Thread:

[legend]

Public Type Index:
enum class	State { Unstarted = 0 , Started = 1 , Running = 2 , Done = 3 , Terminated = 4 }

Public Static Method Index:
static ALIB_API Thread *	Get (std::thread::id nativeID)

static Thread *	GetCurrent ()

static ALIB_API Thread *	GetMain ()

static void	Sleep (const Ticks::Duration &duration)

static void	Sleep (const Ticks::Duration::TDuration &duration)

static void	SleepMicros (int64_t microseconds)

static void	SleepMillis (int milliseconds)

static void	SleepNanos (int64_t nanoseconds)

static void	SleepUntil (const Ticks &time)

static void	YieldToSystem ()

Public Method Index:
ALIB_API	Thread (const String &pName=EMPTY_STRING)

	Thread (const Thread &)=delete
	Deleted copy constructor.

ALIB_API	Thread (Runnable *target, const String &pName=EMPTY_STRING)

virtual ALIB_API	~Thread () override

ThreadID	GetID () const

virtual const CString	GetName () const

std::thread::id	GetNativeID () const

State	GetState ()

bool	IsAlive ()

virtual ALIB_API void	Join ()

virtual void	Run () override

virtual void	SetName (const String &newName)

virtual ALIB_API void	Start ()

Public Method Index: inherited from Runnable
virtual	~Runnable ()
	Virtual destructor.

Protected Field Index:
std::thread *	c11Thread =nullptr
	The internal C++ thread object.

ThreadID	id =0
	The id of the thread.

AString	name
	The name of the thread.

std::thread::id	nativeID
	The internal C++ thread id.

Runnable *	runnable =nullptr
	The runnable to execute.

State	state = State::Unstarted
	Internal flag to indicate if the thread is alive.

Enumeration Details:

◆ State

enum class State

strong

States that follow lifecycle of the thread. The states are accessible with method GetState.

Enumerator
Unstarted	Not started and no call to Start was performed, yet. This is the state after construction of an instance.
Started	Method Start was invoked but not running, yet.
Running	The thread's Run method is currently processed.
Done	The run method is processed, and the thread is ready to be terminated.
Terminated	The thread is terminated.

Definition at line 113 of file thread.hpp.

Field Details:

◆ c11Thread

std::thread* c11Thread =nullptr

protected

The internal C++ thread object.

Definition at line 129 of file thread.hpp.

◆ id

ThreadID id =0

protected

The id of the thread.

Definition at line 138 of file thread.hpp.

◆ name

AString name

protected

The name of the thread.

Definition at line 141 of file thread.hpp.

◆ nativeID

std::thread::id nativeID

protected

The internal C++ thread id.

Definition at line 132 of file thread.hpp.

◆ runnable

Runnable* runnable =nullptr

protected

The runnable to execute.

Definition at line 135 of file thread.hpp.

◆ state

State state = State::Unstarted

protected

Internal flag to indicate if the thread is alive.

Definition at line 144 of file thread.hpp.

Constructor(s) / Destructor Details:

◆ Thread() [1/2]

ALIB_API Thread ( const String & pName = EMPTY_STRING )

inline

Constructor without a parameter specifying a Runnable. Such thread will not execute any code unless a specialized class is derived that overrides virtual method Run.

Parameters

pName (Optional) The designated name of the thread. If the name provided is, empty the name of the thread will be set to match a string representation of the thread id.

Definition at line 160 of file thread.hpp.

◆ Thread() [2/2]

Thread	(	Runnable *	target,
		const String &	pName = EMPTY_STRING )

Constructor with provision of a Runnable 'target'. The Run method of 'target' will be executed upon thread start, unless this class is specialized an its own Run() method is overwritten.

Parameters

target	The target to execute when the thread runs.
pName	(Optional) The designated name of the thread. If the name provided is, empty the name of the thread will be set to match a string representation of the thread id.

Definition at line 193 of file thread.cpp.

Here is the call graph for this function:

◆ ~Thread()

~Thread ( )

overridevirtual

Before destruction, Join has to be called. The destructor blocks if the thread was started and is still running. Blocking lasts until the thread's end of execution.

Definition at line 206 of file thread.cpp.

Here is the call graph for this function:

Method Details:

◆ Get()

Thread * Get ( std::thread::id nativeID )

static

Static method that returns an object representing the thread identified by the given system ID nativeID. nullptr is returned only if:

parameter nativeID is nulled, or
during bootstrapping of ALib, which multithreaded applications have to perform before starting threads, nullptr might be returned as well.

In any other situations, either,

nativeID is received from a thread that was started using this class Thread, then a pointer to that instance is returned, or
the thread was started without the use of ALib, then an instance of this class is created (once) and registered.

Parameters

nativeID The C++ Standard Libraray identifier.

Returns: A pointer to the instance associated with the native thread ID.

Definition at line 321 of file thread.cpp.

Here is the call graph for this function:

◆ GetCurrent()

static Thread * GetCurrent ( )

inlinestatic

Static method that returns an object representing the thread that invoked this call.

Returns: A pointer to the current thread.

Definition at line 283 of file thread.hpp.

Here is the call graph for this function:

◆ GetID()

ThreadID GetID ( ) const

inline

Returns the id of this Thread. Systems threads have IDs below 0, ALIB generated threads have positive IDs and start with 1.

Returns: The ALib id of the thread.

Definition at line 207 of file thread.hpp.

◆ GetMain()

Thread * GetMain ( )

static

Static method that returns the thread that initialized the library. Such thread this is supposedly the "main" thread as bootstrapping usually is performed by the process before any other threads are started.

Returns: A pointer to the main thread.

Definition at line 320 of file thread.cpp.

◆ GetName()

virtual const CString GetName ( ) const

inlinevirtual

Returns the name of the thread. An ALib thread can have any name that is given to it and such name can be changed any time. In fact, names are for debugging and logging purposes only.

Returns: Returns the name of the thread.

Reimplemented in DedicatedWorker.

Definition at line 225 of file thread.hpp.

◆ GetNativeID()

std::thread::id GetNativeID ( ) const

inline

Returns the id of this Thread. Systems threads have IDs below 0, ALIB generated threads have positive IDs and start with 1.

Returns: The ALib id of the thread.

Definition at line 215 of file thread.hpp.

◆ GetState()

State GetState ( )

inline

Returns the state of the thread. The states are given in enumeration State and during the lifecycle of the thread, the state transitions from State::Unstarted to State::Terminated.

Note: For system threads (the thread that executed function main thread and those not created using ALib thread features) State::Running is returned. For those, it can't be determined if the thread is stared, alive or not.

Returns: The current state within the thread's lifecycle.

Definition at line 246 of file thread.hpp.

◆ IsAlive()

bool IsAlive ( )

inline

A shortcut to GetState().first == State::Started || GetState().first == State::Running.

Returns: true if the current state of the thread is State::Running.

Definition at line 255 of file thread.hpp.

◆ Join()

void Join ( )

virtual

Terminates a thread using std::join(). When this method is called, the thread should be in state State::Done, which is the case after method Run has exited. Otherwise, an ALib warning is raised.

Definition at line 220 of file thread.cpp.

Here is the call graph for this function:

◆ Run()

virtual void Run ( )

inlineoverridevirtual

If we have a runnable, its run() method is executed. Otherwise nothing is done.

Hence, to have the thread execute something, either a Runnable has to be provided or a derived version of this class replaces this method.

Implements Runnable.

Reimplemented in DedicatedWorker, and Trigger.

Definition at line 195 of file thread.hpp.

Here is the call graph for this function:

◆ SetName()

virtual void SetName ( const String & newName )

inlinevirtual

Sets the name of the thread. An ALib thread can have any name that is given to it and such name can be changed any time. Thread names are meant for debugging and logging purposes only.

Parameters

newName The name that the Thread should hold.

Definition at line 233 of file thread.hpp.

Here is the call graph for this function:

◆ Sleep() [1/2]

static void Sleep ( const Ticks::Duration & duration )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants SleepUntil, SleepMicros, SleepMillis and SleepNanos.

Parameters

duration Sleep duration.

Definition at line 344 of file thread.hpp.

◆ Sleep() [2/2]

static void Sleep ( const Ticks::Duration::TDuration & duration )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants SleepUntil, SleepMicros, SleepMillis and SleepNanos.

Parameters

duration Sleep duration.

Definition at line 350 of file thread.hpp.

◆ SleepMicros()

static void SleepMicros ( int64_t microseconds )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants SleepMillis, SleepNanos, Sleep and SleepUntil

Parameters

microseconds Sleep time in microseconds.

Definition at line 332 of file thread.hpp.

◆ SleepMillis()

static void SleepMillis ( int milliseconds )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants SleepMicros, SleepNanos, Sleep and SleepUntil

Parameters

milliseconds Sleep time in milliseconds.

Definition at line 325 of file thread.hpp.

◆ SleepNanos()

static void SleepNanos ( int64_t nanoseconds )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants SleepMicros, SleepMillis, Sleep and SleepUntil

Parameters

nanoseconds Sleep time in nanoseconds.

Definition at line 338 of file thread.hpp.

◆ SleepUntil()

static void SleepUntil ( const Ticks & time )

inlinestatic

Suspends the current thread by calling std::this_thread::sleep_for.

See also: Variants Sleep, SleepMicros, SleepMillis and SleepNanos

Parameters

time	Sleep duration.

Definition at line 356 of file thread.hpp.

Here is the call graph for this function:

◆ Start()

void Start ( )

virtual

Starts the execution of the thread. Method Run is invoked by the new system thread, which - if not overwritten - invokes the method Runnable::Run. Of course, this method immediately returns, and after invocation, method IsAlive will usually return true (unless the executed thread is not finished already).

Reimplemented in Trigger.

Definition at line 284 of file thread.cpp.

Here is the call graph for this function:

◆ YieldToSystem()

static void YieldToSystem ( )

inlinestatic

Proactively offers the system to suspend the current thread. Invokes std::this_thread::yield.

Note: Must not be named 'Yield', because this is a macro name with MSVC.

Definition at line 320 of file thread.hpp.

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

Description:

Friends

Public Type Index:

Public Static Method Index:

Public Method Index:

Protected Field Index:

Enumeration Details:

◆ State

Field Details:

◆ c11Thread

◆ id

◆ name

◆ nativeID

◆ runnable

◆ state

Constructor(s) / Destructor Details:

◆ Thread() [1/2]

◆ Thread() [2/2]

◆ ~Thread()

Method Details:

◆ Get()

◆ GetCurrent()

◆ GetID()

◆ GetMain()

◆ GetName()

◆ GetNativeID()

◆ GetState()

◆ IsAlive()

◆ Join()

◆ Run()

◆ SetName()

◆ Sleep() [1/2]

◆ Sleep() [2/2]

◆ SleepMicros()

◆ SleepMillis()

◆ SleepNanos()

◆ SleepUntil()

◆ Start()

◆ YieldToSystem()