C++ Portable Types Library (PTypes) Version 1.7

Top: Multithreading: thread

#include <pasync.h>

thread::thread(bool autofree);
void thread::start();
void thread::signal();
void thread::waitfor();
pthread_id_t thread::get_id();
bool thread::get_running();
bool thread::get_finished();
bool thread::get_signaled();

virtual void thread::execute() = 0;
virtual void thread::cleanup() = 0;
bool thread::relax(int milliseconds);

Create a descendant of thread to represent an execution thread in a multithreaded application. All threads are running within the framework of the parent process and share the same global variables. Each thread, however, has its own stack. The execution of a thread can be started either from the main process or from another thread. Further, the newly launched thread executes its code concurrently.

Multithreading can significantly improve your application when a process consumes time by waiting for data from some communication device, a slow storage device or user input. When such pieces of code run concurrently the CPU is loaded more efficiently. The number of concurrently running threads within one application is usually limited to some reasonable amount (e.g. 30) since switching between threads on a single-CPU system consumes CPU time.

When threads concurrently access and modify shared data structures precautions should be taken to preserve logical integrity of these data structures. Synchronization between threads is performed using either of: semaphore, mutex, rwlock, trigger or msgqueue.

thread::thread(bool autofree) creates a thread object, but does not run it. If autofree is set to true the thread will destroy itself upon termination. Note, that you can use autofree only for dynamically allocated thread objects.

thread::~thread() destroys the thread object. Usually both the constructor and the destructor for non-autofree threads are called from a different context. In contrary, autofree threads call their destructors from their own context.

void thread::start() runs the thread. The overridden virtual method execute() is called asynchronously. start() itself returns immediately. Each thread object can be run only once. Subsequent calls to start() have no effect.

void thread::waitfor() waits for the thread to terminate. This function is called when a concurrent thread needs to synchronize its execution with the completion of the target non-autofree thread. For non-autofree threads this method must be called at least once. It is a good practice to place a call to waitfor() in the overridden destructor for this type of threads. waitfor(), however, can not be called for autofree threads.

void thread::signal() sets signaled attribute to true and possibly wakes up the thread if in a `relaxed' state (see relax() below). signal() is usually called from a different thread to let the given thread know that the execution should be terminated as soon as possible. If the given thread performs an iteration one of the conditions of leaving the loop should be (!get_signaled()).

pthread_id_t thread::get_id() returns the thread ID assigned by the operating system. This ID can then be used in call to pthrequal().

bool thread::get_running() returns true if the given thread object is running. This property is never set to 0 once the thread started. To check whether the thread finished its job, i.e. returned from execute(), use get_finished().

bool thread::get_finished() returns true if thread has already terminated its execution, or, in other words, has left execute().

bool thread::get_signaled() returns true if the thread object is in signaled state, i.e. signal() has been called from a concurrent thread. See also signal().

virtual void thread::execute() -- this pure virtual method should be overridden in the descendant class to implement the functionality of your thread. execute() can be viewed as main() for your mini-process. Typically, you create a class descendant from thread and override at least two virtual methods: execute() and cleanup().

virtual void thread::cleanup() -- this pure virtual method should be overridden in the descendant class. cleanup() is called either when the thread terminates normally or when an exception is raised within the thread's context. When implementing this method you might want to clean up any memory and other resources allocated by your thread object. cleanup() is guaranteed to be called once upon termination of the thread. To properly shut down the thread, avoid using operations that can cause exceptions in cleanup().

bool thread::relax(int milliseconds) is a protected member function which can be called only from within the overridden execute() method. This function suspends the execution of the thread until either of: the specified amount of time is elapsed, in which case the function returns false, or signal() is called from a concurrent thread, in which case relax() returns true. If parameter milliseconds is -1 the function will wait infinitely. The relax/signal mechanism is useful for threads doing some job that requires taking periodic actions in the background.

See also: semaphore, mutex, rwlock, trigger, Utilities, Examples

PTypes home