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