NAME¶

SYNOPSIS¶

#include <thread.h>

Inherited by ost::PosixThread, ost::SerialService, ost::SocketService, ost::TCPSession, ost::ThreadQueue, ost::TTYSession, and ost::UnixSession.

Detailed Description¶

Classes derived from Thread must implement the run() method, which specifies the code of the thread. The base Thread class supports encapsulation of the generic threading methods implemented on various target operating systems. This includes the ability to start and stop threads in a synchronized and controllable manner, the ability to specify thread execution priority, and thread specific 'system call' wrappers, such as for sleep and yield. A thread exception is thrown if the thread cannot be created. Threading was the first part of Common C++ I wrote, back when it was still the APE library. My goal for Common C++ threading has been to make threading as natural and easy to use in C++ application development as threading is in Java. With this said, one does not need to use threading at all to take advantage of Common C++. However, all Common C++ classes are designed at least to be thread-aware/thread-safe as appropriate and necessary.

Common C++ threading is currently built either from the Posix 'pthread' library or using the win32 SDK. In that the Posix 'pthread' draft has gone through many revisions, and many system implementations are only marginally compliant, and even then usually in different ways, I wrote a large series of autoconf macros found in ost_pthread.m4 which handle the task of identifying which pthread features and capabilities your target platform supports. In the process I learned much about what autoconf can and cannot do for you..

Currently the GNU Portable Thread library (GNU pth) is not directly supported in Common C++. While GNU 'Pth' doesn't offer direct native threading support or benefit from SMP hardware, many of the design advantages of threading can be gained from it's use, and the Pth pthread 'emulation' library should be usable with Common C++. In the future, Common C++ will directly support Pth, as well as OS/2 and BeOS native threading API's.

Common C++ itself defines a fairly 'neutral' threading model that is not tied to any specific API such as pthread, win32, etc. This neutral thread model is contained in a series of classes which handle threading and synchronization and which may be used together to build reliable threaded applications.

Common C++ defines application specific threads as objects which are derived from the Common C++ 'Thread' base class. At minimum the 'Run' method must be implemented, and this method essentially is the 'thread', for it is executed within the execution context of the thread, and when the Run method terminates the thread is assumed to have terminated.

Common C++ allows one to specify the running priority of a newly created thread relative to the 'parent' thread which is the thread that is executing when the constructor is called. Since most newer C++ implementations do not allow one to call virtual constructors or virtual methods from constructors, the thread must be 'started' after the constructor returns. This is done either by defining a 'starting' semaphore object that one or more newly created thread objects can wait upon, or by invoking an explicit 'start' member function.

Threads can be 'suspended' and 'resumed'. As this behavior is not defined in the Posix 'pthread' specification, it is often emulated through signals. Typically SIGUSR1 will be used for this purpose in Common C++ applications, depending in the target platform. On Linux, since threads are indeed processes, SIGSTP and SIGCONT can be used. On solaris, the Solaris thread library supports suspend and resume directly.

Threads can be canceled. Not all platforms support the concept of externally cancelable threads. On those platforms and API implementations that do not, threads are typically canceled through the action of a signal handler.

As noted earlier, threads are considered running until the 'Run' method returns, or until a cancellation request is made. Common C++ threads can control how they respond to cancellation, using setCancellation(). Cancellation requests can be ignored, set to occur only when a cancellation 'point' has been reached in the code, or occur immediately. Threads can also exit by returning from Run() or by invoking the Exit() method.

Generally it is a good practice to initialize any resources the thread may require within the constructor of your derived thread class, and to purge or restore any allocated resources in the destructor. In most cases, the destructor will be executed after the thread has terminated, and hence will execute within the context of the thread that requested a join rather than in the context of the thread that is being terminated. Most destructors in derived thread classes should first call Terminate() to make sure the thread has stopped running before releasing resources.

A Common C++ thread is normally canceled by deleting the thread object. The process of deletion invokes the thread's destructor, and the destructor will then perform a 'join' against the thread using the Terminate() function. This behavior is not always desirable since the thread may block itself from cancellation and block the current 'delete' operation from completing. One can alternately invoke Terminate() directly before deleting a thread object.

When a given Common C++ thread exits on it's own through it's Run() method, a 'Final' method will be called. This Final method will be called while the thread is 'detached'. If a thread object is constructed through a 'new' operator, it's final method can be used to 'self delete' when done, and allows an independent thread to construct and remove itself autonomously.

A special global function, getThread(), is provided to identify the thread object that represents the current execution context you are running under. This is sometimes needed to deliver signals to the correct thread. Since all thread manipulation should be done through the Common C++ (base) thread class itself, this provides the same functionality as things like 'pthread_self' for Common C++.

All Common C++ threads have an exception 'mode' which determines their behavior when an exception is thrown by another Common C++ class. Extensions to Common C++ should respect the current exception mode and use getException() to determine what to do when they are about to throw an object. The default exception mode (defined in the Thread() constructor) is throwObject, which causes a pointer to an instance of the class where the error occured to be thrown. Other exception modes are throwException, which causes a class-specific exception class to be thrown, and throwNothing, which causes errors to be ignored.

As an example, you could try to call the Socket class with an invalid address that the system could not bind to. This would cause an object of type Socket * to be thrown by default, as the default exception mode is throwObject. If you call setException(throwException) before the bad call to the Socket constructor, an object of type SockException (the exception class for class Socket) will be thrown instead.

To determine what exception class is thrown by a given Common C++ class when the exception mode is set to throwException, search the source files for the class you are interested in for a class which inherits directly or indirectly from class Exception. This is the exception class which would be thrown when the exception mode is set to throwException.

The advantage of using throwException versus throwObject is that more information is available to the programmer from the thrown object. All class-specific exceptions inherit from class Exception, which provides a getString() method which can be called to get a human-readable error string.

Common C++ threads are often aggregated into other classes to provide services that are 'managed' from or operate within the context of a thread, even within the Common C++ framework itself. A good example of this is the TCPSession class, which essentially is a combination of a TCP client connection and a separate thread the user can define by deriving a class with a Run() method to handle the connected service. This aggregation logically connects the successful allocation of a given resource with the construction of a thread to manage and perform operations for said resource.

Threads are also used in 'service pools'. In Common C++, a service pool is one or more threads that are used to manage a set of resources. While Common C++ does not provide a direct 'pool' class, it does provide a model for their implementation, usually by constructing an array of thread 'service' objects, each of which can then be assigned the next new instance of a given resource in turn or algorithmically.

Threads have signal handlers associated with them. Several signal types are 'predefined' and have special meaning. All signal handlers are defined as virtual member functions of the Thread class which are called when a specific signal is received for a given thread. The 'SIGPIPE' event is defined as a 'Disconnect' event since it's normally associated with a socket disconnecting or broken fifo. The Hangup() method is associated with the SIGHUP signal. All other signals are handled through the more generic Signal().

Incidently, unlike Posix, the win32 API has no concept of signals, and certainly no means to define or deliver signals on a per-thread basis. For this reason, no signal handling is supported or emulated in the win32 implementation of Common C++ at this time.

In addition to TCPStream, there is a TCPSession class which combines a thread with a TCPStream object. The assumption made by TCPSession is that one will service each TCP connection with a separate thread, and this makes sense for systems where extended connections may be maintained and complex protocols are being used over TCP.

Author:

Examples:
bug1.cpp, bug2.cpp, tcpservice.cpp, tcpstr1.cpp, thread1.cpp, and thread2.cpp.

Member Typedef Documentation¶

Member Enumeration Documentation¶

Constructor & Destructor Documentation¶

Member Function Documentation¶

Friends And Related Function Documentation¶

Author¶