RWCancellation


                 RWTHRxmsg
RWCancellation... 
                 RWHandleBase

Data Type and Member Function Indexes
Package
Header File
Description
Example
Constructors
See Also

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

None

Package

Threading

Header File

#include <rw/thread/RWCancellation.h>

Description

RWCancellation is an exception which is thrown to cancel a thread. It may be caught by the thread in order to clean up resources or perform final shutdown operations. Thread cancellation allows one to stop a thread at a safe point in its execution. Thread cancellation is especially useful for stopping threads that are executing in infinite loops.

A thread is cancelled when an external thread calls requestCancellation() on the RWRunnable object. The thread cancellation starts when RWRunnable::serviceCancellation() is called from within the cancelled thread. If cancellation has been requested on that thread, via RWRunnable::requestCancellation(), then an RWCancellation exception is thrown out of RWRunnable::serviceCancellation().

RWRunnable::serviceCancellation() will also be called implicitly from within the acquire() or wait() methods of a synchronization object, when that synchronization object has been initialized with RW_CANCELLATION_ ENABLED. A global function called rwServiceCancellation() may also be used as a substitute for RWRunnable::serviceCancellation() member function.

Example

#include <rw/thread/RWThreadFunction.h> // for RWThreadFunction
#include <rw/thread/RWRunnableSelf.h>   // for ::rwThread() and
                                        // ::rwSleep
#include <rw/thread/RWCancellation.h>   // for RWCancellation
#include <rw/sync/RWMutexLock.h>        // for RWMutexLock

RWMutexLock cancelEnabledMutex(RW_CANCELLATION_ENABLED);
void func(void) {
   RWRunnableSelf currentRunnable = ::rwRunnable();
   try {
      while (1) {
         // Check to see if cancellation has been requested. 
         // If it has, then an RWCancellation exception 
         // will be thrown.
         currentRunnable.serviceCancellation();
         // - OR -
         cancelEnabledMutex.acquire();
         // - OR -
         rwServiceCancellation(); 

         // ...
      }
   }
   catch (RWCancellation&) {
      // thread canceled, do any necessary clean up 
      
      throw;  // rethrow
   }
}
 
main() {
   RWThread t = rwtMakeThreadFunction(func);
   t.start(); 
   ::rwSleep(100); // wait 100 milliseconds 
   t.requestCancellation();
}

Constructors

RWCancellation(RWRunnableImp* runnableImpP);

Construct a cancellation instance that is targeted at the specified runnable.

RWCancellation(const RWCancellation& second);

The copy constructor. Required for exception propagation.