RWCancellation

Module:  Threads   Package:  Threading

                RWTHRxmsg
RWCancellation... 
                RWHandleBase

• Local Index
• Header File
• Description
• Example
• Public Constructors
• See Also

Members

RWCancellation()

#include <rw/thread/RWCancellation.h>

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.

#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();

   return 0;
}

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.

RWRunnable, rwServiceCancellation()

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.