<?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-B9F07057-4B31-5FE8-BE4C-98CC8151CD29" xml:lang="en"><title>Single

Phase Constructor Tutorial</title><shortdesc>Single phase construction is enabled by defining the <codeph>CONSTRUCTORS_MAY_LEAVE()</codeph> macro

in a public section of a class definition if the single phase construction

is part of the public interface of the class. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-0FCC96BD-B7C4-4604-96C1-D6E5D574AB53"><p><b>Required background</b></p><p>Before

beginning you must know the following: </p> <ul>

<li id="GUID-DC57A39F-122C-545C-A2A1-D26F71209C10"><p> <b>RAII:</b> The Resource

Acquisition Is Initialization (RAII) idiom is the basis of the implementation

of the smart pointer class templates. </p> </li>

<li id="GUID-C0228985-A32D-5652-8CCC-4BF401998FCC"><p> <xref href="GUID-764C2888-7EA7-3F58-B519-878A82E879CA.dita"><apiname>CONSTRUCTORS_MAY_LEAVE()</apiname></xref>:

This macro is used for enabling single phase construction, particularly for

CBase-derived classes. </p> </li>

</ul> </prereq>

<context id="GUID-D82AD7F2-633E-4A5B-9B82-4026A8F91B41"><p>Single phase constructor

provides a means to use the RAII concepts for Symbian Developers who are familiar

with C++ standards. It is provided as a tool and needs to be used after careful

consideration. </p> </context>

<steps id="GUID-DF51DCE9-ACA3-4376-B4B3-4A31728670D2">

<step id="GUID-FA70E487-145A-4502-BB58-B09A42F69183"><cmd>Enabling single

phase constructor</cmd>

<stepxmp><p>Single phase construction is enabled by defining the CONSTRUCTORS_MAY_LEAVE()

macro in a public section of a class definition if the single phase construction

is part of the public interface of the class. An example of this is given

below: </p><codeblock xml:space="preserve">class CManagedUserSinglePhase : public CBase

	{

public:

	CONSTRUCTORS_MAY_LEAVE

	static CManagedUserSinglePhase* NewL(CTicker* aTicker)

		{

		return new(ELeave) CManagedUserSinglePhase(aTicker);

		}

	. . .

	}	</codeblock></stepxmp>

</step>

<step id="GUID-5A449AB7-512E-4701-928A-2209C1A41A06"><cmd>Using single phase

constructor</cmd>

<stepxmp><p>This macro must be used within a public section of a class definition,

if the single phase construction is part of the public interface of the class.

Other classes, not derived from CBase will not be affected by this macro. </p><p>The

following example code snippet the class demonstrates the use of an embedded

string in the ingle-phase construction pattern, where a leave-safe constructor

fully initializes the object.  </p><codeblock xml:space="preserve">class CStringUserSinglePhase : public CBase

	{

public:

		CONSTRUCTORS_MAY_LEAVE

	static CStringUserSinglePhase* NewL(const TDesC& aName)

		{

		return new(ELeave) CStringUserSinglePhase(aName);

		}

	~CStringUserSinglePhase()

		{

		}</codeblock></stepxmp>

</step>

<step id="GUID-D41D3443-FBFA-44DA-8E35-E82C12829F3D"><cmd>Need to declare

the CONSTRUCTORS_MAY_LEAVE macro</cmd>

<stepxmp><p>This is necessary because the Symbian platform currently lacks

the placement delete operator counterparts corresponding to the CBase placement

new operators that take a TLeave parameter (new(ELeave)). The macro defines

these missing placement delete operators and ensures that all allocated memory

can be freed if a constructor leaves.</p></stepxmp>

</step>

</steps>

</taskbody><related-links>

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

Level Library Overview</linktext></link>

<link href="GUID-96AB1D5A-932E-55BE-A025-F01608546B99.dita"><linktext>RAII Idiom</linktext>

</link>

</related-links></task>