|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-B9F07057-4B31-5FE8-BE4C-98CC8151CD29" xml:lang="en"><title>Single |
|
13 Phase Constructor Tutorial</title><shortdesc>Single phase construction is enabled by defining the <codeph>CONSTRUCTORS_MAY_LEAVE()</codeph> macro |
|
14 in a public section of a class definition if the single phase construction |
|
15 is part of the public interface of the class. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
16 <prereq id="GUID-0FCC96BD-B7C4-4604-96C1-D6E5D574AB53"><p><b>Required background</b></p><p>Before |
|
17 beginning you must know the following: </p> <ul> |
|
18 <li id="GUID-DC57A39F-122C-545C-A2A1-D26F71209C10"><p> <b>RAII:</b> The Resource |
|
19 Acquisition Is Initialization (RAII) idiom is the basis of the implementation |
|
20 of the smart pointer class templates. </p> </li> |
|
21 <li id="GUID-C0228985-A32D-5652-8CCC-4BF401998FCC"><p> <xref href="GUID-764C2888-7EA7-3F58-B519-878A82E879CA.dita"><apiname>CONSTRUCTORS_MAY_LEAVE()</apiname></xref>: |
|
22 This macro is used for enabling single phase construction, particularly for |
|
23 CBase-derived classes. </p> </li> |
|
24 </ul> </prereq> |
|
25 <context id="GUID-D82AD7F2-633E-4A5B-9B82-4026A8F91B41"><p>Single phase constructor |
|
26 provides a means to use the RAII concepts for Symbian Developers who are familiar |
|
27 with C++ standards. It is provided as a tool and needs to be used after careful |
|
28 consideration. </p> </context> |
|
29 <steps id="GUID-DF51DCE9-ACA3-4376-B4B3-4A31728670D2"> |
|
30 <step id="GUID-FA70E487-145A-4502-BB58-B09A42F69183"><cmd>Enabling single |
|
31 phase constructor</cmd> |
|
32 <stepxmp><p>Single phase construction is enabled by defining the CONSTRUCTORS_MAY_LEAVE() |
|
33 macro in a public section of a class definition if the single phase construction |
|
34 is part of the public interface of the class. An example of this is given |
|
35 below: </p><codeblock xml:space="preserve">class CManagedUserSinglePhase : public CBase |
|
36 { |
|
37 public: |
|
38 CONSTRUCTORS_MAY_LEAVE |
|
39 static CManagedUserSinglePhase* NewL(CTicker* aTicker) |
|
40 { |
|
41 return new(ELeave) CManagedUserSinglePhase(aTicker); |
|
42 } |
|
43 . . . |
|
44 } </codeblock></stepxmp> |
|
45 </step> |
|
46 <step id="GUID-5A449AB7-512E-4701-928A-2209C1A41A06"><cmd>Using single phase |
|
47 constructor</cmd> |
|
48 <stepxmp><p>This macro must be used within a public section of a class definition, |
|
49 if the single phase construction is part of the public interface of the class. |
|
50 Other classes, not derived from CBase will not be affected by this macro. </p><p>The |
|
51 following example code snippet the class demonstrates the use of an embedded |
|
52 string in the ingle-phase construction pattern, where a leave-safe constructor |
|
53 fully initializes the object. </p><codeblock xml:space="preserve">class CStringUserSinglePhase : public CBase |
|
54 { |
|
55 public: |
|
56 CONSTRUCTORS_MAY_LEAVE |
|
57 |
|
58 static CStringUserSinglePhase* NewL(const TDesC& aName) |
|
59 { |
|
60 return new(ELeave) CStringUserSinglePhase(aName); |
|
61 } |
|
62 |
|
63 ~CStringUserSinglePhase() |
|
64 { |
|
65 |
|
66 }</codeblock></stepxmp> |
|
67 </step> |
|
68 <step id="GUID-D41D3443-FBFA-44DA-8E35-E82C12829F3D"><cmd>Need to declare |
|
69 the CONSTRUCTORS_MAY_LEAVE macro</cmd> |
|
70 <stepxmp><p>This is necessary because the Symbian platform currently lacks |
|
71 the placement delete operator counterparts corresponding to the CBase placement |
|
72 new operators that take a TLeave parameter (new(ELeave)). The macro defines |
|
73 these missing placement delete operators and ensures that all allocated memory |
|
74 can be freed if a constructor leaves.</p></stepxmp> |
|
75 </step> |
|
76 </steps> |
|
77 </taskbody><related-links> |
|
78 <link href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita"><linktext>EUser High |
|
79 Level Library Overview</linktext></link> |
|
80 <link href="GUID-96AB1D5A-932E-55BE-A025-F01608546B99.dita"><linktext>RAII Idiom</linktext> |
|
81 </link> |
|
82 </related-links></task> |