Libthreadar 1.4.0
Public Member Functions | Protected Member Functions | List of all members
libthreadar::thread Class Referenceabstract

Class thread is a pure virtual class, that implements thread creation and operations. More...

#include <thread.hpp>

Public Member Functions

 thread ()
 constructor
 
 thread (const thread &ref)=delete
 copy constructor and assignment operator are disabled
 
 thread (thread &&ref) noexcept=default
 
threadoperator= (const thread &ref)=delete
 
threadoperator= (thread &&ref) noexcept=default
 
virtual ~thread ()
 destructor
 
void set_signal_mask (const sigset_t &mask)
 set signal mask for this object's when the thread will be run More...
 
void run ()
 launch the current object routing in a separated thread
 
bool is_running () const
 checks whether a separated thread is running the inherited_run() method of this object More...
 
bool is_running (pthread_t &id) const
 checks whether the object is running in a separated thread More...
 
void join () const
 the caller will be suspended until the current object's thread ends
 
void kill () const
 the caller send a cancellation request to this object's running thread if any More...
 

Protected Member Functions

virtual void inherited_run ()=0
 action to be performed in the separated thread More...
 
void suspend_cancellation_requests () const
 available for inherited class to avoid thread cancellation to occur in a critical section More...
 
void resume_cancellation_requests () const
 available for inherited class to avoid thread cancellation to occur in a critical section
 

Detailed Description

Class thread is a pure virtual class, that implements thread creation and operations.

At the difference of the C++11 thread directive, the creation of an inherited class object does not immediately launch a thread. The inherited class can first provide any fields necessary to the thread execution by mean of inherited class constructor or better by using several customized method of the inherited class, which brings better readability and ease code maintenance than having a call with a lot of argument as C++11 requests it to be done.

Inherited classes must only define the inherited_run() method, method that will be run in its specific thread once the run() method will be called. The private field of inherited classes can be used to host variables only accessible by the running thread. Inherited class may also implement method to communicate with the running thread, here too the private (or protected) fields of the class can be used to host mutex if one is necessary to provide consistent information from one thread to the other.

The join() method can be used by the run() caller to wait for thread termination. If the corresponding thread has already ended, the join() method ends immediately. If the thread aborted due to an exception, this exception will be rethrown from the the thread calling join(). Last, calling join() on an object which thread has not yet started or which has ended and for which join() has already been run, does nothing: the join() method returns immediately.

Note
Class thread object destruction kills the thread and could have generated an exception from inherited_run(), but this one will be caught and ignored by the thread::thread parent destructor. Under some context implementation (Cygwin) if a pthread has already started but has not yet reached the time it calls inherited_run() method, when object destructor is called, when the subthread calls the inherited_run() method, the system may report a SEGFAULT in particular when the fields of the object that are from the inherited class do not exist anymore. The kill() and join() present in the thread::~thread destructor, cannot prevent this as when the execution pointer reach them, all inherited class fields do no more exist.

IT IS THUS IMPORTANT FOR ANY INHERITED CLASS TO INVOKE kill() THEN join() IN THEIR DESTRUCTOR

Once the thread is no more running a new call to run() is allowed if a join() call has been issued since the thread was last run. This allows to run again a thread without having to pass again all the possibly many arguments and datastructures requested by this thread.

Examples
/doc/examples/fast_tampon_example.cpp, and /doc/examples/thread_example.cpp.

Definition at line 97 of file thread.hpp.

Member Function Documentation

◆ inherited_run()

virtual void libthreadar::thread::inherited_run ( )
protectedpure virtual

action to be performed in the separated thread

Note
There is no argument to provide, because this is the responsibility of the inherited class to defined private/protected fields, methods and constructors to set their value and define whether fields are only accessed by the spawn or the calling thread or both and in that case which way to avoid concurrent access to such fields.
Examples
/doc/examples/fast_tampon_example.cpp, and /doc/examples/thread_example.cpp.

◆ is_running() [1/2]

bool libthreadar::thread::is_running ( ) const
inline

checks whether a separated thread is running the inherited_run() method of this object

Examples
/doc/examples/fast_tampon_example.cpp, and /doc/examples/thread_example.cpp.

Definition at line 121 of file thread.hpp.

◆ is_running() [2/2]

bool libthreadar::thread::is_running ( pthread_t &  id) const

checks whether the object is running in a separated thread

Parameters
[out]idreturns the thread_id upon success
Returns
true if the object is running under a separated thread if false is returned, the argument is not set

◆ kill()

void libthreadar::thread::kill ( ) const

the caller send a cancellation request to this object's running thread if any

Note
if the thread is suspended by the system reading or writing to a filedescriptor for example, the thread survives up to the time it exits from that suspended state
Examples
/doc/examples/thread_example.cpp.

◆ set_signal_mask()

void libthreadar::thread::set_signal_mask ( const sigset_t &  mask)
inline

set signal mask for this object's when the thread will be run

Note
see sigsetops(3) for details on manipulating signal sets

Definition at line 115 of file thread.hpp.

◆ suspend_cancellation_requests()

void libthreadar::thread::suspend_cancellation_requests ( ) const
protected

available for inherited class to avoid thread cancellation to occur in a critical section

any cancellation request received after a call to suspend_cancellation_requests() is delayed until a call to resume_cancellation_requests() is issued


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