Active objects

An active object uses an asynchronous service provider class to provide the service. The active object hides the asynchronous service provider and offers request and cancel functions for that service provider.

The class from which all active objects are derived is CActive. This provides derived active objects with:

• the data member iStatus, an object of type TRequestStatus, which is passed to the request functions of the asynchronous service provider. The active objects request functions, therefore, do not include a TRequestStatus among their parameters (except when the active object is itself acting as a secondary provider of asynchronous services).

• the flag data member, iActive, which is used to indicate that a request has been issued. The active scheduler tests this flag when handling the completion of a wait for any request. The active objects request functions must set this flag when they issue a request by calling the SetActive() function.

• the Cancel() function which cancels an outstanding request and resets the iActive flag. If no request has been issued Cancel() does nothing, otherwise it calls DoCancel(), a pure virtual function which 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 TPriority enumeration, which defines the set of priorities which an active object can take. The active object's priority is set during construction.. When the active schedulers 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 objects 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.

Note that the RunError() function is not defined in v5.

Active Scheduler