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.