Class CActiveScheduler

class CActiveScheduler : public CBase;

Description

Controls the handling of asynchronous requests as represented by active objects.

An active scheduler is used to schedule the sequence in which active object request completion events are handled by a single event-handling thread.

An active scheduler can be instantiated and used directly if either:

• the RunL() function of all of its active objects is guaranteed not to leave, or

• each of its active objects implements a suitable RunError() function to provide suitable cleanup

If any of the active scheduler's active objects does not provide a RunError() function, then a CActiveScheduler derived class must be defined and an implementation of the CActiveScheduler::Error(TInt)const function provided to perform the cleanup required.

There is one active scheduler per thread and the static functions provided by the class always refer to the current active scheduler.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActiveScheduler - ...

Members

Defined in CActiveScheduler:

• Add(CActive *)Adds the specified active object to the current active scheduler.
• CActiveScheduler()Constructs an active scheduler.
• Current()Gets a pointer to the currently installed active scheduler.
• Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• Extension_(TUint,TAny *&,TAny *)Extension function
• Halt(TInt)constUnilaterally terminates the current scheduler loop.
• Install(CActiveScheduler *)Installs the specified active scheduler as the current active scheduler.
• Level()constGets the scheduler's level of nestedness.
• OnStarting() Dummy EXPORT for Binary Compatibility reasons. This method is never called.
• OnStopping() Dummy EXPORT for Binary Compatibility reasons. This method is never called.
• Replace(CActiveScheduler *)Allows the current active scheduler to be replaced, while retaining its active o...
• RunIfReady(TInt &,TInt)Causes the RunL() function of at most one pending active object of priority aMin...
• StackDepth()constGets the current number of nested wait loops.
• Start()Starts a new wait loop under the control of the current active scheduler.
• Stop()Stops the wait loop started by the most recent call to CActiveScheduler::Start()...
• TLoopOwner
• WaitForAnyRequest()Wait for an asynchronous request to complete.
• ~CActiveScheduler()Frees resources prior to destruction.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

See also:

• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.

IMPORT_C CActiveScheduler();

Description

Constructs an active scheduler.

After construction, the scheduler should be installed.

See also:

• CActiveScheduler::Install(CActiveScheduler *)Installs the specified active scheduler as the current active scheduler.

IMPORT_C ~CActiveScheduler();

Description

Frees resources prior to destruction.

Specifically, it removes all active objects from the active scheduler's list of active objects.

An active scheduler should only be destroyed when the top-level call to CActiveScheduler::Start() has returned.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Stop()Stops the wait loop started by the most recent call to CActiveScheduler::Start()...

IMPORT_C static void Install(CActiveScheduler *aScheduler);

Description

Installs the specified active scheduler as the current active scheduler.

The installed active scheduler now handles events for this thread.

The current active scheduler can be uninstalled by passing a NULL pointer.

Parameters

CActiveScheduler *aScheduler A pointer to the active scheduler to be installed. If this is NULL, the current active scheduler is uninstalled.

Panic codes

E32USER-CBase 43 if If there is already an installed active scheduler.

IMPORT_C static CActiveScheduler* Current();

Description

Gets a pointer to the currently installed active scheduler.

Return value

CActiveScheduler * A pointer to the active scheduler which is currently installed.

IMPORT_C static void Add(CActive *aActive);

Description

Adds the specified active object to the current active scheduler.

An active object can be removed from an active scheduler either by destroying the active object or by using its Deque() member function.

Parameters

CActive *aActive Pointer to the active object to be added.

Panic codes

E32USER-CBase 41 if the active object aRequest has already been added to the current active scheduler. E32USER-CBase 48 if aRequest is NULL. E32USER-CBase 44 if the thread does not have an installed active scheduler.

See also:

• CActive::Deque()Removes the active object from the active scheduler's list of active objects.

IMPORT_C static void Start();

Description

Starts a new wait loop under the control of the current active scheduler.

At least one active object, with an outstanding request, must be added to the scheduler before the wait loop is started, otherwise no events will occur and the thread will hang, or any events that do occur will be counted as stray signals, raising a panic.

While CActiveScheduler::Start() is executing, user code runs only:

1. in the RunL() function of active objects known to the current active scheduler

2. in the RunError() function of an active object that leaves from its RunL()

3. in the current active scheduler’s CActiveScheduler::Error(TInt)const function, if an active object’s RunError() returns an error code.

CActiveScheduler::Start() returns only when a corresponding CActiveScheduler::Stop() or CActiveScheduler::Halt(TInt)const is issued.

Although this can be used to start a nested wait loop, this API is deprecated for that specific functionality, and a CActiveSchedulerWait object should be used instead.

(Note that a nested wait loop is used when the handling of a completed event in an active object requires the processing of further events from the other active objects before it can complete. This is a form of modal processing.)

Panic codes

E32USER-CBase 44 if the thread does not have an active scheduler installed.

See also:

• CActiveScheduler::Stop()Stops the wait loop started by the most recent call to CActiveScheduler::Start()...
• CActiveScheduler::Halt(TInt)constUnilaterally terminates the current scheduler loop.
• CActive::RunL()Handles an active object's request completion event.
• CActive::RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.

IMPORT_C static void Stop();

Description

Stops the wait loop started by the most recent call to CActiveScheduler::Start().

Typically, this is called by the RunL() of one of the scheduler’s active objects. When this RunL() finishes, the scheduler’s wait loop terminates, i.e. it does not wait for the completion of the next request.

It will not stop a wait loop started by a call to CActiveSchedulerWait::Start().

CActiveScheduler::Stop() may also be called from CActiveScheduler::Error(TInt)const.

Note that stopping a nested wait loop is deprecated using this functionality, use a CActiveSchedulerWait object instead.

See also:

• CActiveSchedulerWait::Start()Starts a new wait loop under the control of the current active scheduler.
• CActive::RunL()Handles an active object's request completion event.
• CActiveSchedulerWait::AsyncStop()Stops the scheduling loop owned by this object.

Interface status:

deprecated

IMPORT_C static TBool RunIfReady(TInt &aError, TInt aMinimumPriority);

Description

Causes the RunL() function of at most one pending active object of priority aMinimumPriority or greater to be run.

Parameters

TInt &aError Error returned by called active object. TInt aMinimumPriority Minimum priority of active object to run.

Return value

TBool EFalse if no active object's RunL() function was run, i.e. if there were no active objects of priority aMinimumPriority or greater pending.

IMPORT_C static CActiveScheduler* Replace(CActiveScheduler *aNewActiveScheduler);

Description

Allows the current active scheduler to be replaced, while retaining its active objects.

Parameters

CActiveScheduler *aNewActiveScheduler The new active scheduler.

Return value

CActiveScheduler * Previous active scheduler.

IMPORT_C virtual void WaitForAnyRequest();

Description

Wait for an asynchronous request to complete.

The default implementation just calls User::WaitForAnyRequest().

Derived classes can replace this. Typically, this would be done to implement code for maintaining an outstanding request; this would be followed by a call to User::WaitForAnyRequest().

See also:

• User::WaitForAnyRequest()Waits for any asynchronous request to complete.

IMPORT_C virtual void Error(TInt aError) const;

Description

Handles the result of a leave occurring in an active object’s RunL() function.

An active scheduler always invokes an active object’s RunL() function under a trap harness.

The default implementation must be replaced.

Any cleanup relevant to the possible causes of leaving should be performed. If CActiveScheduler::Stop() or CActiveScheduler::Halt(TInt)const is called from within this function, the current wait loop terminates. This may be an appropriate response to catastrophic error conditions.

Parameters

TInt aError The leave code propagated from the active object’s RunL() function

Panic codes

E32USER-CBase 47 if the default implementation is invoked.

See also:

• CActive::RunL()Handles an active object's request completion event.
• CActiveScheduler::Stop()Stops the wait loop started by the most recent call to CActiveScheduler::Start()...
• CActiveScheduler::Halt(TInt)constUnilaterally terminates the current scheduler loop.

IMPORT_C void Halt(TInt aExitCode) const;

Description

Unilaterally terminates the current scheduler loop.

This causes the current scheduler loop to stop, whether it was started using CActiveSchedulerWait::Start() or CActiveScheduler::Start(). It can also trigger a leave from CActiveScheduler::Start() if an exit code is provided. If the current level has already been stopped, then this still records the exit code.

Parameters

TInt aExitCode If non-zero, the reason code reported by CActiveScheduler::Start().

IMPORT_C TInt StackDepth() const;

Description

Gets the current number of nested wait loops.

Return value

TInt The number of nested calls to CActiveScheduler::Start().

Interface status:

removed

private: IMPORT_C virtual void OnStarting();

Description

Dummy EXPORT for Binary Compatibility reasons. This method is never called.

Interface status:

removed

private: IMPORT_C virtual void OnStopping();

Description

Dummy EXPORT for Binary Compatibility reasons. This method is never called.

protected: IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);

Description

Extension function

Parameters

TUint aExtensionId TAny *&a0 TAny *a1

Return value

TInt

Interface status:

deprecated

Use the StackDepth() function instead.

protected: inline TInt Level() const;

Description

Gets the scheduler's level of nestedness.

Return value

TInt The level of nestedness.

See also:

• CActiveScheduler::StackDepth()constGets the current number of nested wait loops.

typedef TLoop* CActiveScheduler::TLoopOwner;

Description