EPOC   SDK Home Glossary Indexes Previous Next Up

About the cleanup utilities


Contents


Overview

In ER5, there are three special templated functions and three associated templated classes which applications and EPOC code can use to create a generalised cleanup item for an object and push it onto the cleanup stack.

Recall that a clean up item is an object of type TCleanUpItem and it is this which is put onto the cleanup stack when an application calls

    CleanupStack::PushL(pointer to an object);

Cleaning up is a process which does not just mean the deletion of an object - some application objects need to do more; for example, an application object which has some open resource, must close or free that resource before being deleted.

A TCleanUpItem encapsulates two pieces of information:

The three templated functions:

and the three supporting templated classes:

offer a useful technique for constructing a TCleanUpItem and pushing it onto the cleanup stack.

These templated functions and classes were originally defined in ER3 as part of EPOC's STORE component; specifically, they were declared in s32strm.h and defined in s32strm.inl. In ER5, they have migrated to the BASE (E32) component because of their general usefulness; specifically, they are declared in e32base.h and defined in e32base.inl.

Any code which uses these functions and classes and which is being re-built under ER5 should review the header files which are #included.

These changes are binary compatible with ER3.


Using the cleanup utilities

Section Contents

Recall that a TCleanUpItem encapsulates a pointer to an object to be cleaned up and a clean up operation to be applied to that object.

The cleanup utilities support three types of clean up operation:


Using CleanupDeletePushL()

The CleanupDeletePushL() templated function constructs and pushes a TCleanupItem onto the cleanup stack. When CleanupStack::PopAndDestroy() is called, the object encapsulated by the TCleanupItem is deleted.

Look at the following code fragment is taken from the euclnutl example which can be found in the \Epoc32ex\E32 set of examples.

    ...
    CTestOne* one = new (ELeave) CTestOne;
    CleanupDeletePushL(one);
    one->SetTextL(KTxtHelloWorld);
    CleanupStack::PopAndDestroy();
    ...

The TCleanupItem encapsulates a pointer to the CTestOne object; the cleanup operation is the static function Delete() of the templated class CleanupDelete<class T>. This is implemented by simply deleting CTestOne.


Using CleanupClosePushL()

The CleanupClosePushL() templated function constructs and pushes a TCleanupItem onto the cleanup stack. When CleanupStack::PopAndDestroy() is called, the Close() member function of the object encapsulated by the TCleanupItem is called.

Look at the following code fragment is taken from the euclnutl example which can be found in the \Epoc32ex\E32 set of examples.

    ...
    RTestTwo two;
    CleanupClosePushL(two);
    CleanupStack::PopAndDestroy();
    ...

The TCleanupItem encapsulates a reference to the RTestTwo object; the cleanup operation is the static function Close() of the templated class CleanupClose<class T>. This is implemented by simply calling the Close() member function of RTestTwo.

This means that RTestTwo must define or inherit a member function Close() which performs whatever clean up is required.

In practice, this type of cleanup operation is commonly applied to handles which are constructed on the program stack.


Using CleanupReleasePushL()

The CleanupReleasePushL() templated function constructs and pushes a TCleanupItem onto the cleanup stack. When CleanupStack::PopAndDestroy() is called, the Release() member function of the object encapsulated by the TCleanupItem is called.

Look at the following code fragment is taken from the euclnutl example which can be found in the \Epoc32ex\E32 set of examples.

    ...
    RTestThree three;
    CleanupReleasePushL(three);
    CleanupStack::PopAndDestroy();
    ...

The TCleanupItem encapsulates a reference to the RTestThree object; the cleanup operation is the static function Release() of the templated class CleanupRelease<class T>. This is implemented by simply calling the Release() member function of RTestThree.

This means that RTestThree must define or inherit a member function Release() which performs whatever clean up is required.

EPOC       SDK Home Glossary Indexes Previous Next Up