#include <threadFunctor.h>
Public Member Functions | |
| ThreadFunctor (const std::string &threadName="anonymous") | |
| This constructor initializes the ThreadFunctor instance and sets the thread name. | |
| ThreadFunctor (const ThreadFunctor &source) | |
| The copy constructor does a deep copy. | |
| virtual | ~ThreadFunctor () |
| Destroys the ThreadFunctor instance and releases any resources. | |
| ThreadFunctor & | operator= (const ThreadFunctor &source) |
| The assignment operator does a deep copy. | |
| virtual void | operator() () |
| This operator executes this->main(), catches any exceptions thrown by this->main(), and handles those exceptions by calling this->handleError(). | |
| const std::string & | getThreadName () |
| This member function returns the name of the thread. | |
| virtual void | handleError (const std::string &errorMessage, const std::string &errorDetail) |
| This member function is called if an exception is thrown by this->main() to send notification that the thread is about to terminate. | |
| void | join () |
| This member function blocks until the thread associated with *this exits. | |
| virtual void | main ()=0 |
| This pure virtual function should be overridden by the subclass to contain whatever code the ThreadFunctor instance is responsible for running. | |
| void | run () |
| This member function creates a new thread and executes this->operator()() from within that thread. | |
| void | setName (const std::string &threadName) |
| This member function sets the name of the thread. | |
Protected Attributes | |
| std::string | m_threadName |
| boost::thread * | m_threadPtr |
Derived classes should define the main() method so that it runs whatever code is to be executed by the thread. Derived classes may optionally define a handleError() method which will be called if the main() method throws an exception. The default version of handleError() simply prints a message to standard error. The run() method will start the new thread, and the join() method will block until that thread's main() method finishes. Here's an example of how to use ThreadFunctor:
class MyThreadFunctor : public dlr::ThreadFunctor { public: MyThreadFunctor(const std::string& threadName) : dlr::ThreadFunctor(threadName) {} void main() { // Do stuff. } }; // Later, in application code... MyThreadFunctor threadFunctor0("Thread 0"); MyThreadFunctor threadFunctor1("Thread 1"); threadFunctor0.run(); threadFunctor1.run(); // Later still... threadFunctor0.join(); threadFunctor1.join();
It's OK to copy a ThreadFunctor instance, but you must remember that the copy does not refer to the same thread as the original. This can cause some subtle errors. For example, this code is broken:
std::vector<MyThreadFunctor> threadFunctorVector; threadFunctorVector.push_back(MyThreadFunctor("Thread 0")); threadFunctorVector[0].run(); threadFunctorVector.push_back(MyThreadFunctor("Thread 1")); threadFunctorVector[1].run(); threadFunctorVector[0].join(); threadFunctorVector[1].join();
The error is that the second call to push_back() may copy the already running thread, and the calls to join() won't match up. The following code is OK:
std::vector<MyThreadFunctor> threadFunctorVector; threadFunctorVector.push_back(MyThreadFunctor("Thread 0")); threadFunctorVector.push_back(MyThreadFunctor("Thread 1")); threadFunctorVector[0].run(); threadFunctorVector[1].run(); threadFunctorVector[0].join(); threadFunctorVector[1].join();
Definition at line 88 of file threadFunctor.h.
| dlr::thread::ThreadFunctor::ThreadFunctor | ( | const std::string & | threadName = "anonymous" |
) | [inline] |
This constructor initializes the ThreadFunctor instance and sets the thread name.
It is encouraged to use a unique thread name for each thread, and to include the thread name in any exception messages, since this will make debugging easier.
| threadName | This argument |
Definition at line 101 of file threadFunctor.h.
| dlr::thread::ThreadFunctor::ThreadFunctor | ( | const ThreadFunctor & | source | ) | [inline] |
The copy constructor does a deep copy.
Note that it does not change the thread name, so after copying a ThreadFunctor instance it may be useful to call the setName() method with a unique name.
| source | The ThreadFunctor instance to be copied. |
Definition at line 113 of file threadFunctor.h.
| dlr::thread::ThreadFunctor::~ThreadFunctor | ( | ) | [virtual] |
Destroys the ThreadFunctor instance and releases any resources.
Definition at line 47 of file threadFunctor.cpp.
References m_threadPtr.
| ThreadFunctor & dlr::thread::ThreadFunctor::operator= | ( | const ThreadFunctor & | source | ) |
The assignment operator does a deep copy.
Note that it does not change the thread name, so after copying a ThreadFunctor instance it may be useful to call the setName() method with a unique name. It is an error to call this member function while a subordinate thread is running. That is, if you've called this->run(), you must call this->join() before calling this->operator=().
| source | The ThreadFunctor instance to be copied. |
Definition at line 60 of file threadFunctor.cpp.
References DLR_THROW, m_threadName, and m_threadPtr.
| void dlr::thread::ThreadFunctor::operator() | ( | ) | [virtual] |
This operator executes this->main(), catches any exceptions thrown by this->main(), and handles those exceptions by calling this->handleError().
It is normally not necessary to call this member function directly. Call this->run() instead to create a new thread and automatically call this->operator()() from within that thread.
Definition at line 83 of file threadFunctor.cpp.
References handleError(), and main().
| const std::string& dlr::thread::ThreadFunctor::getThreadName | ( | ) | [inline] |
This member function returns the name of the thread.
Definition at line 160 of file threadFunctor.h.
References m_threadName.
| void dlr::thread::ThreadFunctor::handleError | ( | const std::string & | errorMessage, | |
| const std::string & | errorDetail | |||
| ) | [virtual] |
This member function is called if an exception is thrown by this->main() to send notification that the thread is about to terminate.
The default implementation simply prints to the standard error output. Subclasses may override this function to handle the error in other ways.
| errorMessage | This argument is a short string describing the error. It is generated from the what() message of the caught exception. | |
| errorDetail | This argument is a longer string containing more details about the error. If such details are not available, it is set to the empty string. It is generated from the trace() message of a caught dlr::Exception instance. |
Definition at line 103 of file threadFunctor.cpp.
References m_threadName.
Referenced by operator()().
| void dlr::thread::ThreadFunctor::join | ( | ) |
This member function blocks until the thread associated with *this exits.
It is an error to call join() without first calling run() to start the thread.
Definition at line 122 of file threadFunctor.cpp.
References DLR_THROW, m_threadName, and m_threadPtr.
| virtual void dlr::thread::ThreadFunctor::main | ( | ) | [pure virtual] |
This pure virtual function should be overridden by the subclass to contain whatever code the ThreadFunctor instance is responsible for running.
Referenced by operator()().
| void dlr::thread::ThreadFunctor::run | ( | ) |
This member function creates a new thread and executes this->operator()() from within that thread.
It is an error to call run() twice without calling join() in between.
Definition at line 141 of file threadFunctor.cpp.
References DLR_THROW, m_threadName, and m_threadPtr.
| void dlr::thread::ThreadFunctor::setName | ( | const std::string & | threadName | ) | [inline] |
This member function sets the name of the thread.
The thread name will be included in the what() message of any exception thrown by ThreadFunctor, and it is encouraged to include it in the messages of any exceptions thrown by derived class member functions.
| threadName | This argument specifies a name for the thread. |
Definition at line 223 of file threadFunctor.h.
References m_threadName.
1.5.2