Cleanup +Support Overview

Description

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