RWCancellation Class Reference

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

#include <rw/thread/RWCancellation.h>

Inheritance diagram for RWCancellation:

Public Member Functions
	RWCancellation (const RWCancellation &second)
	RWCancellation (RWRunnableImp *runnableImpP)
virtual RWTHRxmsg *	clone (void) const
virtual void	raise (void) const
Public Member Functions inherited from RWTHRxmsg
	RWTHRxmsg (const RWCString &msg)
	RWTHRxmsg (const RWTHRxmsg &second)
	RWTHRxmsg (void)
virtual	~RWTHRxmsg (void)
RWTHRxmsg &	operator= (const RWTHRxmsg &second)
Public Member Functions inherited from RWxmsg
	RWxmsg (const char *msg)
	RWxmsg (const RWxmsg &msg)
	RWxmsg (RWxmsg &&msg)
RWxmsg &	operator= (const RWxmsg &)
RWxmsg &	operator= (RWxmsg &&msg)
void	swap (RWxmsg &rhs)
virtual const char *	why () const
Public Member Functions inherited from RWHandleBase
bool	isValid (void) const

Additional Inherited Members
Protected Member Functions inherited from RWxmsg
	RWxmsg (const char *msg, bool doCopy)
Protected Member Functions inherited from RWHandleBase
	RWHandleBase (const RWHandleBase &second)
	RWHandleBase (RWBodyBase *body)
	RWHandleBase (RWStaticCtor)
	RWHandleBase (void)
	~RWHandleBase (void)
RWBodyBase &	body (void) const
RWHandleBase &	operator= (const RWHandleBase &second)
Related Symbols inherited from RWxmsg
#define	RWTHROW(a)
Related Symbols inherited from RWHandleBase
bool	operator!= (const RWHandleBase &lhs, const RWHandleBase &rhs)

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 canceled when an external thread calls requestCancellation() on the RWRunnable object. The thread cancellation starts when RWRunnableSelf::serviceCancellation() is called from within the canceled 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.

Example

#include <rw/thread/RWCancellation.h>
#include <rw/thread/RWRunnableSelf.h>
#include <rw/thread/RWThreadFunction.h>
#include <rw/sync/RWMutexLock.h>
 
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
  }
}
 
int main() {
  RWThread t = RWThreadFunction::make(func);
  t.start();
  ::rwSleep(100);  // wait 100 milliseconds
  t.requestCancellation();
 
  return 0;
}

See also

RWRunnable, rwServiceCancellation()

Constructor & Destructor Documentation

RWCancellation() [1/2]

RWCancellation::RWCancellation ( RWRunnableImp * runnableImpP )

explicit

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

RWCancellation() [2/2]

RWCancellation::RWCancellation ( const RWCancellation & second )

inline

Copy constructor. Required for exception propagation.

Member Function Documentation

clone()

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.

raise()

virtual void RWCancellation::raise ( void ) const

virtual

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

Reimplemented from RWTHRxmsg.