Private Types | List of all members
blaze::Thread< TT, MT, LT, CT > Class Template Reference

Implementation of a single thread of execution. More...

#include <Thread.h>

Inherits blaze::NonCopyable.

Public Member Functions

Destructor
 ~Thread ()
 Destructor for the Thread class.
 

Private Types

typedef TT ThreadType
 Type of the encapsulated thread.
 
typedef ThreadPool< TT, MT, LT, CT > ThreadPoolType
 Type of the managing thread pool.
 
typedef std::unique_ptr< ThreadTypeThreadHandle
 Handle for a single thread.
 

Private Member Functions

Thread execution functions
void run ()
 Execution function for threads in a thread pool. More...
 

Private Attributes

Member variables
volatile bool terminated_
 Thread termination flag. More...
 
ThreadPoolTypepool_
 Handle to the managing thread pool.
 
ThreadHandle thread_
 Handle to the thread of execution.
 

Constructors

 Thread (ThreadPoolType *pool)
 Starting a thread in a thread pool. More...
 
template<typename Callable , typename... Args>
 Thread (Callable func, Args &&...args)
 Starting a thread of execution on the given zero argument function/functor. More...
 

Utility functions

bool hasTerminated () const
 Returns whether the thread has terminated its execution. More...
 
bool joinable () const
 Returns whether this is a thread of execution. More...
 
void join ()
 Waiting for a thread of execution to complete. More...
 

Detailed Description

template<typename TT, typename MT, typename LT, typename CT>
class blaze::Thread< TT, MT, LT, CT >

Implementation of a single thread of execution.

General

The Thread template represents a thread of execution for the parallel execution of concurrent tasks. Each Thread object incorporates a single thread of execution, or Not-a-Thread, and at most one Thread object incorporates a given thread of execution since it is not possible to copy a Thread.

Class Definition

The implementation of the Thread class template is based on the implementation of standard threads as provided by the C++11 standard or the Boost library. Via the four template parameters it is possible to configure a Thread instance as either a C++11 thread or as Boost thread:

template< typename TT, typename MT, typename LT, typename CT >
class Thread;

Examples:

typedef blaze::Thread< boost::thread
, boost::mutex
, boost::unique_lock<boost::mutex>
, boost::condition_variable > BoostThread;
typedef blaze::Thread< std::thread
, std::mutex
, std::unique_lock<std::mutex>
, std::condition_variable > StdThread;

For more information about the standard thread functionality, see [1] or [2] or the current documentation at the Boost homepage: www.boost.org.

Creating individual threads

The Blaze library provides the functionality to create individual threads for specific tasks, or to create thread pools for the execution of a larger number of tasks (see the ThreadPool class description). The following example demonstrates the setup of individual threads to handle specific tasks. In this example, a function without arguments and a functor with two arguments are executed in parallel by two distinct threads:

// Definition of a function with no arguments that returns void
void function0() { ... }
// Definition of a functor (function object) taking two arguments and returning void
struct Functor2
{
void operator()( int a, int b ) { ... }
};
int main()
{
// Creating a new thread executing the zero argument function.
StdThread thread1( function0 );
// Waiting for the thread to finish its task
thread1.join();
// After the thread has completed its tasks, it is not possible to reassign it a
// new task. Therefore it is necessary to create a new thread for optional follow
// up tasks.
// Creating a new thread executing the binary functor.
StdThread thread2( Functor2(), 4, 6 );
// Waiting for the second thread to finish its task
thread2.join();
}

Note that the Thread class allows for up to five arguments for the given functions/functors. Also note that the two tasks are not executed in parallel since the join() function is used to wait for each thread's completion.

Throwing exceptions in a thread parallel environment

It can happen that during the execution of a given task a thread encounters an erroneous situation and has to throw an exception. However, exceptions thrown in the usual way cannot be caught by a try-catch-block in the main thread of execution:

// Definition of a function throwing a std::runtime_error during its execution
void task()
{
...
throw std::runtime_error( ... );
...
}
// Creating a thread executing the throwing function. Although the setup, execution and
// destruction of the thread are encapsuled inside a try-catch-block, the exception cannot
// be caught and results in an abortion of the program.
try {
StdThread thread( task );
thread.join();
}
catch( ... )
{
...
}

For a detailed explanation how to portably transport exceptions between threads, see [1] or [2]. In case of the Boost library, the according Boost functionality as demonstrated in the following example has to be used. Note that any function/functor passed to a thread is responsible to handle exceptions in this way!

#include <boost/bind.hpp>
#include <boost/exception_ptr.hpp>
// Definition of a function that happens to throw an exception. In order to throw the
// exception, boost::enable_current_exception() is used in combination with throw.
void throwException()
{
...
throw boost::enable_current_exception( std::runtime_error( ... ) );
...
}
// Definition of a thread function. The try-catch-block catches the exception and uses the
// boost::current_exception() function to get a boost::exception_ptr object.
void task( boost::exception_ptr& error )
{
try {
throwException();
error = boost::exception_ptr();
}
catch( ... ) {
error = boost::current_exception();
}
}
// The function that start a thread of execution can pass along a boost::exception_ptr object
// that is set in case of an exception. Note that boost::current_exception() captures the
// original type of the exception object. The exception can be thrown again using the
// boost::rethrow_exception() function.
void work()
{
boost::exception_ptr error;
Thread<boost::thread> thread( boost::bind( task, boost::ref(error) ) );
thread.join();
if( error ) {
std::cerr << " Exception during thread execution!\n\n";
boost::rethrow_exception( error );
}
}

References

[1] A. Williams: C++ Concurrency in Action, Manning, 2012, ISBN: 978-1933988771
[2] B. Stroustrup: The C++ Programming Language, Addison-Wesley, 2013, ISBN: 978-0321563842

Constructor & Destructor Documentation

template<typename TT , typename MT , typename LT , typename CT >
blaze::Thread< TT, MT, LT, CT >::Thread ( ThreadPoolType pool)
explicitprivate

Starting a thread in a thread pool.

Parameters
poolHandle to the managing thread pool.

This function creates a new thread in the given thread pool. The thread is kept alive until explicitly killed by the managing thread pool.

template<typename TT , typename MT , typename LT , typename CT >
template<typename Callable , typename... Args>
blaze::Thread< TT, MT, LT, CT >::Thread ( Callable  func,
Args &&...  args 
)
inlineexplicit

Starting a thread of execution on the given zero argument function/functor.

Parameters
funcThe given function/functor.
argsThe arguments for the function/functor.

This function creates a new thread of execution on the given function/functor. The given function/functor must be copyable, must be callable without arguments and must return void.

Member Function Documentation

template<typename TT , typename MT , typename LT , typename CT >
bool blaze::Thread< TT, MT, LT, CT >::hasTerminated ( ) const
inlineprivate

Returns whether the thread has terminated its execution.

Returns
true in case the thread is terminated, false otherwise.

This function is used by the managing thread pool to learn whether the thread has finished its execution and can be destroyed.

template<typename TT , typename MT , typename LT , typename CT >
void blaze::Thread< TT, MT, LT, CT >::join ( )
inline

Waiting for a thread of execution to complete.

Returns
void

If the thread is still executing the given task, this function blocks until the thread's tasks is completed.

template<typename TT , typename MT , typename LT , typename CT >
bool blaze::Thread< TT, MT, LT, CT >::joinable ( ) const
inline

Returns whether this is a thread of execution.

Returns
true if this is a thread of execution, false otherwise.

This function returns whether this thread is still executing the given task or if it has already finished the job. In case the thread is still execution, the function returns true, else it returns false.

template<typename TT , typename MT , typename LT , typename CT >
void blaze::Thread< TT, MT, LT, CT >::run ( )
private

Execution function for threads in a thread pool.

This function is executed by any thread managed by a thread pool.

Member Data Documentation

template<typename TT , typename MT , typename LT , typename CT >
volatile bool blaze::Thread< TT, MT, LT, CT >::terminated_
private

Thread termination flag.

This flag value is used by the managing thread pool to learn whether the thread has terminated its execution.


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