How to use the cleanup stack

This document describes how to use the cleanup stack when a function leaves.

The cleanup stack is used as follows:

1. Use CleanupStack::PushL() to push a pointer to the object onto the cleanup stack before any operation which might leave is performed

2. Use CleanupStack::Pop() to pop the pointer from the cleanup stack when all operations that might leave have completed

If a function leaves, then part of leave processing is to pop and destroy all objects on the cleanup stack. Thus, the cleanup stack may be used to prevent objects becoming orphaned if a leave occurs.

void doExampleL()
 {
 // allocate with checking
 CExample* myExample = new (ELeave) CExample;

 // do something that cannot leave
 myExample->iInt = 5; // cannot leave: no protection needed

 // do something that can leave: use cleanup stack
 CleanupStack::PushL(myExample); // pointer on cleanup stack
 myExample->DoSomethingL(); // something that might leave
 CleanupStack::Pop(); // it didn't leave: pop the pointer

 // delete
 delete myExample;
 }