CleanupStack Class Reference

A collection of static functions that are used to add resources to and remove resources from the cleanup stack. More...

#include <e32base.h>

Static Public Member Functions
static IMPORT_C void	PushL (TAny *aPtr)
	Pushes a pointer to an object onto the cleanup stack.
static IMPORT_C void	PushL (CBase *aPtr)
	Pushes a pointer to an object onto the cleanup stack.
static IMPORT_C void	PushL (TCleanupItem anItem)
	Pushes a cleanup item onto the cleanup stack.
static IMPORT_C void	Pop ()
	Pops an object previously pushed onto the cleanup stack by CleanupStack::PushL().
static IMPORT_C void	Pop (TInt aCount)
	Pops a specified number of objects previously pushed onto the cleanup stack by CleanupStack::PushL().
static IMPORT_C void	PopAndDestroy ()
	Pops and cleans up an item pushed onto the stack.
static IMPORT_C void	PopAndDestroy (TInt aCount)
	Pops and cleans up the specified number of items pushed onto the stack.
static IMPORT_C void	Check (TAny *aExpectedItem)
	Checks that the specified object is at the top of the cleanup stack.
static void	Pop (TAny *aExpectedItem)
	Pops an object from the top of the cleanup stack.
static void	Pop (TInt aCount, TAny *aLastExpectedItem)
	Pops the specified number of objects from the top of the cleanup stack.
static void	PopAndDestroy (TAny *aExpectedItem)
	Pops an object from the top of the cleanup stack, and cleans it up.
static void	PopAndDestroy (TInt aCount, TAny *aLastExpectedItem)
	Pops the specified number of objects from the top of the cleanup stack, and cleans them up.

Detailed Description

A collection of static functions that are used to add resources to and remove resources from the cleanup stack.

API status

Published to all clients. Released API.

Definition at line 3003 of file e32base.h.

Member Function Documentation

Check()

static IMPORT_C void CleanupStack::Check ( TAny *  aExpectedItem )

static

Checks that the specified object is at the top of the cleanup stack.

If the specified item is not at the top of the cleanup stack, then the function raises an E32USER-CBase 90 panic.

The function is part of Symbian OS in both debug and release builds, and is an aid to debugging.

Parameters

aExpectedItem

A pointer to the item expected to be at the top of the cleanup stack.

(generated from Symbian Developer Library)

Pop() [1/4]

static IMPORT_C void CleanupStack::Pop ( )

static

Pops an object previously pushed onto the cleanup stack by CleanupStack::PushL().

After an object has been successfully constructed and stored within another object, it cannot be orphaned and, therefore, the object (i.e. a pointer or a cleanup item) can be popped from the cleanup stack.

If no cleanup stack has been allocated, or there is nothing on the stack, a panic is raised.

(generated from Symbian Developer Library)

Pop() [2/4]

static void CleanupStack::Pop ( TAny *  aExpectedItem )

inlinestatic

Pops an object from the top of the cleanup stack.

The function has two modes of operation, depending on whether it is part of a debug build or a release build.

1. In a debug build, the function checks that the specified item is at the top of the cleanup stack before attempting to pop it; an E32USER-CBase 90 panic is raised if the check fails.

2 In a release build, the function just pops the object which is at the top of the cleanup stack; no checking is done.

Parameters

aExpectedItem

A pointer to the item expected to be at the top of the cleanup stack. In a release build, this parameter is not used.

(generated from Symbian Developer Library)

Pop() [3/4]

static IMPORT_C void CleanupStack::Pop ( TInt  aCount )

static

Pops a specified number of objects previously pushed onto the cleanup stack by CleanupStack::PushL().

After an object has been successfully constructed and stored within another object, it cannot be orphaned and, therefore, the object(s), that is, pointers and cleanup items can be popped from the cleanup stack.

If no cleanup stack has been allocated, or there is nothing on the stack, a panic is raised.

Parameters

aCount

The number of objects to be popped off the cleanup stack.

(generated from Symbian Developer Library)

Pop() [4/4]

static void CleanupStack::Pop ( TInt  aCount, TAny *  aLastExpectedItem  )

inlinestatic

Pops the specified number of objects from the top of the cleanup stack.

The function has two modes of operation, depending on whether it is part of a debug build or a release build.

1. In a debug build, the function pops (aCount-1) items from the cleanup stack, and then checks that the specified item is the next one on the cleanup stack before attempting to pop it; an E32USER-CBase 90 panic is raised if the check fails.
2. In a release build, the function just pops aCount items from the cleanup stack; no checking is done.

Parameters

aCount	The number of items top be popped from the cleanup stack.
aLastExpectedItem	A pointer to the item expected to be at the top of the cleanup stack, after (aCount-1) items have been popped. In a release build, this parameter is not used.

(generated from Symbian Developer Library)

PopAndDestroy() [1/4]

static IMPORT_C void CleanupStack::PopAndDestroy ( )

static

Pops and cleans up an item pushed onto the stack.

If the item on the stack is a CBase* pointer, the pointer is removed from the stack and the object is destroyed with delete.

If the item on the stack is a TAny* pointer, the pointer is removed from the stack and the memory occupied by the object is freed with User::Free().

If the item on the stack is a cleanup item, i.e. an object of type TCleanupItem, the item is removed from the stack and the cleanup operation defined during construction of the TCleanupItem object is invoked.

If no cleanup stack has been allocated, or there is nothing on the stack, a panic occurs.

(generated from Symbian Developer Library)

PopAndDestroy() [2/4]

static void CleanupStack::PopAndDestroy ( TAny *  aExpectedItem )

inlinestatic

Pops an object from the top of the cleanup stack, and cleans it up.

The function has two modes of operation, depending on whether it is part of a debug build or a release build.

1. In a debug build, the function checks that the specified item is at the top of the cleanup stack before attempting to pop and clean it up; an E32USER-CBase 90 panic is raised if the check fails.
2. In a release build, the function just pops and cleans up the object at the top of the cleanup stack; no checking is done.

Parameters

aExpectedItem

A pointer to the item expected to be at the top of the cleanup stack. In a release build, this parameter is not used.

(generated from Symbian Developer Library)

PopAndDestroy() [3/4]

static IMPORT_C void CleanupStack::PopAndDestroy ( TInt  aCount )

static

Pops and cleans up the specified number of items pushed onto the stack.

If an item on the stack is a CBase* pointer, the pointer is removed from the stack and the object is destroyed with delete.

If an item on the stack is a TAny* pointer, the pointer is removed from the stack and the memory occupied by the object is freed with User::Free().

If an item on the stack is a cleanup item, i.e. an object of type TCleanupItem, the item is removed from the stack and the cleanup operation defined during construction of the TCleanupItem object is invoked.

If no cleanup stack has been allocated, or there is nothing on the stack, a panic occurs.

Parameters

aCount

The number of objects to be popped off the cleanup stack and destroyed.

(generated from Symbian Developer Library)

PopAndDestroy() [4/4]

static void CleanupStack::PopAndDestroy ( TInt  aCount, TAny *  aLastExpectedItem  )

inlinestatic

Pops the specified number of objects from the top of the cleanup stack, and cleans them up.

The function has two modes of operation, depending on whether it is part of a debug build or a release build.

1. In a debug build, the function pops and cleans up (aCount-1) items from the cleanup stack, and then checks that the specified item is the next one on the cleanup stack before attempting to pop it and clean it up; an E32USER-CBase 90 panic is raised if the check fails.
2. In a release build, the function just pops and cleans up aCount items from the cleanup stack; no checking is done.

Parameters

aCount	The number of items top be popped from the cleanup stack, and cleaned up.
aLastExpectedItem	A pointer to the item expected to be at the top of the cleanup stack, after (aCount-1) items have been popped and cleaned up. In a release build, this parameter is not used.

(generated from Symbian Developer Library)

PushL() [1/3]

static IMPORT_C void CleanupStack::PushL ( CBase *  aPtr )

static

Pushes a pointer to an object onto the cleanup stack.

If a leave occurs while an object is on the stack, it is cleaned up automatically. CBase derived objects are cleaned up with delete.

Typically, when an object has been fully constructed and it can be guaranteed that a pointer to this new object is stored in some other object before a leave occurs, issue CleanupStack::Pop() to pop it back off the stack.

If no cleanup stack has been allocated, a panic occurs.

It is guaranteed that the object is pushed onto the cleanup stack. However, this function may leave if a stack frame for the next PushL() cannot be allocated. In this case, the cleanup stack will be cleaned up as normal, and no extra programmer intervention is needed.

Parameters

aPtr	Pointer to a CBase-derived object. If cleanup is necessary, the object will be freed by delete, thus invoking its destructor, and freeing its memory.

Panic condition: E32USER-CBase 66 if a call to this function is made when no prior call to TRAP has been made.

(generated from Symbian Developer Library)

PushL() [2/3]

static IMPORT_C void CleanupStack::PushL ( TAny *  aPtr )

static

Pushes a pointer to an object onto the cleanup stack.

If a leave occurs while an object is on the stack, it is cleaned up automatically. Untyped objects are cleaned up with User::Free() (a rather limited form of cleanup, not even the C++ destructor is called).

Typically, when an object has been fully constructed and it can be guaranteed that a pointer to this new object is stored in some other object before a leave occurs, issue CleanupStack::Pop() to pop it back off the stack.

If no cleanup stack has been allocated, a panic occurs.

It is guaranteed that the object is pushed onto the cleanup stack. However, this function may leave if a stack frame for the next PushL() cannot be allocated. In this case, the cleanup stack will be cleaned up as normal, and no extra programmer intervention is needed.

Parameters

aPtr	Pointer to any object. If cleanup is necessary, the object will be freed by User::Free(), which does not invoke any destructor: it simply frees its memory

Panic condition: E32USER-CBase 66 if a call to this function is made when no prior call to TRAP has been made.

(generated from Symbian Developer Library)

PushL() [3/3]

static IMPORT_C void CleanupStack::PushL ( TCleanupItem  anItem )

static

Pushes a cleanup item onto the cleanup stack.

If a leave occurs while a cleanup item is on the stack, the cleanup operation defined in the construction of the TCleanupItem, is invoked.

Typically, when an object has been fully constructed and it can be guaranteed that a pointer to this new object is stored in some other object before a leave occurs, issue CleanupStack::Pop() to pop it back off the stack.

If no cleanup stack has been allocated, a panic occurs.

It is guaranteed that the object is pushed onto the cleanup stack. However, this function may leave if a stack frame for the next PushL() cannot be allocated. In this case, the cleanup stack will be cleaned up as normal, and no extra programmer intervention is needed.

Parameters

anItem

A cleanup item. If cleanup is necessary, the cleanup operation defined in the construction of anItem is called.

Panic condition: E32USER-CBase 66 if a call to this function is made when no prior call to TRAP has been made.

(generated from Symbian Developer Library)

---

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

• e32base.h
• e32base.h.dox