Chapter 1

Even user input errors can be handled using the cleanup framework: as an example, code
that processes the OK button on a dialog can allocate many resources before finding that an
error has occurred. Dialog code can use the cleanup framework to flag an error and free the
resources with a single function call.
There's just one kind of error that the cleanup framework can't deal with – programming
errors. If you write a program with an error, you have to fix it. The best service Symbian OS
can do you (and your users) is to kill your program as soon as possible when the error is
detected, with enough diagnostics to give you a chance to identify the error and fix it –
hopefully, before you release the program. In Symbian OS, this is a panic. We've heard
about panics already – in this chapter, I'll explain them.
6.2 Handling Out-of-memory Errors
For application programmers, the resources you use mostly consist of the memory in your
own application. With that in mind, we'll introduce the cleanup tools in the context of dealing
with out-of-memory conditions in your own application (or library) code. We'll get confident
with OOM handling, and then we'll look at handling cleanup with other kinds of resources.
The toolkit provided by Symbian OS for handling out of memory and for testing your OOM
handling includes the following:
� The UIQ GUI framework's debug keys.
� Heap-checking tools, which check that all resources that were allocated by a function
are also freed.
� Proper use of the C++ destructor to destroy any owned objects.
� Heap-failure tools, which produce deliberate out-of-memory errors for testing purposes.
� The leave mechanism, which is used to indicate an error. The fundamental function
here is User::Leave(), which is at the heart of any leaving function. It does a job
similar to C++'s and Java's throw.
� The cleanup stack : objects on the cleanup stack are deleted when a leave occurs.
� The trap harness: leave processing is caught by a trap. A leave aborts its function and
any functions that called it, up to and excluding the first function that contains a trap
harness. The trap harness does a similar job to C++'s and Java's try-catch
mechanism.
� The CBase class, the ultimate base class of all C classes, which is recognized by the
cleanup stack, and includes a virtual C++ destructor so that any C class can be cleaned
up using the cleanup stack.
� The two-phase construction pattern necessary to ensure that C++ constructors
never leave. C++ constructors must, therefore, perform only basic initialization. CBasederived
classes should include a ConstructL() function that will complete the
initialization of the object.
� Naming conventions that indicate class resource-allocation patterns, whether a
function has the potential to leave, and other behavior important for cleanup. These
conventions go together with some rules that make it easy to address cleanup
requirements in the vast majority of cases.
The toolkit may look strange at first, even if you have used another error-handling
framework. Actually, it's quite easy to work with. It makes it possible to build very robust
applications with only a few disciplines, and almost no programming overhead.
6.2.1 Uikon Debug Keys
Some of the memory management tools are quite conveniently accessible through debug
builds of the Uikon GUI. Boot up the debug-mode emulator