cpp3ds::Thread Class Reference

Utility class to manipulate threads. More...

#include <Thread.hpp>

Inheritance diagram for cpp3ds::Thread:

Public Member Functions
template<typename F >
	Thread (F function)
	Construct the thread from a functor with no argument. More...
template<typename F , typename A >
	Thread (F function, A argument)
	Construct the thread from a functor with an argument. More...
template<typename C >
	Thread (void(C::*function)(), C *object)
	Construct the thread from a member function and an object. More...
void	initialize ()
	~Thread ()
	Destructor. More...
void	launch ()
	Run the thread. More...
void	wait ()
	Wait until the thread finishes. More...
void	terminate ()
	Terminate the thread. More...

Detailed Description

Utility class to manipulate threads.

Threads provide a way to run multiple parts of the code in parallel.

When you launch a new thread, the execution is split and both the new thread and the caller run in parallel.

To use a cpp3ds::Thread, you construct it directly with the function to execute as the entry point of the thread. cpp3ds::Thread has multiple template constructors, which means that you can use several types of entry points:

• non-member functions with no argument
• non-member functions with one argument of any type
• functors with no argument (this one is particularly useful for compatibility with boost/std::bind)
• functors with one argument of any type
• member functions from any class with no argument

The function argument, if any, is copied in the cpp3ds::Thread instance, as well as the functor (if the corresponding constructor is used). Class instances, however, are passed by pointer so you must make sure that the object won't be destroyed while the thread is still using it.

The thread ends when its function is terminated. If the owner cpp3ds::Thread instance is destroyed before the thread is finished, the destructor will wait (see wait())

Usage examples:

// example 1: non member function with one argument

void threadFunc(int argument)
{
    ...
}

cpp3ds::Thread thread(&threadFunc, 5);
thread.launch(); // start the thread (internally calls threadFunc(5))

// example 2: member function

class Task
{
public :
    void run()
    {
        ...
    }
};

Task task;
cpp3ds::Thread thread(&Task::run, &task);
thread.launch(); // start the thread (internally calls task.run())

// example 3: functor

struct Task
{
    void operator()()
    {
        ...
    }
};

cpp3ds::Thread thread(Task());
thread.launch(); // start the thread (internally calls operator() on the Task instance)

Creating parallel threads of execution can be dangerous: all threads inside the same process share the same memory space, which means that you may end up accessing the same variable from multiple threads at the same time. To prevent this kind of situations, you can use mutexes (see cpp3ds::Mutex).

See also

cpp3ds::Mutex

Definition at line 53 of file Thread.hpp.

Constructor & Destructor Documentation

template<typename F >

cpp3ds::Thread::Thread

(

F

function

)

Construct the thread from a functor with no argument.

This constructor works for function objects, as well as free function.

Use this constructor for this kind of function:

void function();

// --- or ----

struct Functor
{
    void operator()();
};

Note: this does not run the thread, use Launch().

Parameters

function

Functor or free function to use as the entry point of the thread

template<typename F , typename A >

cpp3ds::Thread::Thread	(	F	function,
		A	argument
	)

Construct the thread from a functor with an argument.

This constructor works for function objects, as well as free function. It is a template, which means that the argument can have any type (int, std::string, void*, Toto, ...).

Use this constructor for this kind of function:

void function(int arg);

// --- or ----

struct Functor
{
    void operator()(std::string arg);
};

Note: this does not run the thread, use Launch().

Parameters

function	Functor or free function to use as the entry point of the thread
argument	argument to forward to the function

template<typename C >

cpp3ds::Thread::Thread	(	void(C::*)()	function,
		C *	object
	)

Construct the thread from a member function and an object.

This constructor is template, which means that you can use it with any class. Use this constructor for this kind of function:

class MyClass
{
public :

    void function();
};

Note: this does not run the thread, use Launch().

Parameters

function	Entry point of the thread
object	Pointer to the object to use

cpp3ds::Thread::~Thread

(

)

Destructor.

This destructor calls Wait(), so that the internal thread cannot survive after its cpp3ds::Thread instance is destroyed.

Member Function Documentation

void cpp3ds::Thread::launch

(

)

Run the thread.

This function starts the entry point passed to the thread's constructor, and returns immediately. After this function returns, the thread's function is running in parallel to the calling code.

void cpp3ds::Thread::terminate

(

)

Terminate the thread.

This function immediately stops the thread, without waiting for its function to finish. Terminating a thread with this function is not safe, and can lead to local variables not being destroyed on some operating systems. You should rather try to make the thread function terminate by itself.

void cpp3ds::Thread::wait

(

)

Wait until the thread finishes.

This function will block the execution until the thread's function ends. Warning: if the thread function never ends, the calling thread will block forever. If this function is called from its owner thread, it returns without doing anything.

---

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

• Thread.hpp