Canceling a runnable is implemented by the following functions:

Cancellation is used to request a thread to exit a runnable. The cancellation operations are similar in function to the interrupt operations. Like the interrupt, cancellation is a synchronous process; a thread can only be canceled if it chooses to be.

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.

Threads Module has two types of requestCancellation() functions:

The requestCancellation() function returns one of the following:

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 10.

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 11 shows this approach.

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

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

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 12.

Each of these code fragments uses the global function rwRunnable() to retrieve a handle to the runnable that is the current source or active runnable of the calling thread. This handle is then used to call serviceCancellation(). This pair of statements may be replaced with the global function, rwServiceCancellation(), which combines these two operations into a single function.

Servicing cancellations can be very complicated when you are accessing thread-shared data that is protected by locks such as mutexes. If a runnable is canceled in the middle of acquiring and releasing locks on shared data, then the locks must also be released to prevent deadlock and the data must be set to a correct and consistent state.

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 13 demonstrates this concept.