ALib C++ Library
Library Version: 2312 R0
Documentation generated by doxygen
Public Types | Public Static Methods | Public Methods | Protected Fields | List of all members
Thread Class Reference

#include <thread.hpp>

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

Class Description


This class provides a limited (minimal) abstraction of C++ 11 threads. 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

Definition at line 109 of file thread.hpp.

Public Types

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

Public Static Methods

static ThreadGetCurrent ()
 
static ALIB_API ThreadGetMain ()
 
static void Sleep (const Ticks::Duration &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 ALIB_API void YieldToSystem ()
 

Public Methods

ALIB_API Thread (const String &pName=EmptyString())
 
ALIB_API Thread (Runnable *target, const String &pName=EmptyString())
 
virtual ALIB_API ~Thread () override
 
virtual ThreadID GetId ()
 
virtual const CString GetName ()
 
State GetState ()
 
bool IsAlive ()
 
virtual void Run () override
 
virtual void SetName (const String &newName)
 
virtual ALIB_API void Start ()
 
virtual ALIB_API void Terminate ()
 
- Public Methods inherited from Runnable
virtual ~Runnable ()
 

Protected Fields

std::thread::id c11ID
 
std::thread * c11Thread =nullptr
 
ThreadID id =0
 
AString name
 
Runnablerunnable =nullptr
 
State state = State::Unstarted
 

Member Enumeration Documentation

◆ State

enum 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.

Stopped 

The run method is processed and the thread is ready to be terminated.

Terminated 

The thread is terminated.

Definition at line 123 of file thread.hpp.

Constructor & Destructor Documentation

◆ Thread() [1/2]

ALIB_API Thread ( const String pName = EmptyString())
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 169 of file thread.hpp.

◆ Thread() [2/2]

Thread ( Runnable target,
const String pName = EmptyString() 
)

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
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 231 of file thread.cpp.

Here is the call graph for this function:

◆ ~Thread()

~Thread ( )
overridevirtual

Prior to destruction, Terminate 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. Declared virtual, as inherited from Runnable.

Definition at line 241 of file thread.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ 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 287 of file thread.hpp.

Here is the call graph for this function:

◆ GetId()

virtual ThreadID GetId ( )
inlinevirtual

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 216 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 351 of file thread.cpp.

◆ GetName()

virtual const CString GetName ( )
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, such names are for debugging and logging purposes only.

Returns
Returns the name of the thread.

Definition at line 225 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 247 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 256 of file thread.hpp.

◆ 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.

Definition at line 204 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. In fact, such names are for debugging and logging purposes only.

Parameters
newNameThe name that the Thread should hold.

Definition at line 234 of file thread.hpp.

Here is the call graph for this function:

◆ Sleep()

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
durationSleep duration.

Definition at line 362 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
microsecondsSleep time in microseconds.

Definition at line 335 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
millisecondsSleep time in milliseconds.

Definition at line 321 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
nanosecondsSleep time in nanoseconds.

Definition at line 348 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
timeSleep duration.

Definition at line 375 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).

Definition at line 316 of file thread.cpp.

Here is the call graph for this function:

◆ Terminate()

void Terminate ( )
virtual

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

Definition at line 254 of file thread.cpp.

Here is the call graph for this function:

◆ YieldToSystem()

static ALIB_API 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 308 of file thread.hpp.

Member Data Documentation

◆ c11ID

std::thread::id c11ID
protected

The internal C++ 11 thread id.

Definition at line 142 of file thread.hpp.

◆ c11Thread

std::thread* c11Thread =nullptr
protected

The internal C++ 11 thread object.

Definition at line 139 of file thread.hpp.

◆ id

ThreadID id =0
protected

The id of the thread.

Definition at line 148 of file thread.hpp.

◆ name

AString name
protected

The name of the thread.

Definition at line 151 of file thread.hpp.

◆ runnable

Runnable* runnable =nullptr
protected

The runnable to execute.

Definition at line 145 of file thread.hpp.

◆ state

State state = State::Unstarted
protected

Internal flag to indicate if thread is alive.

Definition at line 154 of file thread.hpp.


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