|
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 concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2" xml:lang="en"><title>Standard |
|
13 C++ Support on Symbian Platform</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This topic describes the Standard C++ runtime features supported on Symbian^3. </p> |
|
15 <ul> |
|
16 <li id="GUID-F620B47D-35A9-54DF-89FC-031C3B3A50D4"><p><xref href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita#GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2/GUID-B44FDC08-487F-589B-8355-CF6EAB3F25BC">Global operator new</xref> </p> </li> |
|
17 <li id="GUID-2BF296E4-1204-599D-889B-46CD0FEFCC52"><p><xref href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita#GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2/GUID-ED64EEBA-A52D-5008-8F5F-11019BC5B1E2">new_handler</xref> </p> </li> |
|
18 <li id="GUID-E53A2527-BF8A-5578-AF29-B4E1862E958E"><p><xref href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita#GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2/GUID-FEC1BFE6-0219-5EE8-93D1-C0D5BCFA8A26">Global object destruction</xref> </p> </li> |
|
19 <li id="GUID-303ADDE1-83D6-5449-B508-6C6DBD7DDFC9"><p><xref href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita#GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2/GUID-1D9D2701-FD3E-57D1-952B-FB8C057FE055">STL</xref> </p> </li> |
|
20 </ul> |
|
21 <section id="GUID-B44FDC08-487F-589B-8355-CF6EAB3F25BC"><title>Global operator |
|
22 new</title> <p>In Standard C++, when dynamic memory allocation (using <codeph>operator |
|
23 new</codeph>) fails and if a handler is not set to handle it, the |
|
24 code throws an exception (<codeph>std::bad_alloc</codeph>). But in Symbian |
|
25 C++, when dynamic memory allocation fails, the code returns <b>NULL</b>. </p> <p>When |
|
26 you write Standard C++ code on Symbian C++ ensure that you either use Symbian |
|
27 C++ semantics of operator new or Standard C++ semantics of operator new in |
|
28 your code. You can use the global <codeph>operator new</codeph> as per the |
|
29 Standard C++ specification on Symbian platform by either: </p> <ul> |
|
30 <li id="GUID-3E72A8F5-F68B-5454-8F20-67CC53FDC37F"><p>Building your application |
|
31 or library using the STD target type. </p> </li> |
|
32 <li id="GUID-40D77F25-4EE4-578A-B51E-451F7655CBA6"><p>Using the <codeph>MMP</codeph> keyword, <codeph>STDCPP</codeph>. </p> </li> |
|
33 </ul> <p> <b>Note:</b> For detailed information about problems that can occur |
|
34 while using the global <codeph>operator new</codeph>, see <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-39350E32-26C2-5440-B221-10EE693CCF18">Use of operator new</xref>. </p> <p> <b>Warning:</b> The Symbian build system |
|
35 does not permit you to mix the Standard C++ <codeph>operator new</codeph> and |
|
36 the Symbian C++ <codeph>operator new</codeph>. </p> <p><b>Example</b> </p> <p>The |
|
37 following example code illustrates how to use the global <codeph>operator |
|
38 new</codeph> when you write Standard C++ code on Symbian platform and your |
|
39 target type is a non-STD target type, for example, <codeph>exe</codeph>. </p> <p>You |
|
40 must add the <codeph>MMP</codeph> keyword, <codeph>STDCPP</codeph> in the <filepath>.mmp</filepath> file |
|
41 as shown in the following code: </p> <codeblock id="GUID-400432AB-79A2-5F17-9F96-22209524BC84" xml:space="preserve">//operator_new_example.mmp |
|
42 Target operator_new_example.exe |
|
43 Targettype exe |
|
44 //The STDCPP keyword specifies Standard C++ |
|
45 STDCPP |
|
46 Source operator_new.cpp |
|
47 Systeminclude /epoc32/include/stdapis/stlportv5 |
|
48 Systeminclude /epoc32/include/stdapis |
|
49 Library libstdcppv5.lib libc.lib |
|
50 Capability all -tcb</codeblock> <codeblock id="GUID-D3F3E4C0-D08A-5498-89A8-87A70CC02FD3" xml:space="preserve">//operator_new.cpp |
|
51 #include <new> |
|
52 int main() |
|
53 { |
|
54 try |
|
55 { |
|
56 int *ptr = new int(0); |
|
57 //do something |
|
58 } |
|
59 catch(std::bad_alloc) |
|
60 { |
|
61 return 1; |
|
62 } |
|
63 delete ptr; |
|
64 return 0; |
|
65 }</codeblock> </section> |
|
66 <section id="GUID-ED64EEBA-A52D-5008-8F5F-11019BC5B1E2"><title>new_handler</title> <p>The |
|
67 new_handler() function of Standard C++ is fully supported on Symbian platform |
|
68 (the global <codeph>operator new</codeph> restrictions are applicable). You |
|
69 can use the new_handler function to handle an out of memory scenario caused |
|
70 by the global <codeph>operator new</codeph> when dynamic memory allocation |
|
71 fails. </p> <p>The following code illustrates how to set and invoke a <codeph>new_handler</codeph>: </p> <codeblock id="GUID-E1CD4479-99AF-5547-B350-00699CD2788D" xml:space="preserve">#include <new> |
|
72 int one_huge_chunk = 0xa000; |
|
73 int *last_huge_chunk=NULL; |
|
74 void foo() |
|
75 { |
|
76 /* |
|
77 * This is the new_handler and it frees the last successful allocation so |
|
78 * that the subsequent call to operator new has some free memory. |
|
79 */ |
|
80 delete [] last_huge_chunk; |
|
81 } |
|
82 void bar() |
|
83 { |
|
84 last_huge_chunk = new int[one_huge_chunk]; |
|
85 } |
|
86 int main() |
|
87 { |
|
88 std::new_handler h_new; |
|
89 try |
|
90 { |
|
91 while(1) |
|
92 { |
|
93 // Keep allocating until we reach OOM (out of memory) condition. At OOM |
|
94 // the default new handler throws std::bad_alloc |
|
95 bar(); |
|
96 } |
|
97 } |
|
98 catch(std::bad_alloc ba) |
|
99 { |
|
100 /* |
|
101 * Once the handler is set, failure of 'new' will call the handler to |
|
102 * get some free memory... |
|
103 */ |
|
104 h_new = (std::new_handler)&foo; |
|
105 try |
|
106 { |
|
107 /* |
|
108 * Try once more to see if our handler actually freed up some memory |
|
109 */ |
|
110 bar(); |
|
111 } |
|
112 catch(...) |
|
113 { |
|
114 } |
|
115 return 0; |
|
116 } |
|
117 /*Failed to throw std::bad_alloc*/ |
|
118 return 1; |
|
119 }</codeblock> <p> <b>Important Note:</b> The <codeph>targettype</codeph> of |
|
120 this executable must either be <codeph>STDEXE</codeph> /<codeph>STDDLL</codeph> or |
|
121 its <filepath>.mmp</filepath> file must use the <codeph>STDCPP</codeph> keyword. </p> </section> |
|
122 <section id="GUID-FEC1BFE6-0219-5EE8-93D1-C0D5BCFA8A26"><title>Global object |
|
123 destructors</title> <p>Global objects are supported both in a statically or |
|
124 dynamically loaded Standard C++ DLL. Their constructors are invoked when the |
|
125 DLL is loaded and their destructors are invoked when the reference count of |
|
126 the DLL falls to zero. </p> <p><b>Example</b> </p> <p>The following example |
|
127 illustrates the construction and destruction of a global object: </p> <codeblock id="GUID-75012329-3172-5B99-833B-24C2FB658FFF" xml:space="preserve">// glob_data.cpp |
|
128 #include <iostream> |
|
129 // class definition |
|
130 class AClass |
|
131 { |
|
132 AClass() |
|
133 { |
|
134 std::cout << “ctor()” << std::endl; // inline constructor |
|
135 } |
|
136 ~AClass() |
|
137 { |
|
138 std::cout << “dtor()” <<std::endl; // inline destructor |
|
139 } |
|
140 }; |
|
141 AClass GlobData; // global instance of AClass |
|
142 int main() |
|
143 { |
|
144 std::cout << “main()” << std::endl; |
|
145 }</codeblock> <p>The output of this example must be: </p> <codeblock id="GUID-0AB81D7E-B310-5CEA-86DD-65E697F4D2C2" xml:space="preserve">ctor |
|
146 main |
|
147 dtor</codeblock> </section> |
|
148 <section id="GUID-1D9D2701-FD3E-57D1-952B-FB8C057FE055"><title>STL</title> <p>Here |
|
149 are some key facts about STL support on Symbian platform: </p> <ul> |
|
150 <li id="GUID-F0FCA9CA-7417-5D07-A6AA-F679B3A3A41A"><p>The Standard C++ implementation |
|
151 on Symbian platform is based on STLPort version 5.1.4. </p> </li> |
|
152 <li id="GUID-FB97F095-533F-582D-BD28-667D1BD6863A"><p>The Standard C++ header |
|
153 files are available in the <filepath>${EPOCROOT}/epoc32/include/stdapis/stlportv5</filepath> directory. </p> </li> |
|
154 <li id="GUID-F6381C75-4C30-5627-8AAA-7D8F1FF53565"><p>The Standard C++ library |
|
155 name that you must use is <filepath>libstdcppv5.lib</filepath>. The value |
|
156 5 (in the library name) being based on the STL Port version number, which |
|
157 is 5. </p> </li> |
|
158 </ul> </section> |
|
159 </conbody><related-links> |
|
160 <link href="GUID-D6BEAF0D-844D-51F4-8DB7-FB1D60E17FE3.dita"><linktext>Copyright |
|
161 Acknowledgments for Standard C++ (STLport)</linktext></link> |
|
162 <link href="GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita"><linktext>Standard |
|
163 C++ Library Overview</linktext></link> |
|
164 <link href="GUID-CDE8CD85-8467-5B36-A0AC-41D1D98151CA.dita"><linktext> Developing |
|
165 Applications or Libraries Using Standard C++</linktext></link> |
|
166 <link href="GUID-E331B72B-84AF-558A-9B8F-73E5E50B58C7.dita"><linktext>Building |
|
167 a Standard C++ Application or Library</linktext></link> |
|
168 <link href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita"><linktext>Possible |
|
169 Problems</linktext></link> |
|
170 <link href="GUID-5B3F5296-D6D0-5D25-8362-141DF5927E52.dita"><linktext>Troubleshooting</linktext> |
|
171 </link> |
|
172 <link href="GUID-D32E52C9-F05C-5F1E-8B49-243D555C353C.dita"><linktext>Known Issues</linktext> |
|
173 </link> |
|
174 </related-links></concept> |