<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-3799F0DA-B99C-55BB-B44F-63B971DF1865" xml:lang="en"><title>Cleanup

Strategy Tutorial</title><shortdesc>This tutorial describes the cleanup strategy and provides details

on alternative cleanup strategies. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq><p>Before you start, you must: </p> <ul>

<li id="GUID-18CD0776-EEA9-56AF-9E5F-E5101BB88643"><p> <b>Deafult cleanup

strategies:</b> These are based on a template-based implementation of the

strategy design pattern. </p> </li>

<li id="GUID-598FF730-0C91-51C4-B9AA-16B74137BB6E"><p> <b>Alternative cleanup

strategies:</b> These can be specified as an optional template parameter of

the class templates for automatic resource management. </p> </li>

</ul> </prereq>

<context><p>Cleanup strategy is based on a template-based implementation of

the Strategy design pattern. The strategy design pattern is one of the most

popular, highly recommended design patterns. The vast majority of the competent

C++ developers are already familiar with the strategy (Policy) design pattern

and Policy-based design, which should improve the usability of these class

templates. </p> <p>Each

resource management class has a default cleanup strategy that is invoked when

the managing object goes out of scope. It is however possible to define an

alternative cleanup strategy when constructing the managing object. It is

also possible to define a custom cleanup strategy using the <xref href="GUID-CE0F22BA-8789-3659-87C4-164EB5862B4C.dita"><apiname>DEFINE_CLEANUP_FUNCTION</apiname></xref> macro. </p> <p> <b>Note:</b> Although

the examples below use LCleanedupX classes, the method for definfing how the

object is cleaned up is equally applicable to LManagedX classes. </p> <p>An

example code snippet is given below: </p> <codeblock id="GUID-DE45C250-C8C5-5210-B53C-D9256F00194B" xml:space="preserve">

//Class definition of trivial R-Class

class RSimple

    {

public:

    RSimple(){iData = NULL;}

    void Open(TInt aValue)

        {

        iData = new(ELeave) TInt(aValue);

        }

    //Cleanup function – frees resource

    void Close()

        {

        delete iData;

        iData = NULL;

        }

    //Cleanup function – frees resource

    void Free()

        {

        delete iData;

        iData = NULL;

        }

    //Cleanup function – frees resource

    void ReleaseData()

        {

        delete iData;

        iData = NULL;

        }

    //static cleanup function – frees aRSimple resources

    static void Cleanup(TAny* aRSimple)

        {

        static_cast RSimple* (aRSimple)->Close();

        }

private:

    Tint* iData;

    };

</codeblock> <p>The above RSimple class has three cleanup member functions,

Close, Free and ReleaseData. </p> <p>Each resource management class has a

default cleanup strategy that is invoked when the managing object goes out

of scope. The default cleanup strategy is dependent on the managing type.

Consider the example code snippet below: </p> <p> <b>Note:</b> Although the

examples below use LManagedX classes, the method for defining a custom cleanup

strategy is equally applicable to LCleanedupX classes. </p> <codeblock id="GUID-7D4F639F-3BEA-59CD-BA75-DF1C25175BA3" xml:space="preserve">

class CTicker : public CBase

    {

public:

    void Tick() { ++iTicks; }

    void Tock() { ++iTocks; }

    void Zap() { delete this; }

public:

    TInt iTicks;

    TInt iTocks;

    };

class CManagedUserSinglePhase : public CBase

    {

public:

    . . .

    ~CManagedUserSinglePhase()

        {

        // The iTicker manager will automatically delete the CTicker

        // The iTimer manager will automatically Close() the RTimer

        }

    . . .

private:

    // We have to use LManagedXxx for fields, not LCleanedupXxx

    LManagedPtr CTicker iTicker;

    LManagedHandle RTimer iTimer;

    };

</codeblock> <p>The default cleanup strategy for an LManagedPtr is to delete

the pointer and this is the action taken in the destructor for CManagedUserSinglePhase. </p> <p>Alternate

cleanup strategies are pre-defined in <filepath>emanaged.h</filepath> file.

It is also possible to define a custom alternate cleanup strategy that can

be passed as the second template parameter to the constructor of an LManagedX

or LCleanedupX object. </p> <p>Although the examples below use LManagedX classes,

the method for defining an alternate cleanup strategy is equally applicable

to LCleanedupX classes. </p> <p>The default cleanup strategy is to call <xref href="GUID-91F3C4E0-5687-366D-9D50-D710E763F0CF.dita#GUID-91F3C4E0-5687-366D-9D50-D710E763F0CF/GUID-29E73AC7-D397-3237-ABF9-C93C0AD39543"><apiname>CTicker::Zap()</apiname></xref> function.

It is possible however to define a custom alternate cleanup strategy as shown

below: </p> <codeblock id="GUID-5B268C52-2708-50CF-8070-0896C8CE80C0" xml:space="preserve">

// Defines a custom pointer cleanup policy that calls the Zap member

template <class T>

class TTickerZap 

    {

public:

    static void Cleanup(T* aPtr)

        {

        // The general template/class scaffolding remains the same

        // for all custom cleanups, just this cleanup body varies

        aPtr->Zap();

        test.Printf(_L("Zapped CTicker\n"));

        }

    };

</codeblock> </context>

</taskbody><related-links>

<link href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita"><linktext>EUser High

Level Overview</linktext></link>

<link href="GUID-A18153C0-230C-51FB-9384-A48BB4E42F03.dita"><linktext>Clean-up

Strategy</linktext></link>