How to cancel requests

This document describes how to cancel a previously scheduled request.

The CActive class provides the Cancel() member function to cancel an active object’s request.

If no request has been issued, Cancel() does nothing, otherwise it calls DoCancel(). This is a pure virtual function that must be provided by derived classes and which handles specific cancellation as required by the service provider. Cancel() then waits for the completion of that request and sets the active request flag to false.

The service provider must guarantee that the cancellation operation completes in a very short period of time.

For example, a specialized timer active object, derived from CTimer which is derived from CActive, might implement this as:

void CTimedMessenger::DoCancel()
    {
      // Base class
    CTimer::DoCancel(); 
      // Reset variable - needed if the object is later re-activated
    iTicksDone = 0;
    ...
    }

Note that an active object's destructor should ensure that any outstanding requests are cancelled. If the class implements a DoCancel() function, then the destructor must call the Cancel() member function. For example:

CTimedMessenger::~CTimedMessenger()
    {
    Cancel();
    }