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).