Class CAsyncOneShot

class CAsyncOneShot : public CActive;

Description

An active object that performs processing that is only performed once.

The active object is intended to be given a low priority, so that it runs only when no higher-priority active objects are ready to run. In addition, the class ensures that the current thread cannot be closed until the active object is destroyed.

The class needs to be derived from to make use of its behaviour, in particular, it needs to define and implement a CActive::RunL() function.

NB: the constructor creates a process-relative handle to the current thread and this is stored within this object. If the thread subsequently dies abnormally, then this handle will not be closed, and the thread will not be destroyed until the process terminates.

NB: if CAsyncOneShot::Call() is called from a different thread (for example, to implement a kind of inter-thread communication), a client-specific mechanism must be used to ensure that the thread that created this object is still alive.

NB: if the thread that created this object has its own heap and terminates abnormally, then the handle stored within this object is lost.

Derivation

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

• CActive - The core class of the active object abstraction.

• CAsyncOneShot - An active object that performs processing that is only performed once.

Members

Defined in CAsyncOneShot:

• CAsyncOneShot(TInt)Constructor taking a priority value.
• Call()Queues this active object to be run once.
• DoCancel()Implements cancellation of an outstanding request.
• Thread()Gets a handle to the current thread.
• ~CAsyncOneShot()Frees resources prior to destruction.

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• RunL()Handles an active object's request completion event.
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

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:

• CActive::RunL()Handles an active object's request completion event.
• CAsyncOneShot::Call()Queues this active object to be run once.

IMPORT_C CAsyncOneShot(TInt aPriority);

Description

Constructor taking a priority value.

Specifically, the constructor:

1. sets this active object's priority value

2. opens a handle to the current thread to ensure that the thread cannot be closed until this CAsyncOneShot object is destroyed

3. adds this active object to the current active scheduler.

Parameters

TInt aPriority The active object priority value. CActive::TPriority defines a standard set of priorities.

Panic codes

E32USER-CBase 93 if the attempt to open a handle to the current thread fails.

IMPORT_C virtual ~CAsyncOneShot();

Description

Frees resources prior to destruction.

Specifically, it closes the handle to the current thread.

See also:

• CActive::~CActive()Frees resources prior to destruction.

IMPORT_C virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

The class provides an empty implementation.

This is called by the destructor.

IMPORT_C virtual void Call();

Description

Queues this active object to be run once.

Panic codes

E32USER-CBase 2 In debug builds only, if this active object has not already been added to the active scheduler.

inline RThread& Thread();

Description

Gets a handle to the current thread.

Return value

RThread & The handle to the current thread.