LEAVE and TRAP:Exception Handling in Symbian C++

 

Most of us which are beggining in Symbian programming have dificulties on to adapt yourself with the exception handling schema used in the Symbian C++ dialect. Personally, for me was very bore to know how to use the CleanupStack and the ELeave constant!!! Let me try to show you what I learned...

For starting, some definitions: an exception differs from an error, because an error, or a bug, you MUST (or NEED) to correct it to put the application properly running. We would say that an exception is an error, but an exception appears at runtime. The main difference is that an error, once it had discovered, gives to you the opportunity to correct it, and an exception not, because it depends on environment factors (such memory limitations...)

With the Symbian C++ you can't use the famous try/catch keywords for exception handling, very well knowed such by Java developers, as by C++ programmers... (try/catch was removed by performance issues, and to downsize the generated code)

Thinking on it, the Symbian creators implemented an alternative model for exception handling such as the encountered in the modern languages, but with a minor impact in the performance and "object code" size, using only operator overloading, the creation of some classes and functions, and the definition of some exclusive macros for exception handling. In a such way, we could assume that the Symbian LEAVE is like throws, and the TRAP is the catch.

A simplified schema for Symbian exception handling is to think that every function you call, which would throws an exception, is putted inside a TRAP. TRAP is our try/catch, and is defined through a macro "define" keyword. For example:

TInt error;
TRAP(error, fooFunctionL());
if (error!=KErrNone)
{
   // threats exceptions throwed by "fooFunctionL()"
}

In the Symbian developer day-by-day, it's unusual to reference TRAP calls in a Symbian programm, because Symbian Active Scheduler (an execution daemon thread) already call TRAP macros in many execution points in the application. This turn its use a rare occurrence. So, let's pass to the next strucuture, which is more frequently used. I'm talking about CleanupStack. CleanupStack class, like a generic stack struct, defines 2 fundamental methods, PushL and Pop. The CleanupStack main intent is to address every allocated object that may be "orphaned" when an exception occurs. CleanupStack maintains a stack where its forming elements stores pointers to the objects in the heap. It's very importante on that cases where an object may lose its reference during object instantiation and memory space allocation. Suppose a function that can throw an exception (nominatedely, every function with the character "L" sufix can throw an exception, or a LEAVE):

void CTest::testFunctionL()
{
   CSomeClass* obj1 = new (ELeave) CComeClass;
   CComeClass* obj2 = new (ELeave) CComeClass;
   ConstructL();
}

There is an misuse in the function above: all 2 lines in the function can throw an exception (leave). So, what happens when the first variable (obj1) is succesfully allocated, but the second one (obj2) couldn't be instantiated because a memory leack occurs? The result is that a LEAVE is throwed on the second line, the second object wasn't created, but the first one will be orphaned, because the TRAP in the Active Scheduler (or in the user's program) will clean all automatic variables (automatic variables are that declared inside a function)

To fix the "testFunctionL()" method:

void CTest::testFunctionL()
{
   CSomeClass* obj1 = new (ELeave) CSomeClass;
   CleanupStack::PushL(obj1);
   CSomeClass* obj2 = new (ELeave) CSomeClass;
   CleanupStack::PushL(obj2);
   ConstructL();
}

With the CleanupStack's PushL inclusion, when a Leave occurs, the associated TRAP will call a PopAndDestroy (this function do the same thing the Pop do, but call the reference's destructor too, and clear space occupied by it) over every object declared and initialized inside this function. You can remove his object's pointer from the stack, calling the CleanupStack::Pop() function. In that case, you call Pop wherever you are certified that the object won't throw an exception (or a Leave), because once it was removed from CleanupStack, a TRAP wouldn't clear its reference from memory.

The last tip: to specify when an instantiation instruction (new operator) could Leave, you can use the overloaded new operator, passing the ELeave constant parameter. For example:

CUser* usr = new (ELeave) CUser(name, age);

Using operator overloading, the Symbian designers redefined the new operator to receive a constant, whiuch will say that it can throw an exception. A similar code in C++ ANSI could use the following strategy for threating an excpetion in the object initialization:

CUser* user;
if ( (user = new CUser(name, age)) == NULL )
{
   // manage the inapropriated initialization
}

Perceive the differences from that solution, to that used on Symbian...