RWCancellation Class Reference
[Threading]

Represents an exception that is thrown to cancel a thread. More...

#include <rw/thread/RWCancellation.h>

Inheritance diagram for RWCancellation:

List of all members.

Public Member Functions
virtual void	raise (void) const
virtual RWTHRxmsg *	clone (void) const
	RWCancellation (RWRunnableImp *runnableImpP)
	RWCancellation (const RWCancellation &second)
Protected Member Functions
RWCancellationImp &	body (void) const

---

Detailed Description

RWCancellation is an exception that 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 an application 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 RWRunnableSelf::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 RWRunnableSelf::serviceCancellation().

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

Examples

 #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;
 }

See also:

RWRunnable, rwServiceCancellation()

---

Constructor & Destructor Documentation

RWCancellation::RWCancellation

(

RWRunnableImp *

runnableImpP

)

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

RWCancellation::RWCancellation

(

const RWCancellation &

second

)

[inline]

Copy constructor. Required for exception propagation.

---

Member Function Documentation

RWCancellationImp& RWCancellation::body

(

void

)

const [protected]

Gets a reference for the body instance, if any.

Exceptions:

RWTHRInvalidPointer

Thrown if this handle is not attached to a body.

Reimplemented from RWHandleBase.

virtual RWTHRxmsg* RWCancellation::clone

(

void

)

const [virtual]

Calls the copy constructor of the runtime (derived) type of self and returns the result.

Reimplemented from RWTHRxmsg.

virtual void RWCancellation::raise

(

void

)

const [virtual]

Throws an exception of the runtime (derived) type of self.

Reimplemented from RWTHRxmsg.