ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
alib::threads::Thread Class Reference

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 124 of file thread.inl.

Inheritance diagram for alib::threads::Thread:
[legend]
Collaboration diagram for alib::threads::Thread:
[legend]

Public Type Index:

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

Public Static Method Index:

static ALIB_DLL ThreadGet (std::thread::id nativeID)
 
static ThreadGetCurrent ()
 
static ALIB_DLL ThreadGetMain ()
 
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:

 Thread (const character *pName=A_CHAR(""))
 
 Thread (const Thread &)=delete
 Deleted copy constructor.
 
ALIB_DLL Thread (Runnable *target, const character *pName=A_CHAR(""))
 
virtual ~Thread () override
 
ThreadID GetID () const
 
virtual const characterGetName () const
 
std::thread::id GetNativeID () const
 
State GetState ()
 
bool IsAlive ()
 
virtual ALIB_DLL void Join ()
 
virtual void Run () override
 
virtual void SetName (const character *newName)
 
virtual ALIB_DLL void Start ()
 
- Public Method Index: inherited from alib::threads::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.
 
const charactername =nullptr
 The name of the thread.
 
std::thread::id nativeID
 The internal C++ thread id.
 
Runnablerunnable =nullptr
 The runnable to execute.
 
State state = State::Unstarted
 Internal flag to indicate if the thread is alive.
 

Protected Method Index:

ALIB_DLL void destruct ()
 

Enumeration Details:

◆ State

enum class alib::threads::Thread::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 136 of file thread.inl.

Field Details:

◆ c11Thread

std::thread* alib::threads::Thread::c11Thread =nullptr
protected

The internal C++ thread object.

Definition at line 153 of file thread.inl.

◆ id

ThreadID alib::threads::Thread::id =0
protected

The id of the thread.

Definition at line 162 of file thread.inl.

◆ name

const character* alib::threads::Thread::name =nullptr
protected

The name of the thread.

Definition at line 165 of file thread.inl.

◆ nativeID

std::thread::id alib::threads::Thread::nativeID
protected

The internal C++ thread id.

Definition at line 156 of file thread.inl.

◆ runnable

Runnable* alib::threads::Thread::runnable =nullptr
protected

The runnable to execute.

Definition at line 159 of file thread.inl.

◆ state

State alib::threads::Thread::state = State::Unstarted
protected

Internal flag to indicate if the thread is alive.

Definition at line 168 of file thread.inl.

Constructor(s) / Destructor Details:

◆ Thread() [1/2]

alib::threads::Thread::Thread ( const character * pName = A_CHAR(""))
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 181 of file thread.inl.

Here is the call graph for this function:

◆ Thread() [2/2]

alib::threads::Thread::Thread ( Runnable * target,
const character * pName = A_CHAR("") )

Constructor with the provision of a Runnable 'target'. The Run method of target will be executed upon thread start (unless this class implements an own Run() method which overrides this behavior.

Parameters
targetThe 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 221 of file thread.cpp.

◆ ~Thread()

virtual alib::threads::Thread::~Thread ( )
inlineoverridevirtual

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 196 of file thread.inl.

Here is the call graph for this function:

Method Details:

◆ destruct()

void alib::threads::Thread::destruct ( )
protected

For reasons currently not understood, MSVC does not allow a direct implementation of the virtual destructor. Only when moving the implementation to this dedicated helper method, the linker does not complain about a missing vtable.

Definition at line 229 of file thread.cpp.

Here is the call graph for this function:

◆ Get()

Thread * alib::threads::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
nativeIDThe C++ Standard Libraray identifier.
Returns
A pointer to the instance associated with the native thread ID.

Definition at line 329 of file thread.cpp.

Here is the call graph for this function:

◆ GetCurrent()

Thread * alib::threads::Thread::GetCurrent ( )
inlinestatic

Static method that returns an object representing the thread that invoked this call. If no instance of class Thread was created for the current thread, yet, then one with a negative ID is created, indicating that this thread was not created by ALib.

Once a Thread was created, a pointer to this instance stored in the thread_local namespace variable THIS_THREAD is returned. Thus, this method is very fast from, starting with the second invocation.

Note
For technical reasons, under WindowsOS and DLL compilation, this method is not inlined, but implemented using the macro ALIB_DLL.
Returns
A pointer to the current thread.

Definition at line 300 of file thread.inl.

Here is the call graph for this function:

◆ GetID()

ThreadID alib::threads::Thread::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 227 of file thread.inl.

◆ GetMain()

Thread * alib::threads::Thread::GetMain ( )
static

Static method that returns the thread that initialized the library. Such thread 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 328 of file thread.cpp.

Here is the call graph for this function:

◆ GetName()

virtual const character * alib::threads::Thread::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 alib::threadmodel::DedicatedWorker.

Definition at line 241 of file thread.inl.

◆ GetNativeID()

std::thread::id alib::threads::Thread::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 233 of file thread.inl.

◆ GetState()

State alib::threads::Thread::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 258 of file thread.inl.

◆ IsAlive()

bool alib::threads::Thread::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 265 of file thread.inl.

◆ Join()

void alib::threads::Thread::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, a warning is raised.

Definition at line 251 of file thread.cpp.

◆ Run()

virtual void alib::threads::Thread::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 alib::threads::Runnable.

Reimplemented in alib::threadmodel::DedicatedWorker, and alib::threadmodel::Trigger.

Definition at line 217 of file thread.inl.

◆ SetName()

virtual void alib::threads::Thread::SetName ( const character * 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
newNameThe name that the Thread should hold.

Definition at line 247 of file thread.inl.

◆ Sleep() [1/2]

void alib::threads::Thread::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
durationSleep duration.

Definition at line 365 of file thread.inl.

◆ Sleep() [2/2]

void alib::threads::Thread::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
durationSleep duration.

Definition at line 371 of file thread.inl.

◆ SleepMicros()

void alib::threads::Thread::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
microsecondsSleep time in microseconds.

Definition at line 353 of file thread.inl.

◆ SleepMillis()

void alib::threads::Thread::SleepMillis ( int milliseconds)
inlinestatic

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

See also
Variants SleepMicros, SleepNanos, Sleep and SleepUntil
Parameters
millisecondsSleep time in milliseconds.

Definition at line 346 of file thread.inl.

◆ SleepNanos()

void alib::threads::Thread::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
nanosecondsSleep time in nanoseconds.

Definition at line 359 of file thread.inl.

◆ SleepUntil()

void alib::threads::Thread::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
timeSleep duration.

Definition at line 377 of file thread.inl.

◆ Start()

void alib::threads::Thread::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 alib::threadmodel::Trigger.

Definition at line 296 of file thread.cpp.

Here is the call graph for this function:

◆ YieldToSystem()

void alib::threads::Thread::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 341 of file thread.inl.


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