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 (RWRunnableImp *runnableImpP)
	RWCancellation (const RWCancellation &second)
virtual RWTHRxmsg *	clone (void) const
virtual void	raise (void) const
Public Member Functions inherited from RWTHRxmsg
	RWTHRxmsg (void)
	RWTHRxmsg (const RWCString &msg)
	RWTHRxmsg (const RWTHRxmsg &second)
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
bool	operator!= (const RWHandleBase &second) const
bool	operator< (const RWHandleBase &second) const
bool	operator== (const RWHandleBase &second) const

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

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/RWThreadFunction.h>
#include <rw/thread/RWRunnableSelf.h>
#include <rw/thread/RWCancellation.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::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

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.