<?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&amp; 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>