How to handle completed requests

This document describes how an active scheduler handles a completed request.

When an asynchronous service provider signals completion of a request, the active scheduler's wait completes.

The active scheduler scans those active objects whose active request flags are set. The active objects are checked in priority order. It invokes the RunL() function of the first active object whose request has completed. If there are no such active objects then the signal cannot be identified and the active scheduler raises a panic.

The RunL() function performs whatever processing is required to complete the request, for example retrieving the results of the service function and displaying them. It may also:

  • schedule another request, for example, in a keyboard handler, a request for the next key press.

  • terminate the active scheduler by calling CActiveScheduler::Stop().

If it is possible for the RunL() function to leave, then the active object should implement the RunError() function.

The active scheduler traps any leave occurring in the RunL() function and calls the active object's RunError() function, passing it the leave code. RunError() has the opportunity to do appropriate cleanup and, when complete, should return KErrNone.

If RunError() returns anything other than KErrNone, then the active scheduler's Error() function is called. As the default implementation of Error() raises a panic, then a CActiveScheduler derived class must be defined to implement a suitable Error() function.

It may be simpler to ensure that the active objects's RunError() function always returns KErrNone.