# Leaves and the Cleanup Stack

Symbian doesn't use C++ exceptions because it was written before the exceptions where standardized and they require lots of resources. Instead Symbian uses a mechanism of leaves very similar to exceptions.

A leave is generated with `User::Leave(errorCode)`. The error code is an `int` which carrys the information about the reason of the leave (there are many predefined error codes, like `KErrNotFound`). It is like the `throw` instruction in C++ with the differance that the information about the failure must be contained in the `int` error code, not in an arbitrary object. The `User::LeaveIfError(errorCode)` is also very usefull.

When a leave occurs then (similarly to exceptions) the control will `return` from all the functions (the stack will be unwinded) until it reaches a trap harness (which is like a `try`/`catch` block in standard C++). A trap harness is defined by `TRAP`:

      TInt error;

      TRAP(error, FunctionThatLeavesL());    // try

      if (error==KErrNotFound)               // catch
      {
        //...
      }

      if (error!=KErrNone)                  // catch
      {
        //...
      }

There is also a `TRAPD` macro that automatically defines the variable in the first parameter.

When a leaves occures all the data which is not owned by an object (i.e. data which is only pointed by an automatic variable in one of the functions we return from because of the leave) should be destroyed to prevent a memory leak. To achieve that Symbian uses a concept of Cleanup Stack.

If you have an object that should be destroyed in case of a leave push it on the cleanup stack with `CleanupStack::PushL(object)`. When the leave occures all the objects on the cleanup stack pushed after entering the trap harness will be destroyed. When an object should be removed from the cleanup stack, e.g. because it will be destroyed or the ownership of it will be taken by an object use `CleanupStack::Pop()` to remove the top-most object from the stack (In the first case `CleanupStack::PopAndDestroy()` it very practical). There is also a function `CleanupStack::Pop(object)` with checks if the poped object is the same as the pushed one what is usefull for debugging.

The `CleanupStack::PushL()` function has an overloaded version that accepts a `CBase *` class which has a virtual destructor. When a leaves occures the destructor will be called and the owned data will be deleted. That's why all objects that owns some external data should be decendant of `CBase`. The R classes doesn't have a common ancestor so the closing function won't be called automatically. However there are functions `CleanupClosePushL()`, `CleanupReleasePushL()` and `CleanupDeletePushL()` that, thanks to the magic of templates, will guarantee a call of `Close`, `Release` or `Delete` before destroying the object by the Cleanup Stack.

Note that every object pointed by an automatic variable should be put ont the cleanup stack - this objects whould be orphaned if a leaves occures. However if an object if owned by another object it should not be put on the cleanup stack or else it will be destored twice - once during the leave and once in the owner's destructor.

It is imporatant to know if a function can leave, so all the function that may leave have a L suffix (e.g. `PushL`). Symbian provides an overloaded `new` operator - `new(ELeave)` - that in case of a lack of memory leaves instead of returning `NULL`. Example: `iApp = new (ELeave) CMyApp();`

Due to reasons that are simple but outside of the scope of this brief tutorial a constructor must not leave. What's why Symbian uses a so called two phase construction. Often after calling the constructor you should call a function `ConstructL` that executes all the functions that may leave (e.g. memory allocations). Some classes provides static functions `NewL` and `NewLC` that does all the construction (the C suffix is another common Symbian suffix - it means that the returned object was pushed on the cleanup stack).