Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]


Cleanup Support Overview

[Top]


Purpose

Provides idioms to handle program exceptions, and to clean up memory when exceptions occur.

[Top]


Architectural relationships

Symbian OS's clean up strategy is closely tied to its general class types, particularly classes derived from CBase.

[Top]


Description

The API has three key concepts: exception handling, cleanup stack, and general cleanup item.


Exception handling

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.


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

[Top]


See also

Basic Types Overview

System Static Functions Overview