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

#include <e32base.h>

Inheritance diagram for CActiveScheduler:

Public Types
typedef TLoop *	TLoopOwner

Public Member Functions
IMPORT_C	CActiveScheduler ()
	Constructs an active scheduler.

IMPORT_C	~CActiveScheduler ()
	Frees resources prior to destruction.

virtual IMPORT_C void	WaitForAnyRequest ()
	Wait for an asynchronous request to complete.

virtual IMPORT_C void	Error (TInt aError) const
	Handles the result of a leave occurring in an active object s RunL() function.

IMPORT_C void	Halt (TInt aExitCode) const
	Unilaterally terminates the current scheduler loop.

IMPORT_C TInt	StackDepth () const
	Gets the current number of nested wait loops.

Public Member Functions inherited from CBase
	CBase ()
	Default constructor.

virtual IMPORT_C	~CBase ()
	Virtual destructor.

TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.

TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Static Public Member Functions
static IMPORT_C void	Install (CActiveScheduler *aScheduler)
	Installs the specified active scheduler as the current active scheduler.

static IMPORT_C CActiveScheduler *	Current ()
	Gets a pointer to the currently installed active scheduler.

static IMPORT_C void	Add (CActive *aActive)
	Adds the specified active object to the current active scheduler.

static IMPORT_C void	Start ()
	Starts a new wait loop under the control of the current active scheduler.

static IMPORT_C void	Stop ()
	Stops the wait loop started by the most recent call to Start().

static IMPORT_C TBool	RunIfReady (TInt &aError, TInt aMinimumPriority)
	Causes the RunL() function of at most one pending active object of priority aMinimumPriority or greater to be run.

static IMPORT_C CActiveScheduler *	Replace (CActiveScheduler *aNewActiveScheduler)
	Allows the current active scheduler to be replaced, while retaining its active objects.

Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Protected Member Functions
virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)
	Extension function.

TInt	Level () const
	Use the StackDepth() function instead.

Friends
class	CActiveSchedulerWait

Detailed 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 Error() 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.

See also: CActiveScheduler::Error; CActive; CActiveSchedulerWait

API status: Published to all clients. Released API.

Definition at line 2893 of file e32base.h.

Member Typedef Documentation

◆ TLoopOwner

typedef TLoop* CActiveScheduler::TLoopOwner

Definition at line 2927 of file e32base.h.

Constructor & Destructor Documentation

◆ CActiveScheduler()

IMPORT_C CActiveScheduler::CActiveScheduler ( )

Constructs an active scheduler.

After construction, the scheduler should be installed.

CActiveScheduler::Install

(generated from Symbian Developer Library)

◆ ~CActiveScheduler()

IMPORT_C CActiveScheduler::~CActiveScheduler ( )

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 Start() has returned.

CActiveScheduler::Start CActiveScheduler::Stop

(generated from Symbian Developer Library)

Member Function Documentation

◆ Add()

static IMPORT_C void CActiveScheduler::Add ( CActive * aActive )

static

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

aActive Pointer to the active object to be added.

Panic condition: E32USER-CBase 41 if the active object aRequest has already been added to the current active scheduler.

Panic condition: E32USER-CBase 48 if aRequest is NULL.

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

(generated from Symbian Developer Library)

◆ Current()

static IMPORT_C CActiveScheduler * CActiveScheduler::Current ( )

static

Gets a pointer to the currently installed active scheduler.

(generated from Symbian Developer Library)

◆ Error()

IMPORT_C void CActiveScheduler::Error ( TInt aError ) const

virtual

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 Stop() or Halt() is called from within this function, the current wait loop terminates. This may be an appropriate response to catastrophic error conditions.

Parameters

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

Panic condition: E32USER-CBase 47 if the default implementation is invoked.

(generated from Symbian Developer Library)

◆ Extension_()

IMPORT_C TInt CActiveScheduler::Extension_	(	TUint	aExtensionId,
		TAny *&	a0,
		TAny *	a1
	)

protectedvirtual

Extension function.

(generated from Symbian Developer Library)

Reimplemented from CBase.

◆ Halt()

IMPORT_C void CActiveScheduler::Halt ( TInt aExitCode ) const

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 Start() if an exit code is provided. If the current level has already been stopped, then this still records the exit code.

Parameters

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

(generated from Symbian Developer Library)

◆ Install()

static IMPORT_C void CActiveScheduler::Install ( CActiveScheduler * aScheduler )

static

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

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

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

(generated from Symbian Developer Library)

◆ Level()

TInt CActiveScheduler::Level ( ) const

inlineprotected

Use the StackDepth() function instead.

Gets the scheduler's level of nestedness.

StackDepth()

(generated from Symbian Developer Library)

◆ Replace()

static IMPORT_C CActiveScheduler * CActiveScheduler::Replace ( CActiveScheduler * aNewActiveScheduler )

static

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

Parameters

aNewActiveScheduler The new active scheduler.

(generated from Symbian Developer Library)

◆ RunIfReady()

static IMPORT_C TBool CActiveScheduler::RunIfReady	(	TInt &	aError,
		TInt	aMinimumPriority
	)

static

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

Parameters

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

(generated from Symbian Developer Library)

◆ StackDepth()

IMPORT_C TInt CActiveScheduler::StackDepth ( ) const

Gets the current number of nested wait loops.

(generated from Symbian Developer Library)

◆ Start()

static IMPORT_C void CActiveScheduler::Start ( )

static

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 Start() is executing, user code runs only:

in the RunL() function of active objects known to the current active scheduler
in the RunError() function of an active object that leaves from its RunL()
in the current active scheduler s Error() function, if an active object s RunError() returns an error code.

Start() returns only when a corresponding Stop() or Halt() 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 condition: E32USER-CBase 44 if the thread does not have an active scheduler installed.

(generated from Symbian Developer Library)

◆ Stop()

static IMPORT_C void CActiveScheduler::Stop ( )

static

Stops the wait loop started by the most recent call to 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().

Stop() may also be called from Error().

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

CActiveSchedulerWait::Start CActive::RunL CActiveSchedulerWait::Error CActiveSchedulerWait::AsyncStop

(generated from Symbian Developer Library)

◆ WaitForAnyRequest()

IMPORT_C void CActiveScheduler::WaitForAnyRequest ( )

virtual

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().

User::WaitForAnyRequest

(generated from Symbian Developer Library)

Friends And Related Symbol Documentation

◆ CActiveSchedulerWait

friend class CActiveSchedulerWait

friend

Definition at line 2924 of file e32base.h.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ TLoopOwner

Constructor & Destructor Documentation

◆ CActiveScheduler()

◆ ~CActiveScheduler()

Member Function Documentation

◆ Add()

◆ Current()

◆ Error()

◆ Extension_()

◆ Halt()

◆ Install()

◆ Level()

◆ Replace()

◆ RunIfReady()

◆ StackDepth()

◆ Start()

◆ Stop()

◆ WaitForAnyRequest()

Friends And Related Symbol Documentation

◆ CActiveSchedulerWait