Active objects

This document describes the functionality and class membership of active objects.

An active object uses an asynchronous service provider class to provide a service. The active object hides the asynchronous service provider. The active object must provide:

• a function that requests a service from the service provider

• a function that cancels a request for service from the service provider.

All active objects are derived from CActive. This class provides derived active objects with:

• the data member iStatus. This data member is a TRequestStatus type object. This object is passed to the request functions of the asynchronous service provider. The request functions of the active object do not include a TRequestStatus in their parameters. The exception to this rule occurs when the active object acts as a secondary supplier of asynchronous services.

• the Cancel() function. This function cancels a request to the service provider. Cancel() does nothing if there is no outstanding request. If a request is pending, Cancel() calls DoCancel(). DoCancel() is a pure virtual function that a derived class supplies. DoCancel() must deal with the specific cancellation behavior that the service provider requires. Cancel() waits for the request to complete and then marks the request not active.

• the TPriority enumeration. This enumeration defines the set of priorities that an active object can take. The priority of the active object is set during construction of the active object. When the active scheduler's wait completes, it checks the active object with the highest priority. Where active objects have the same priority, the order of checking is not defined.

Classes derived from CActive must:

• own an asynchronous service provider. It may do this by containing either an instance of the required service provider or a handle to that provider.

• provide one or more request functions, such as IssueRequest(), which pass on the request to an asynchronous service provider.

• implement a DoCancel() function which passes on a cancel request to the asynchronous service provider

• provide a RunL() function, which is called by the active scheduler when it detects that an active object’s request has completed.

• provide a RunError() function, which is called by the active scheduler if the active object's RunL() function leaves. A derived class can use the default implementation but this just propagates the leave code up to the active scheduler.