|
||
Provides idioms to handle program exceptions, and to clean up memory when exceptions occur.
Symbian OS'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.
Symbian OS 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.
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
.
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&)
.