Class CleanupStack

CleanupStack

Support

Supported from 5.0

Description

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

Defined in CleanupStack:
Pop(), PopAndDestroy(), PushL()

static void PushL(TAny* aPtr);
static void PushL(CBase* aPtr);
static void PushL(TCleanupItem anItem);

Description

Pushes a pointer to an object onto the cleanup stack. Use the function PushL(TCleanupItem anItem) to push a cleanup item 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.

• 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 a leave occurs while a cleanup item is on the stack, the cleanup operation defined in the construction of the TCleanupItem, is invoked.

Like CBase* and TAny* types, cleanup items can also be popped back off the stack by calling CleanupStack::Pop().

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

Note that for any thread, calling PushL() when no prior call to TRAP has been made, raises an E32USER-CBase 66 panic.

Parameters

TAny* aPtr Pointer to any other object If cleanup is necessary, the object will be freed by User::Free(), which does not invoke any destructor: it simply frees its memory. const CBase *aPtr Pointer to CBase-derived object If cleanup is necessary, the object will be freed by delete, thus invoking its Destruct() function and the C++ destructor, and freeing its memory. TCleanupItem anItem A cleanup item If cleanup is necessary, the cleanup operation defined in the construction of anItem is called.

Leave codes

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.

static void Pop();
static void Pop(TInt aCount);

Description

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.

The second version of the function allows a specified number (aCount) of objects to be popped off the cleanup stack.

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

Parameters

TInt aCount The number of objects to be popped off the cleanup stack. If a parameter of this type is not passed, then only one object is popped off the cleanup stack.

static void PopAndDestroy();
static void PopAndDestroy(TInt aCount);

Description

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.

Similar to Pop(), the second version of the function allows a specified number (aCount) of objects to be popped off the cleanup stack and cleaned up.

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