3.5 The Runnable Object Classes

As explained in Section 3.4.2, "Introducing the Runnable," the runnable family of classes includes the basic mechanisms used to create, control, and monitor the threads of execution within your application.

In a synchronous runnable, the thread that calls start() is the same thread that executes run(); the flow of control is simply passed internally from the start() member to the run() member. By the time the start() function returns, the runnable has completed (or at least attempted to perform) its specified task, as shown in Figure 5.

Figure 5: Synchronous runnable

In a threaded runnable, a call to start() results in the creation of a new thread of execution, as shown in Figure 6. Following creation, this new thread proceeds to execute the run() member, freeing the thread that called start() to move on to other things.

Figure 6: Threaded runnable

In this guide, any thread that is currently executing within a runnable's run() member is commonly referred to as being inside that runnable. The Threading package allows only one thread at a time to be inside, or active, within a runnable. All other threads are considered to exist outside the runnable.

A functor is an object used to encapsulate a function call. Each functor keeps a pointer to the function and copies of the argument values that are to be passed to the function. Invoking a functor produces a call to the function.

The Functor package functors are an ideal mechanism for defining the work to be performed by a runnable. Each functor instance is invoked using a common, inherited interface that remains the same regardless of the actual function signature or argument values.

A functor-based runnable redefines the run() member to invoke a functor instance stored within the runnable. With this capability, you do not have to sub-class or use other intrusive techniques to customize the execution behavior of a runnable. The functor-base runnables allow you to dynamically specify the functions you want to execute when a runnable is started.

The functor-based runnables include:

• RWRunnableFunction — A synchronous runnable class that uses a functor to execute a function whose return value, if any, can be ignored.

• RWTRunnableIOUFunction — A synchronous class that uses a functor to execute a function whose return value is to be captured in an IOU. IOUs are a mechanism used to retrieve and wait for the result of an asynchronous operation. See Section 5.5, "The IOU Classes," of the Interthread Communication Package for more information.

• RWThreadFunction — An asynchronous, threaded runnable that creates a new thread to invoke a functor that executes a function whose return value, if any, can be ignored.

• RWTThreadIOUFunction — An asynchronous, threaded runnable that creates a new thread to invoke a functor that executes a function whose return value is to be captured in an IOU.

For more information on functor-based runnables, see Section 3.5.2, "Creating Functor-based Runnables." For more information on functors, see Chapter 8, "The Functor Package."

In addition to the functor-based runnable classes, the Threading package also has runnable classes that accept other runnable objects for execution. This type of runnable is called a runnable server.

A runnable server is a threaded runnable that accepts and queues any number of runnable objects and executes them within its own internal thread or threads. The runnable server classes are:

• RWRunnableServer

• RWServerPool

These classes are covered in detail in Section 3.6, "The Server Classes."

Functors are covered in detail in Chapter 8, "The Functor Package."

You can choose a global template function that relies on the compiler to extract the signature of a function you specify, allowing it to select, construct, and initialize an appropriate functor and runnable class instance. This style is illustrated in Example 4.

Example 4: Creating a functor-based runnable with a global template function

void hello(void); RWThreadFunction myThread = rwtMakeThreadFunction(hello);

As explained in Section 3.4.3, "Runnable Make Functions," rwtMakeThreadFunction(), is one function in a family of template functions.

The templatized make functions for runnables can accept a global, static, or member function with zero to three arguments and any return type. You can access lists of these functions under Threads Module on the Modules tab of the SourcePro C++ API Reference Guide for a complete list of these functions.

• RWRunnableFunction — rwtMakeRunnableFunction()

• RWTRunnableIOUFunction — rwtMakeRunnableIOUFunction()

• RWThreadFunction — rwtMakeThreadFunction()

• RWTThreadIOUFunction — rwtMakeThreadIOUFunction()

You can choose a macro that takes an explicit definition of a function signature and use it to select, construct, and initialize an appropriate functor and runnable class instance:

RWThreadFunction myThread = rwtMakeThreadFunctionG(void,hello);

The runnable "make" macros are intended as compromise between the easy-to-use templatized make functions with their potential portability problems and the more complex coding required for explicit, low-level instantiation and construction.

The macros use names quite similar to the names used by the templatized make functions, except for the addition of a character sequence that is used to encode and identify the function type and number of arguments accepted by the macro. This sequence consists of the following elements:

• A single letter indicating the function type:

• G — The function is a global or static class member function.

• M — The function is a non-static class member function.

• An optional two letter code describing the number of arguments (if one of the following does not appear, then the function takes no arguments):

• A1 — One argument.

• A2 — Two arguments.

• A3 — Three arguments.

The following macros show how this encoding relates to the macro parameter list.

• rwtMakeRunnableFunctionG(R,function)R — the function return type name (void, for example)function — a pointer to a global function with the signature R (*)(void)

• rwtMakeThreadFunctionMA1(Callee,callee,R,function,A1,a1)

  Callee, the class name containing the member function

  callee, a reference to a Callee class instance

  R, the member function return type

  function, a member function pointer with a signature

  R (Callee::*)(A1) A1, the type name of the function argument

  a1, the argument value that is to be passed to the function at invocation

Each of these macros returns a handle of the type indicated by the macro name. The first macro returns an RWRunnableFunction handle, while the second returns an RWThreadFunction handle.

You can access lists of these macros under Threads Module on the Modules tab of the SourcePro C++ API Reference Guide.

You can choose to construct your own functor instance and pass it to one of the static make() functions in the runnable handle class, as shown in Example 5.

Example 5: Creating a functor-based runnable with a static make function

RWFunctor0 myFunctor; myFunctor = rwtMakeFunctor0(NULL,hello); // Use functor "make" // function RWThreadFunction myThread; myThread = RWThreadFunction::make(myFunctor);

All of the runnable handle classes, except for RWRunnableSelf and RWThreadSelf, have static make() functions for constructing the corresponding runnable object.

The functor-based runnable classes each have a make() function that accepts a handle to a functor instance. If you use these functions, you need to construct your own functor instance, and pass a handle for that instance to the make function.

The threaded runnable classes have make() functions that can also take an RWThreadAttribute instance for use in controlling the attributes of any threads created by the runnable.

You can access lists of these functions under Threads Module on the Modules tab of the SourcePro C++ API Reference Guide.

---

Many of these operations rely on or make changes to the execution or completion state of a runnable. To help you better understand these relationships, study the state diagrams in Figure 7 and Figure 8 and use them as a reference as you read.

---

• RW_THR_INITIAL — The initial state is used to indicate when a runnable is inactive. A runnable is created in the initial state and always returns to the initial state after it completes execution.

• RW_THR_STARTING — A runnable temporarily enters the starting state after start() is called and remains in that state until the runnable is ready to execute its internal run() member.

• RW_THR_RUNNING — The runnable is active and executing inside its run() member.

• RW_THR_INTERRUPTED — The runnable is active, but has been interrupted, and is currently waiting to be released from the interrupt.

• RW_THR_SUSPENDED — The threaded runnable is active, but its thread has been suspended, and is waiting to be resumed.

• RW_THR_CANCELING — The runnable is active, but is currently attempting cancellation.

• RW_THR_ABORTING — The runnable is active and has aborted an attempted cancellation.

• RW_THR_SLEEPING — The runnable is active, but its thread is currently sleeping.

• RW_THR_YIELDING — The runnable is active, but its thread is currently yielding execution.

• RW_THR_SERVER_WAIT — The runnable server is active, but is currently waiting for another runnable to be enqueued for execution.

• RW_THR_EXCEPTION — The runnable is exiting because an exception was produced.

• RW_THR_TERMINATING — The runnable is being terminated by another thread.

Figure 7 demonstrates the various execution state transitions.

Figure 7: Execution state transitions

• RW_THR_PENDING: The runnable has not been started since it was created, or the runnable is currently active. The completion state is reset to RW_THR_PENDING each time start() is called.

• RW_THR_NORMAL: The runnable completed execution normally.

• RW_THR_FAILED: The runnable exited with an exception.

• RW_THR_CANCELED: The runnable was canceled.

• RW_THR_TERMINATED: The thread executing the runnable was terminated.

Figure 8 demonstrates the various completion state transitions.

Figure 8: Completion state transitions

As stated earlier, the runnable is the central mechanism for creating, controlling, and monitoring threads of execution. All runnable objects inherit a common set of operations and capabilities that support these activities. These operations are listed below and described in detail in the following sections:

• Section 3.5.5, "Starting a Runnable."

• Section 3.5.6, "Joining a Runnable."

• Section 3.5.7, "Monitoring the Completion State of a Runnable."

• Section 3.5.8, "Catching and Rethrowing Exceptions."

• Section 3.5.9, "Interrupting a Runnable."

• Section 3.5.10, "Canceling a Runnable."

• Section 3.5.11, "Sleeping."

• Section 3.5.12, "Yielding Execution."

• Section 3.5.13, "Suspending and Resuming Execution."

• Section 3.5.14, "Terminating Execution."

• Section 3.5.15, "Monitoring the Execution State of a Runnable."

• Section 3.5.16, "Execution Nesting."

• Section 3.5.17, "Thread Identification."

A synchronous runnable does not create its own thread to accomplish its tasks. It must use, or borrow, the thread that calls start() to execute the run() member. It is designed to pass control from the start() function to the internal run() function after performing any necessary initialization tasks.

Because run() is executed synchronously, start() cannot return control to its caller until run() returns control. This process is explained in the following steps and is illustrated in Figure 9.

Figure 9: Start operation for synchronous runnables — interaction and timing

You can start a synchronous runnable any number of times, but only one thread at a time can execute the encapsulated function within the runnable. If a second thread attempts to start a runnable that is currently being executed by another thread, the start() function produces an RWTHRThreadActive exception.

You can use the completion state value returned from the start() function to determine whether or not the runnable ran to completion. The start() function returns the following completion states:

• RW_THR_NORMAL if the runnable ran to completion.

• RW_THR_FAILED if an exception was produced.

• RW_THR_CANCELED if the runnable was canceled by another thread.

The code fragment in Example 6 shows how to check for completion states.

Example 6: Checking a runnable's completion state

switch(runnable.start()) { case RW_THR_NORMAL: // The runnable ran to completion ... break; case RW_THR_FAILED: // The runnable exited with an exception ... break; case RW_THR_CANCELED: // The runnable was canceled during execution ... break; }

An asynchronous, threaded runnable creates its own thread to accomplish its tasks. When you call RWRunnable::start(), the runnable launches a new thread to execute the run() member. The process is explained in the following steps and is illustrated in Figure 10.

1. When first constructed, a threaded runnable object is initialized with an execution state of RW_THR_INITIAL[1] and a completion state of RW_THR_PENDING{1}.

2. The runnable enters an execution state of RW_THR_STARTING[2] before creating the new thread. The starting thread requests and waits for the new thread to interrupt.

   The interrupt occurs before the new thread enters its run() member. This step insures that the thread doing the starting does not return from the start() function until the new thread completes any necessary initialization. Once the new thread is interrupted, the Threading package sets the initial scheduling policy and priority for the thread.

3. Once the new thread begins execution, it attempts to service the interrupt request. This causes the execution state to change to RW_THR_INTERRUPTED[7].

4. The start policy of the runnable is evaluated. Depending on the current policy setting, the new thread is either left in the interrupted state or released. In either case, the start() function returns control to the calling thread.

a.	If the threaded runnable has a start policy value of RW_THR_START_INTERRUPTED, the start() function returns without releasing the interrupt.
b.	If the threaded runnable has a start policy of RW_THR_START_RUNNING, the interrupt is released by the starting thread, the execution state is changed to RW_THR_RUNNING[9] state, and the start() function returns a completion state of RW_THR_PENDING to the calling thread. For more information about the start policy and other thread attributes, see Section 3.9, "Thread Attributes."

5. Once a runnable's thread successfully completes its activities and returns from the run() function, the runnable's execution state is changed to RW_THR_INITIAL[4] and its completion state is set to RW_THR_NORMAL{2}.

6. If an exception thrown from within the run() member is successfully caught within the runnable, the completion state changes to RW_THR_FAILED{3} and the execution state briefly changes to RW_THR_EXCEPTION[5] before changing back to the RW_THR_INITIAL[6] state.

Figure 10: Start operation for threaded runnables — interaction and timing

The completion state value returned from the start() function can be used to distinguish between a synchronous runnable and a threaded runnable, as shown in Example 7. The start() function on a synchronous runnable always returns a completion state of RW_THR_NORMAL, RW_THR_FAILED, or RW_THR_CANCELED. Threaded runnables always return RW_THR_PENDING.

Example 7: Using completion state to distinguish synchronous from threaded runnables

void executeRunnable(RWRunnable& runnable) { RWCompletionState result; if (RW_THR_PENDING == (result = runnable.start())) { // Threaded Runnable ... } else { // Synchronous Runnable ... } }

You can restart a threaded runnable, but only after the thread created by the previous call to start() has exited. Any attempt to call start() on a threaded runnable that already has an active thread results in an RWTHRThreadActive exception.

Figure 11 shows the timing-sequence and state changes associated with the join operation.

Figure 11: Join operation — interaction and timing

The Threading package has two types of join functions:

• One waits indefinitely for the runnable to complete execution.

• One accepts a time-limit for the wait.

Several functions in the Threading package accept a timeout value. This value is meant to specify the amount of "wall-clock" time, in milliseconds, that a function waits before timing out.

---

In some situations, functions that accept a timeout value actually measure duration by the amount of CPU time used, not by the elapsed wall-clock time.

---

This may result in longer timeout periods than are expected or intended. In these situations, the amount of delay is directly proportional to the percentage of available CPU time granted to the process.

The code segment in Example 8 illustrates both types of join functions.

Example 8: Joining runnables in two ways

// Create a threaded runnable RWThreadFunction myThread = ... // Start the runnable myThread.start(); // Wait 1000 msecs (1 second) for the runnable's thread to exit. if (RW_THR_TIMEOUT == myThread.join(1000)) { // The runnable did not finish within one second! // Now wait as long as it takes... myThread.join(); }

If you join a runnable that has never been started, the join() function waits for the runnable to start and complete. If you join a runnable that is currently inactive, but has already been started previously, the join() function returns immediately. To wait for the next completion on a runnable that has already completed one or more executions, you need to delay until after the runnable has been restarted, as indicated by the RW_THR_STARTING execution state or by a completion state of RW_THR_PENDING.

• The completion state for a runnable that has not yet been started or not yet completed is RW_THR_PENDING.

• If the runnable completion state is RW_THR_FAILED, an exception was thrown within the runnable. You can rethrow the exception by calling the RWRunnable::raise() member. The raise function can be called at any time, and does nothing if no exception has been captured by the runnable.

• If the completion state is RW_THR_CANCELED, the runnable was successfully canceled, either by another thread, or of its own accord.

• A completion state of RW_THR_TERMINATED indicates that the runnable's active thread was terminated.

You should test for an exception each time you successfully join with a runnable, as shown in Example 9.

Example 9: Testing for an exception after joining with a runnable

RWThreadFunction myThread = ...; try { myThread.start(); // Start the runnable myThread.join(); // Join the runnable myThread.raise(); // Rethrow any exception that was caught! } catch(RWTHRxmsg& msg) { cout << "Exception! " << msg.why() << endl; }

The type of exception that is rethrown by a runnable might not match the original exception class that was thrown or caught.

• If the exception is based on the RWTHRxmsg class, then the exception rethrown by raise() is of the same class as the one captured.

• Exceptions based on the RWxmsg (or xmsg) class are rethrown as an RWxmsg with the same message value as the captured exception.

• Any other type of exception is rethrown as an RWTHRxmsg with a generic message stating that the captured exception was of an unrecognized type.

When designing code that you expect to execute inside a Threading package runnable, you might want to use the RWTHRxmsg class as a base class for your exceptions. An exception derived from this class can be caught as an RWTHRxmsg, copied for storage using a virtual clone() function, and later "reconstituted" using a virtual raise() function defined by the class. This store-and-forward capability allows a runnable to capture and rethrow an exception.

The Threading package includes a template called RWTTHRCompatibleException, which can convert an existing exception class into an RWTHRxmsg-compatible exception.

Figure 12 shows the timing-sequence and state changes associated with various interrupt operations.

Figure 12: Interrupt operations — interactions and timing

To interrupt a runnable from another thread, you need to call the RWRunnable function, requestInterrupt(). This function increments an interrupt count maintained within the runnable instance and waits for the runnable to interrupt.

To complete the interrupt request, the thread executing inside the runnable must call the serviceInterrupt() function provided by the RWRunnableSelf handle class. This function blocks the calling thread as long as one or more outstanding interrupt requests exist.

Prior to blocking, the interrupted thread sets the execution state to RW_THR_INTERRUPTED[8]. This state change signals acknowledgment to all of the threads that requested an interrupt. The interrupted thread remains blocked inside the serviceInterrupt() routine until signaled that all acknowledged interrupt requests have been released. The serviceInterrupt() function returns true if the caller was interrupted by the call and false otherwise.

An interrupt can be used to shutdown a continuous, iterative process by using the serviceInterrupt() routine to control the process iteration, as in Example 10.

Example 10: Using an interrupt to shut down a continuous process

. . . RWRunnableSelf self = rwRunnable(); // Perform iterative operation until interrupted... while(!self.serviceInterrupt()) { // Perform operation } // Operation interrupted! . . .

You can cause a runnable to interrupt itself by using the interrupt() method in the RWRunnableSelf class. This allows you to implement rendezvous or barrier synchronization. A rendezvous defines a meeting point between two threads. The thread that arrives at the meeting point first must wait for the other thread to arrive before continuing.

Example 11 shows how to use the interrupt() and requestInterrupt() calls to implement a simple rendezvous. The thread on one side of the rendezvous uses interrupt() to block itself while waiting for the other thread to arrive:

Example 11: Implementing a simple rendezvous between threads

RWRunnableSelf self = rwRunnable(); while(/*condition*/) { ... // Do something useful... ... // Rendezvous with the other thread // Wait here until the other thread releases the interrupt! self.interrupt(); }

The thread on the other side of the rendezvous uses requestInterrupt() to block while waiting for the other thread to arrive:

// "other" points to the runnable containing the other thread while(/*condition*/) { ... // Do something useful... ... // Rendezvous with the other thread // Wait here until the other thread interrupts! if (RW_THR_ACQUIRED == other.requestInterrupt()) // Must release twice because the thread was // interrupted twice { other.releaseInterrupt(); other.releaseInterrupt(); } }

The threads created by the threaded runnable classes can also be interrupted at startup by using an RWThreadAttribute instance to specify a start policy of RW_THR_START_INTERRUPTED. The releaseInterrupt() function must be used to release any thread interrupted in this manner.

To cancel a runnable from another thread, you need to call the RWRunnable function, requestCancellation(). This function sets a flag maintained within the runnable instance, and waits for the runnable to complete cancellation.

To complete the cancellation request, the thread executing inside the runnable must call the serviceCancellation() function provided by the RWRunnableSelf handle class. If there is an outstanding cancellation request, this function throws an RWCancellation exception object; otherwise the function simply returns to the caller. A thrown cancellation object notifies the current runnable that cancellation has started, causing the runnable's execution state to change to RW_THR_CANCELING[10].

At this point, the C++ exception processing begins unwinding the call-stack until an exception handler is found for the RWCancellation object. If the code that was executing inside the runnable does nothing to stop the unwind, the cancellation exception propagates all the way back out of the runnable's run() member and into exception-handling code inside the runnable class. If this happens, the cancellation process concludes, and the requesting thread is notified that cancellation has completed successfully.

When a runnable is canceled, its completion state is changed to RW_THR_CANCELED{4}, its execution state is reset back to the RW_THR_INITIAL[11], and an RWTHROperationCanceled exception is stored for retrieval by raise().

The cancellation process can be aborted by catching the RWCancellation exception object before it can propagate back into the runnable. When the cancellation object is destroyed, it automatically notifies the current runnable that the cancellation process has been aborted. The abort notification causes the runnable to enter the RW_THR_ABORTING state and the RW_THR_RUNNING state. The RW_THR_ABORTING state is used to signal any waiting threads that the cancellation process was aborted.

• RW_THR_COMPLETED if the runnable was successfully canceled, exited, or was not active in the first place.

• RW_THR_ABORTED if the cancellation process was started, but the RWCancellation exception object was not allowed to propagate back to the runnable class.

• RW_THR_TIMEOUT if the request was time-limited and the runnable failed to complete cancellation within the allotted time.

Once a canceled runnable begins the cancellation process, it continues that process even if the original request for cancellation times out.

A cancellation request cannot be undone; once a runnable is marked for cancellation it stays marked until it exits. An aborted cancellation is restarted the next time serviceCancellation() is called.

The Threads Module synchronization classes can automatically service cancellation requests before performing any operation that may result in blocking the calling thread.

To use this capability, a synchronization object must have its cancellation processing enabled. You can do this when the synchronization object is constructed by passing the appropriate RWCancellationState value to the constructor. The default cancellation state of a synchronization object is RW_CANCELLATION_DISABLED. You can override that default, however, by specifying RW_CANCELLATION_ENABLED when you construct the synchronization instance, as shown in Example 12.

Example 12: Constructing synchronization objects to automatically service cancellation requests

RWMutexLock mutex(RW_CANCELLATION_ENABLED); try { mutex.acquire(); // May throw cancellation! } catch(RWCancellation&) { // Do something about it! }

Except when using nested lockguards, you can also enable synchronization cancellation processing by using the setCancellation(RWCancellationState) member function provided by RWSynchObject class, the base class for all synchronization mechanisms in Threads Module. Example 13 shows this approach.

Example 13: Setting synchronization objects to automatically service cancellation requests

RWMutexLock mutex; // Defaults to disabled! mutex.setCancellation(RW_CANCELLATION_ENABLED); try { mutex.acquire(); // May throw cancellation! } catch(RWCancellation&) { // Do something about it! }

Figure 13 shows the interaction and state changes associated with the cancellation process.

Figure 13: Cancel operations — interaction and timing

If you want to support cancellation in your application, you need to design your code to allow for the propagation of the RWCancellation object:

• Exception specifications for functions, if used, must include the RWCancellation or RWTHRxmsg exceptions.

• Your catch(...) blocks must rethrow the original exception.

• Any block that explicitly catches an RWCancellation or RWTHRxmsg exception must rethrow the original exception, or rethrow the instance that was caught.

Throwing a new exception instance results in the destruction of the original RWCancellation instance, effectively aborting the cancellation process.

These coding guidelines are illustrated in the code fragments in Example 14.

Example 14: Supporting cancellation in an application

void function1() throw(RWCancellation) { RWRunnableSelf self = rwRunnable(); try { self.serviceCancellation(); } catch(RWCancellation&) { // Cancellation occurred! throw; // Rethrow the original instance } } void function2() throw(RWTHRxmsg) { RWRunnableSelf self = rwRunnable(); try { self.serviceCancellation(); } catch(RWTHRxmsg& msg) { // Catch by reference! // An RWTHRxmsg exception occurred! throw msg; // Rethrow the instance caught } } void function3() // No spec! { RWRunnableSelf self = rwRunnable(); try { self.serviceCancellation(); } catch(...) { // Catches anything // Some exception occurred! throw; // Rethrow the original instance } }

For this reason, when using nested lockguards, avoid using the function RWMutexLock::setCancellation(RWCancellationState). Instead, before each attempt to acquire the mutex, use ::rwServiceCancellation() to service cancellation requests. To do otherwise may cause your attempts to acquire the mutex to fail, because the mutex is already canceled. This may cause your program to terminate, due to assertion errors. Example 15 demonstrates this concept.

Example 15: Serving cancellation requests with nested lockguards

#include <rw/thread/RWRunnableSelf.h> #include <rw/thread/RWThread.h> #include <rw/thread/RWCancellation.h> #include <rw/thread/rwtMakeThreadFunction.h> #include <rw/sync/RWMutexLock.h> #include <iostream.h> void func1(void) { RWMutexLock _mutex; ::rwServiceCancellation(); // Don't use // _mutex.setCancellation(); // Instead, service cancellations // before attempting to acquire the // mutex. RWLockGuard<RWMutexLock> lock(_mutex); // Acquire the mutex. rwSleep(1); { RWUnlockGuard<RWMutexLock> unlock(_mutex);// Release the mutex. cout << "going to sleep..." << endl; rwSleep(1500); cout << "waking up..." << endl; ::rwServiceCancellation(); // Service cancellations before you // attempt to acquire the mutex. } // Acquire the mutex. cout << "Everything was successful" << endl; } // Release the mutex. void main(void) { RWThread thr1 = rwtMakeThreadFunctionG(void, func1); thr1.start(); rwSleep(100); cout << "requesting cancellation..." << endl; thr1.requestCancellation(); cout << "cancellation request returned." << endl; }

• void RWRunnableSelf::sleep(unsigned long milliseconds)

  The RWRunnableSelf::sleep() function can be called by a thread running inside of a runnable object. This function sets the runnable execution state to RW_THR_SLEEPING[14] and then enters a blocking wait until the specified period of time has passed. Once the time-period has elapsed, the thread is unblocked and becomes eligible for execution. The runnable is returned to the RW_THR_RUNNING[15] once the thread begins executing again.

• void rwSleep(unsigned long milliseconds)

  The global rwSleep() function can be called by any thread, regardless of whether or not it originated or is executing within a runnable object. This function is identical to the sleep() function except that it causes no changes in the execution state of a runnable.

• void RWRunnableSelf::yield(void)

  The RWRunnableSelf::yield() function can be called by a thread running inside of a runnable object. This function sets the runnable execution state to RW_THR_YIELDING[16] before yielding execution. The execution state is reset to RW_THR_RUNNING[17] once the thread begins executing again.

• void rwYield(void)

  The global rwYield() function can be called by any thread, regardless of whether or not it originated or is executing within a runnable object. This function is identical to the yield() function except that it causes no changes in the execution state of a runnable.

• bool RWThread::canSuspendResume(void) const

• bool RWThreadSelf::canSuspendResume(void) const

• unsigned RWThread::suspend()

• void RWThreadSelf::suspend()

• unsigned RWThread::getSuspendCount() const

• unsigned RWThread::resume()

• Any attempt to suspend an inactive, threaded runnable results in an RWTHRThreadNotActive exception.

• Any attempt to resume a threaded runnable that is not suspended results in an RWTHRThreadActive exception.

Figure 14 shows the interaction and state changes associated with the suspension process.

Figure 14: Suspend and resume operations — interaction and timing

To suspend a thread created by a threaded runnable, use the suspend() function included by the RWThread handle class. A thread inside a threaded runnable can suspend itself by calling the RWThreadSelf::suspend() function.

Suspension is not supported in all environments. The Threading package uses the macro RW_THR_CAN_SUSPEND_RESUME to indicate whether the suspend(), resume(), and getSuspendCount() operations are available. If this macro is not defined, the functions throw an RWTHROperationNotSupported exception. You can also determine whether suspension is supported at run-time by calling the canSuspendResume() function in the RWThread and RWThreadSelf classes.

To determine the instantaneous execution state of a runnable, use the getExecutionState() function in the RWRunnableHandle class. This function returns one of the values defined by the RWExecutionState enumerated type, which are listed in Section 3.5.3, "Runnable State."

You should not use the getExecutionState() function to poll for runnable state changes. A polling loop using this function is unreliable because the runnable could conceivably make several state transitions between any two calls to this function. Also, the execution state retrieved might not reflect the current state of the runnable because the runnable might have shifted to another state by the time you can act on the value returned.

The Threading package has two mechanisms for monitoring execution state changes:

• A pair of runnable wait functions that you can use to make the calling thread wait until the runnable enters an execution state of interest.

• A callback mechanism that allows you to register one or more functors as callbacks to be invoked when the corresponding runnable enters a targeted execution state.

Using Server Classes. The wait functions are useful for detecting state changes in a runnable that has been passed to another thread for execution. The runnable server classes (discussed in Section 3.6, "The Server Classes,") accept runnable instances for execution within the server's thread or threads.

Example. The application code that creates a runnable and passes it to a server class instance might need to know when the runnable began executing. This is accomplished by using one of the wait functions, as shown in Example 16.

Example 16: Using a wait function to detect state changes in a runnable

#include <rw/thread/rwRunnable.h> #include <rw/thread/rwtMakeRunnableFunction.h> #include <rw/thread/RWRunnableSelf.h> #include <rw/thread/RWServerPool.h> #include <rw/rstream.h> void hello() { RWRunnableSelf self = rwRunnable(); do { cout << "Hello World!" << endl; } while(!self.serviceInterrupt()); } void main() { // Create and start a server pool instance RWServerPool server = RWServerPool::make(3); server.start(); // Create and enqueue a runnable that says hello! RWRunnable runnable = rwtMakeRunnableFunctionG(void,hello); server.enqueue(runnable); // Wait for the runnable to start executing runnable.wait(RW_THR_RUNNING); // OK, that's enough of that! if (RW_THR_ACQUIRED == runnable.requestInterrupt()) runnable.releaseInterrupt(); // Shutdown the server pool server.stop(); server.join(); }

Callbacks are specified using functors. The functors used for callbacks are based on a different functor class family than those specified for execution within a runnable. These functors are passed the runnable and the current execution state when invoked. This allows the callback function to determine the source and state of each callback invocation. Any function that you create for use as an execution state callback can accept additional arguments and must accept the two values shown in Example 17 as its first two arguments.

Example 17: Creating a function for an execution state callback

void myCallback(const RWRunnable& runnable, RWExecutionState state) { // Do something useful }

To use your function as a callback, construct a compatible functor instance that calls the function when invoked, as shown in Example 18.

Example 18: Using a function as a callback

RWTFunctor2<const RWRunnable&,RWExecutionState> myFunctor; myFunctor = rwtMakeFunctor2G(const RWRunnable&, RWExecutionState, void, myCallback, const RWRunnable&, RWExecutionState);

For more information on using and constructing functors, see the Functor page accessible from the Modules tab of the SourcePro C++ API Reference Guide.

• An RWTFunctor2 instance.

• An execution state mask value.

• An RWCallbackScope enumerated value that tells the runnable whether the callback should be invoked just once and deleted (RW_CALL_ONCE), or invoked as many times as the execute state requires to satisfy the mask (RW_CALL_REPEATEDLY).

Example 19: Registering a callback

RWRunnable runnable = ...; // Register callback that will be invoked each time the // the runnable is started or completes execution... runnable.addCallback(myFunctor, RW_THR_INITIAL | RW_THR_RUNNING, RW_CALL_REPEATEDLY);

The callbacks for most state changes are invoked and executed by the thread running inside a runnable, but some state change callbacks are invoked by threads that are manipulating the runnable to bring about a change in execution state.

The Threading package does not specify which thread executes a callback because this can change in future versions of the library. You have to explicitly test to see if the calling thread is associated with the source runnable using the threadId() and rwThreadId() functions, as shown in Example 20.

Example 20: Testing a calling thread's identity

void myCallback(const RWRunnable& runnable, RWExecutionState state) { // Are we executing in the runnable's active thread? if (runnable.threadId() == rwThreadId()) // This is the runnable's thread! else // This is some other thread! }

You should take care to avoid making changes in the execution state of a runnable from within a callback function. The Threading package does not prohibit attempts to do so, but the results of such an operation can produce undesirable behavior or result in deadlock.

To simplify the creation of callback functors, the Threading package also has a family of template functions and macros that take care of instantiating the appropriate RWFunctor2 implementation class. By using the rwtMakeRunnableCallback() template function, the previous code fragments can be replaced with the code in Example 21.

Example 21: Creating a callback functor with a make function

runnable.addCallback(rwtMakeRunnableCallback(myCallback), RW_THR_INITIAL | RW_THR_RUNNING, RW_CALL_REPEATEDLY);

---

As with the other convenience functions in the Threading package, the template "make" functions might not be 100% portable.

---

If your compiler is unable to handle the use of these template functions, you need to use the equivalent macros or explicitly code the functor instantiation as done in the earlier example. For more information on using these callback functor make functions and macros, see Threads Module on the Modules tab of the SourcePro C++ API Reference Guide.

The same functor can be registered as a callback on any number of runnables. The runnable handle passed as an argument at invocation can be used to identify the source of the callback. The same functor can also be registered more than once on a single runnable, but you should not have a reason for doing this.

The rwThread() function can be used to get a handle to the threaded runnable that originated the calling thread. If the calling thread was not started by a Threading package runnable class, as is the case with the main thread, then the handle returned by this function is empty. Whenever the source of a thread is in question, you should use the isValid() function to test the handle returned by rwThread() before using it, as shown Example 22.

Example 22: Testing the source of a thread

RWThreadSelf thread = rwThread(); if (thread.isValid()) { // OK, this thread was created by a runnable }

When a thread created by a threaded runnable starts a synchronous runnable, the thread eventually enters the run() member of that runnable. At that point, the thread is considered to be executing inside of the synchronous runnable as well.

In this situation, the synchronous runnable is nested inside of the threaded runnable. A nested runnable registers itself with the enclosing parent runnable for the purpose of supporting cancellation and other operations.

Starting a threaded runnable from within another runnable does not produce a nesting relationship because the threaded runnable launches its own thread of execution. No nesting relationship is formed when a synchronous runnable is started by a thread that does not originate from a Threading package runnable.

When a parent runnable is canceled, the cancellation request uses the nested runnable information to recursively propagate the request down to the innermost nested runnable. In the present version of the Threading package, cancellation is the only operation that propagates in this manner.

The Threading package encapsulates the underlying thread id using the RWThreadId class. Instances of this class can be used just as if they are instances of the underlying thread id type. That's because the RWThreadId class defines constructors and conversion operators that allow it to be used in this manner. For more information about this class, see the SourcePro C++ API Reference Guide.

---

The RWThreadId class is in the Synchronization package.

---

You can get the thread id of the thread executing inside a runnable by calling the runnable's RWRunnableHandle::threadId() member. If the runnable does not have an active thread, then threadId() throws an RWTHRThreadNotActive exception.

You can use the Synchronization package rwThreadId() function to retrieve the id of the current or calling thread. Any thread can call this function, not just threads created by the library.

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.