This section uses a simple example to introduce and explain the concepts and classes involved in creating threads. You can find more examples in buildspace\-examples\package-name. The following list gives the names of those examples and the classes and functions that they exercise:
activobj: RWThreadFunction, RWRunnableFunction, RWRunnableServer, RWTRunnableIOUFunction, RWTThreadIOUFunction, rwtMakeRunnableFunction(), rwtMakeRunnableIOUFunction(), rwtMakeRunnableGuard(), rwtMakeThreadIOU(), rwtMakeThreadFunction()
attrtest: RWRunnableSelf, RWThread, RWThreadAttribute, RWThreadFunction, rwtMakeThreadFunction()
balance: rwtMakeThreadFunction(), RWRunnableTrap
cancella: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, RWCancellation
hello_g: RWThreadFunction, rwtMakeThreadFunction()
hello_m: RWThreadFunction, rwtMakeThreadFunction()
interupt: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, RWCancellation
iouescro: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, rwtMakeThreadIOU()
ioureslt: RWTThreadIOUFunction, rwtMakeThreadIOUFunction(), RWRunnableSelf
ioutrap: RWThreadFunction, rwtMakeThreadFunction(), RWTThreadIOUFunction, rwtMakeThreadIOUFunction(), RWRunnableSelf
prodcons: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, RWRunnableTrap
rnbltrap: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableTrap, RWRunnableSelf
servpool: RWTRunnableIOUFunction, rwtMakeRunnableIOUFunction(), RWRunnableSelf, rwtMakeThreadIOU(), RWServerPool
thrcreat: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf
threadid: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, RWRunnableTrap
thrlocal: RWThreadFunction, rwtMakeThreadFunction(), RWRunnableSelf, RWTThreadLocal, RWRunnableTrap
thrstate: RWThreadFunction, rwtMakeThreadFunction(), rwtMakeRunnableCallback(), RWRunnableSelf, RWCancellation
The scope and completeness of some examples in this guide are limited to insure readability and satisfy size constraints. For this reason, you should also review the example programs distributed with the Threading package. See the appendix on file locations in the Building Your Applications document (rcbbd) for the exact location of the examples for your build.
Example 1 creates a second thread of execution (main() is the first thread) and uses that thread to call a global function that prints the message "Hello World!" to the console.
#include <rw/rstream.h>
#include <rw/thread/RWThreadFunction.h>
#include <rw/thread/rwtMakeThreadFunction.h> // 1
void hello(void) // 2
{
cout << "Hello World!" << endl;
}
int main()
{
RWThreadFunction myThread = rwtMakeThreadFunction(hello); // 3
myThread.start(); // 4
myThread.join(); // 5
return 0;
}
|
| //1 | Include the header file containing the RWThreadFunction class declaration used in the example. |
| //2 | Define a global function to produce the message. |
| //3 | Use a Threading package global function to construct an RWThreadFunction runnable that executes the hello() function when started. That runnable object is bound to a local handle named myThread. |
| //4 | Start the runnable. This results in the creation of a new thread that then executes the hello() function. |
| //5 | Wait for the newly created thread to finish execution. |
The following sections take a closer look at some of the key components of this example.
In the Threading package, the runnable family of classes includes the basic mechanisms used to create, control, and monitor the threads of execution within your application. The RWThreadFunction class used in the example is a member of the runnable family; Section 3.3.1.1 shows its relationship to the other runnable classes.
All runnable objects have a start() member and a virtual run() member. The run() member defines the work or activity to be performed by the runnable object. The start() member defines the form of dispatching to be used in executing the run() member. The dispatching is performed either synchronously by executing within the calling thread, or asynchronously by creating a new thread. Regardless of the dispatching mechanism, the run() member is always executed as a consequence of calling start().
The RWThreadFunction class used in the example is one of the asynchronous or threaded runnable classes. Instances of this class create a new thread of execution when start() is called. The RWThreadFunction class uses a functor to indicate to the new thread what to execute after it starts; in this case, the hello() function.
See Section 3.5, "The Runnable Object Classes," for more information.
In the example, a convenience function called rwtMakeThreadFunction() constructs an RWThreadFunction instance. This "make" function is actually one of a family of template functions that uses the signature of a function to select, construct, and initialize an instance of the appropriate runnable class.
The rwtMakeThreadFunction() function call performs a two-step service. First, it constructs and initializes a functor object that is compatible with the specified function. Then, it uses the static make() function from RWThreadFunction to construct an RWThreadFunctionImp instance, passing it a handle to the newly constructed functor instance. For more information on make functions, see Section 3.5.2.1, "Global Template Functions."
In the following code segment, the rwtMakeThreadFunction() function is left out, and a functor and threaded runnable instance are explicitly constructed:
// Construct a functor that invokes hello RWFunctor0 myFunctor; // 1 myFunctor = rwtMakeFunctor0(NULL,hello); // 2 // Construct a runnable that invokes functor RWThreadFunction myThread; // 3 myThread = RWThreadFunction::make(myFunctor); // 4 |
| //1 | Construct a handle instance for a functor object. |
| //2 | Use another convenience function to construct and initialize a functor instance that is compatible with the hello() function. Bind that instance to the handle instance, myFunctor. |
| //3 | Construct an empty RWThreadFunction handle instance. |
| //4 | Construct and initialize an RWThreadFunctionImp body instance. Bind that instance to the handle instance, myThread. |
The code creates a threaded runnable that, when started, launches a thread that invokes the functor instance to execute the hello() function.
The rwtMakeFunctor0() function used in //2 is a template function that uses the signature of the function you list to select, construct, and initialize an instance of the appropriate functor class.
As with the runnable "make" functions, these functor "make" functions are included for convenience and might not be 100% portable. To use them, your compiler must be able to extract template argument types from a function signature.
The next section describes an alternative to the functor "make" functions.
If your compiler cannot handle these "make" functions, you can use a macro to replace the rwtMakeFunctor() function call with the equivalent code, as in Example 3.
// Construct functor that invokes hello RWFunctor0 myFunctor; // 1 myFunctor = rwtMakeFunctor0G(void,hello); // 2 |
| //1 | Constructs a handle instance for a functor object. |
| //2 | Constructs and initializes a functor body instance that is compatible with the hello() function. Binds that body instance to the handle instance, myFunctor. |
The macro can also be replaced with an explicit call to a static make function included by the functor body class:
myFunctor = RWTFunctor0GImp<void>::make(hello); |
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.