Provides idioms to handle program exceptions, and to clean up memory when exceptions occur
Symbian platform's clean up strategy is closely tied to its general class types, particularly classes derived from CBase.
The API has three key concepts: exception handling, cleanup stack, and general cleanup item.
Exception handling
Symbian platform does not use standard C++ exceptions (try, catch() blocks), but supplies its own idioms. An exception is referred to as a leave.
The trap harness defines a point in code that will be immediately jumped to if a leave occurs. The trap harness is set using the TRAP and TRAPD macros.
Leaves are raised through calling functions provided by the System Static Functions API User class, principally User::Leave(). Many system functions can result in leaves. Leaves may also be raised in user code.
Cleanup stack
If a leave occurs, any heap allocated resources, such as objects created through new(), referred to only through automatic pointer variables will be orphaned on the heap, causing a memory leak. To prevent such leaks, it is necessary for the program to record any such objects, so that, on the event of a leave, the system can automatically find and clean them up. The cleanup stack is the means by which this is done.
The cleanup stack is provided by CleanupStack.
GUI applications have a cleanup stack supplied to them by the application framework. Other applications must explicitly create a cleanup stack using CTrapCleanup.
General cleanup item
By default, the cleanup stack only handles CBase -based classes, and untyped (TAny*) objects that can be cleaned up by a simple memory free call. The general cleanup item allows other types of object to put on the cleanup stack, by making the caller specify a function that is to be called to perform cleanup on the object.
The general cleanup item interface is provided by TCleanupItem.
Template functions are provided as shortcuts to constructing a TCleanupItem and pushing it onto the cleanup stack. These functions are template <class T> void CleanupDeletePushL(T*), template <class T> void CleanupClosePushL(T&), and template <class T> void CleanupReleasePushL(T&).