How to start active objects

This document describes how to start active objects.

The following example code shows how active objects are started. While the example shows the creation of an active scheduler, in UI applications, an active scheduler is always provided.

• Create an instance of the active scheduler, exampleScheduler. This is an instance of a class derived from CActiveScheduler and provides an Error() function to handle leaves occurring in the active object RunL() function(s).

• Push exampleScheduler onto the cleanup stack and install as the current active scheduler.

• Create an active object, myActiveObject, and pass a pointer to the service provider as the parameter. Note that often, the service provider may be constructed as part of the active object's own construction processing.

• Issue a request using IssueRequest().

• Use CActiveScheduler::Start() to start the active scheduler’s wait loop. At least one outstanding request is necessary before the wait loop is started, otherwise the thread hangs. All further request issuing and servicing occurs within this function. The wait loop continues until one of the active objects’ RunL() requests termination using CActiveScheduler::Stop().

• Pop the active object, the active scheduler and the example service provider from the clean-up stack, and destroy. The code assumes that the active object does not take ownership of the CExampleServiceProvider object and is not responsible for its destruction.

LOCAL_C void doExampleL()
    {
        // Create and install the active scheduler
    CActiveScheduler* exampleScheduler=new (ELeave) CExampleScheduler;
    CleanupStack::PushL(exampleScheduler);
    CActiveScheduler::Install(exampleScheduler);

        // Create the service provider. Often, the
        // service provider is part of the active object
    CExampleServiceProvider* myServiceProvider=new (ELeave) CExampleServiceProvider;
    CleanupStack::PushL(myServiceProvider);

        // Create the active object and issue the
        // first asynchronous request
    CExampleActiveObject * myActiveObject=new (ELeave) CExampleActiveObject(myServiceProvider);
    CleanupStack::PushL(myActiveObject);
    myActiveObject->IssueRequest();

        // Now we can start the active scheduler
    CActiveScheduler::Start();

        // Remove the exampleScheduler and other
        // objects from cleanup stack and destroy them
    CleanupStack::PopAndDestroy(3);
    }