--- a/Symbian3/SDK/Source/GUID-8675AC01-E2D8-425C-899F-12BE99345AA9.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-8675AC01-E2D8-425C-899F-12BE99345AA9.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,163 +1,163 @@
-<?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 concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-8675AC01-E2D8-425C-899F-12BE99345AA9" xml:lang="en"><title>C++
-and Machine Architecture</title><shortdesc>The C++ language, following its foundation in C, is close to the
-machine architecture. This allows applications to be implemented efficiently,
-but, especially for developers new to the language, presents some issues of
-which you need to be aware. This topic reviews the basic language features
-from this perspective, and discusses how the resulting issues are handled.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-4E54823B-31A2-4FFB-997D-6FF6056F2643"> <title>Arithmetic types</title> <p>An <codeph>int</codeph> is
-usually implemented as the natural machine word size of the particular implementation.
-This is 32 bits in most modern machines. It was 16 bits in older machines,
-and in a few machines it may even be 64 bits. </p><p>Similarly, a pointer
-(a <codeph>void*</codeph>, for instance) is usually implemented as a machine
-word but, in some machines with special architectures, a pointer may be more
-complex. </p><p>It is assumed that Symbian is implemented on a machine
-with a 32-bit or greater machine word, and 32-bit pointers. The types <codeph>TInt</codeph> and <codeph>TUint</codeph> are<codeph> typedefed</codeph> onto the built-in <codeph>int</codeph> and <codeph>unsigned int</codeph> types,
-and are guaranteed to be at least 32 bits. </p><p>When you need a specific
-size, regardless of implementation, use a sized type. Several of these are
-available: </p><table id="GUID-8E1CEF20-AF41-4980-AA56-5CBF2B7F6A9E">
-<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
-<tbody>
-<row>
-<entry><p><codeph>TInt32</codeph>, <codeph>TUint32</codeph> </p> </entry>
-<entry><p>32-bit signed and unsigned integer</p> <p> In each case, the
-representation is a 32-bit machine word which, in the ARM architecture, must
-be aligned to a four-byte boundary. The compiler ensures that this is always
-the case.</p> </entry>
-</row>
-<row>
-<entry><p><codeph>TInt8</codeph>, <codeph>TUint8</codeph>, <codeph>TText8</codeph></p> </entry>
-<entry><p>8-bit signed and unsigned integer, and 8-bit character </p><p>In
-each case, the representation is an 8-bit byte, which has no specific alignment
-requirements. </p></entry>
-</row>
-<row>
-<entry><p><codeph>TInt16</codeph>, <codeph>TUint16</codeph>, <codeph>TText16</codeph> </p></entry>
-<entry><p>16-bit signed and unsigned integer, and 16-bit character </p><p>In
-each case, the representation is a 16-bit halfword, which should be aligned
-to a two-byte boundary. </p></entry>
-</row>
-<row>
-<entry><p><codeph>TInt64</codeph>, <codeph>TUint64</codeph> </p></entry>
-<entry><p>64-bit signed and unsigned integer </p><p>These are typedefed
-to appropriate built-in types for the compiler being used (long long, and
-unsigned long long for ARM RVCT). </p></entry>
-</row>
-<row>
-<entry><p><codeph>TReal</codeph>, <codeph>TReal64</codeph> </p></entry>
-<entry><p>Double-precision floating point, IEEE754 64-bit representation
- This is the floating-point type recommended for general use. </p><p>You
-are recommended to perform operations in integer arithmetic if possible (for
-instance, most GUI calculations), and to use floating-point only when the
-problem demands it (for instance, a spreadsheet application). </p><p>On
-processors that have floating point hardware, the compiler generates host
-instructions which use that hardware directly. On processors which don't have
-a floating point unit, the compiler implements the calculations in software.
- </p></entry>
-</row>
-<row>
-<entry><p><codeph>TReal32</codeph> </p></entry>
-<entry><p>32-bit floating point </p><p>This is smaller and quicker, but
-should only be used when space and/or time are at a true premium, as its precision
-is unsatisfactory for many applications. </p></entry>
-</row>
-</tbody>
-</tgroup>
-</table> </section>
-<section id="GUID-A89DBA31-B739-48E3-92E1-E00F50029269"><title>Compound types</title><p>Apart from classes, C++ inherits
-from C various other types of compounding. </p><p>A struct maps an area
-of memory: </p><codeblock xml:space="preserve">struct TEg
- {
- TInt iInt; // offset 0, 4 bytes
- TText8 iText; // offset 4, 1 byte
- // 3 wasted bytes
- TReal iReal; // offset 8, 8 bytes
- } // total length = 16 bytes</codeblock><fig id="GUID-70477651-EC14-4321-ACA5-79CEE4AEC69E">
-<image href="GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e5815_href.png" placement="inline"/>
-</fig><p>Structures are regarded as <codeph>T</codeph> types: that is they
-may not own heap-allocated resources such as <codeph>C</codeph> type classes.
- </p><p>An array contains many built-ins or other types </p><codeblock xml:space="preserve">TInt a[32]; // 32 TInts, = 128 bytes
-S b[3]; // 3 Ss, = 48 bytes </codeblock><p>The main disadvantage of using
-C++ arrays is that there is no automatic checking of index values. For this
-reason, and to support more complex containers, C++ has evolved the Standard
-Template Library (STL). Symbian does not use STL, but provides its own range
-of efficient container classes, for fixed, dynamic, and associative arrays.
-For details, see <xref href="GUID-2F64B579-73D3-548A-9104-16483AF77BCB.dita">Dynamic
-Arrays</xref>. </p></section>
-<section id="GUID-F925F040-C1A3-420A-A9A9-BDFBCDA212B2"><title>Pointers</title><p>A pointer is a memory address. If you can
-take the address of an object, then you can refer to it by pointer:</p><codeblock xml:space="preserve">S* ps; // pointer to an S
-ps=&s // take address of existing S
-</codeblock><p>A pointer is a 32-bit machine word, and could point to anything.</p><fig id="GUID-D33AB198-0B62-4391-B86D-088595AE6B8B">
-<image href="GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e5846_href.png" placement="inline"/>
-</fig><p>The specifier is placed next to the type rather than the name. </p><p>There
-is often a need to refer to memory as anything: for this, a <codeph>void*</codeph> pointer
-is used in C++. In Symbian, a <codeph>TAny*</codeph> may be referred to instead.
-A <codeph>TAny*</codeph> is a pointer to anything. </p></section>
-<section id="GUID-51EBCCA6-8E19-43CC-819E-8A7F0560DE4C"><title>Strings</title><p>In C++, the basic string is an array of
-characters:</p><codeblock xml:space="preserve">char* hello="hello";</codeblock><p>This statement
-does two things: firstly, it sets aside six bytes of memory containing the
-characters 'h', 'e', 'l', 'l', 'o', '\0'. Secondly, it sets the pointer hello
-to contain the address of the first of those bytes. </p><fig id="GUID-08C1AF40-8D93-414E-B103-1E57AB17480F">
-<image href="GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e5873_href.png" placement="inline"/>
-</fig><p>Functions accessing the string rely on this address as its starting
-point, and the terminating <codeph>\0</codeph> to indicate its end. Functions
-which manipulate the string must either deliberately not extend it, or must
-have some cue as to the amount of memory reserved for the string (beyond the
-trailing<codeph>\0</codeph>) so they know how much it can be extended. This
-leads to an awkward programming style, and every C++ library provides a way
-to manipulate strings more elegantly. The Symbian platform solution is <i>descriptors</i>:
-these are introduced in <xref href="GUID-9C51D27D-BEDB-59D1-8F0E-8426B8FF2230.dita">Descriptors</xref></p></section>
-<section id="GUID-9D9ED4A6-5C8A-4369-BCFB-0082A3A97599"><title>Functions</title><p>Functions are a piece of code which can
-be called and executed from anywhere else in a program. The stack is used
-to pass parameters and to contain local variables. The stack is often augmented
-by machine registers, especially in a register-rich processor such as the
-ARM, so that memory is often not used. But, conceptually, there is a stack,
-and for the purposes of this explanation it is convenient to consider the
-stack as if it were implemented entirely in memory. </p><p>Parameters are
-passed by copying or evaluating onto the called functions stack frame. It
-is bad practice to pass large parameters, such as an entire struct, or, in
-fact, anything beyond two machine words in size, because this involves excessive
-copying. Instead, a pointer or a reference should be used to pass the address,
-instead of the data itself. </p><p>In a multi-tasking system such as Symbian,
-each thread has its own stack, which is a pre-allocated area of memory. Each
-function then allocates its own frame from the stack on entry, and de-allocates
-it on exit. The advantage of the stack mechanism is that allocation and de-allocation
-are very rapid indeed— just a couple of instructions. Also, the lifetime of
-any variable on the stack is very well defined: it is the lifetime of its
-owning function, or, in fact, its owning block, since functions may have blocks
-within them. </p><p>When a function returns, its stack memory is still there:
-it is just not allocated. The stack memory will be re-used by the next function
-that is called. A potential source of error is to allocate an object on a
-functions stack frame, and then return a pointer to it: </p><codeblock xml:space="preserve">TEg* foo()
- {
- TEg s;
- TEg* ps=&s
- return ps; // !! error !!
- }
-</codeblock><p>This pointer will not be valid for long, because the memory
-will be re-used when the next function is called. You should never allow this
-to happen. This error is so obvious that a compiler will trap it. But it can
-occur in more subtle forms: </p><codeblock xml:space="preserve">foo(CContainer* aContainer)
- {
- TEg s;
- TEg* ps=&s
- aContainer->iMember=ps;
- }
-</codeblock><p>These cannot be trapped so easily. </p></section>
-<section id="GUID-19A4F40C-1177-4F71-B547-A00DE447CF55"><title>Heap</title><p>Each thread also has a heap. You can allocate
-and de-allocate objects on the heap at will, and refer to them by pointer.
-The benefit of a heap is that the lifetime of an object is entirely within
-your control. This power comes with responsibility: you must not forget to
-de-allocate objects once you have finished with them, and you must not use
-pointers to objects that have been de-allocated. </p></section>
+<?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 concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-8675AC01-E2D8-425C-899F-12BE99345AA9" xml:lang="en"><title>C++
+and Machine Architecture</title><shortdesc>The C++ language, following its foundation in C, is close to the
+machine architecture. This allows applications to be implemented efficiently,
+but, especially for developers new to the language, presents some issues of
+which you need to be aware. This topic reviews the basic language features
+from this perspective, and discusses how the resulting issues are handled.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-4E54823B-31A2-4FFB-997D-6FF6056F2643"> <title>Arithmetic types</title> <p>An <codeph>int</codeph> is
+usually implemented as the natural machine word size of the particular implementation.
+This is 32 bits in most modern machines. It was 16 bits in older machines,
+and in a few machines it may even be 64 bits. </p><p>Similarly, a pointer
+(a <codeph>void*</codeph>, for instance) is usually implemented as a machine
+word but, in some machines with special architectures, a pointer may be more
+complex. </p><p>It is assumed that Symbian is implemented on a machine
+with a 32-bit or greater machine word, and 32-bit pointers. The types <codeph>TInt</codeph> and <codeph>TUint</codeph> are<codeph> typedefed</codeph> onto the built-in <codeph>int</codeph> and <codeph>unsigned int</codeph> types,
+and are guaranteed to be at least 32 bits. </p><p>When you need a specific
+size, regardless of implementation, use a sized type. Several of these are
+available: </p><table id="GUID-8E1CEF20-AF41-4980-AA56-5CBF2B7F6A9E">
+<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
+<tbody>
+<row>
+<entry><p><codeph>TInt32</codeph>, <codeph>TUint32</codeph> </p> </entry>
+<entry><p>32-bit signed and unsigned integer</p> <p> In each case, the
+representation is a 32-bit machine word which, in the ARM architecture, must
+be aligned to a four-byte boundary. The compiler ensures that this is always
+the case.</p> </entry>
+</row>
+<row>
+<entry><p><codeph>TInt8</codeph>, <codeph>TUint8</codeph>, <codeph>TText8</codeph></p> </entry>
+<entry><p>8-bit signed and unsigned integer, and 8-bit character </p><p>In
+each case, the representation is an 8-bit byte, which has no specific alignment
+requirements. </p></entry>
+</row>
+<row>
+<entry><p><codeph>TInt16</codeph>, <codeph>TUint16</codeph>, <codeph>TText16</codeph> </p></entry>
+<entry><p>16-bit signed and unsigned integer, and 16-bit character </p><p>In
+each case, the representation is a 16-bit halfword, which should be aligned
+to a two-byte boundary. </p></entry>
+</row>
+<row>
+<entry><p><codeph>TInt64</codeph>, <codeph>TUint64</codeph> </p></entry>
+<entry><p>64-bit signed and unsigned integer </p><p>These are typedefed
+to appropriate built-in types for the compiler being used (long long, and
+unsigned long long for ARM RVCT). </p></entry>
+</row>
+<row>
+<entry><p><codeph>TReal</codeph>, <codeph>TReal64</codeph> </p></entry>
+<entry><p>Double-precision floating point, IEEE754 64-bit representation
+ This is the floating-point type recommended for general use. </p><p>You
+are recommended to perform operations in integer arithmetic if possible (for
+instance, most GUI calculations), and to use floating-point only when the
+problem demands it (for instance, a spreadsheet application). </p><p>On
+processors that have floating point hardware, the compiler generates host
+instructions which use that hardware directly. On processors which don't have
+a floating point unit, the compiler implements the calculations in software.
+ </p></entry>
+</row>
+<row>
+<entry><p><codeph>TReal32</codeph> </p></entry>
+<entry><p>32-bit floating point </p><p>This is smaller and quicker, but
+should only be used when space and/or time are at a true premium, as its precision
+is unsatisfactory for many applications. </p></entry>
+</row>
+</tbody>
+</tgroup>
+</table> </section>
+<section id="GUID-A89DBA31-B739-48E3-92E1-E00F50029269"><title>Compound types</title><p>Apart from classes, C++ inherits
+from C various other types of compounding. </p><p>A struct maps an area
+of memory: </p><codeblock xml:space="preserve">struct TEg
+ {
+ TInt iInt; // offset 0, 4 bytes
+ TText8 iText; // offset 4, 1 byte
+ // 3 wasted bytes
+ TReal iReal; // offset 8, 8 bytes
+ } // total length = 16 bytes</codeblock><fig id="GUID-70477651-EC14-4321-ACA5-79CEE4AEC69E">
+<image href="GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e7090_href.png" placement="inline"/>
+</fig><p>Structures are regarded as <codeph>T</codeph> types: that is they
+may not own heap-allocated resources such as <codeph>C</codeph> type classes.
+ </p><p>An array contains many built-ins or other types </p><codeblock xml:space="preserve">TInt a[32]; // 32 TInts, = 128 bytes
+S b[3]; // 3 Ss, = 48 bytes </codeblock><p>The main disadvantage of using
+C++ arrays is that there is no automatic checking of index values. For this
+reason, and to support more complex containers, C++ has evolved the Standard
+Template Library (STL). Symbian does not use STL, but provides its own range
+of efficient container classes, for fixed, dynamic, and associative arrays.
+For details, see <xref href="GUID-2F64B579-73D3-548A-9104-16483AF77BCB.dita">Dynamic
+Arrays</xref>. </p></section>
+<section id="GUID-F925F040-C1A3-420A-A9A9-BDFBCDA212B2"><title>Pointers</title><p>A pointer is a memory address. If you can
+take the address of an object, then you can refer to it by pointer:</p><codeblock xml:space="preserve">S* ps; // pointer to an S
+ps=&s // take address of existing S
+</codeblock><p>A pointer is a 32-bit machine word, and could point to anything.</p><fig id="GUID-D33AB198-0B62-4391-B86D-088595AE6B8B">
+<image href="GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e7121_href.png" placement="inline"/>
+</fig><p>The specifier is placed next to the type rather than the name. </p><p>There
+is often a need to refer to memory as anything: for this, a <codeph>void*</codeph> pointer
+is used in C++. In Symbian, a <codeph>TAny*</codeph> may be referred to instead.
+A <codeph>TAny*</codeph> is a pointer to anything. </p></section>
+<section id="GUID-51EBCCA6-8E19-43CC-819E-8A7F0560DE4C"><title>Strings</title><p>In C++, the basic string is an array of
+characters:</p><codeblock xml:space="preserve">char* hello="hello";</codeblock><p>This statement
+does two things: firstly, it sets aside six bytes of memory containing the
+characters 'h', 'e', 'l', 'l', 'o', '\0'. Secondly, it sets the pointer hello
+to contain the address of the first of those bytes. </p><fig id="GUID-08C1AF40-8D93-414E-B103-1E57AB17480F">
+<image href="GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e7148_href.png" placement="inline"/>
+</fig><p>Functions accessing the string rely on this address as its starting
+point, and the terminating <codeph>\0</codeph> to indicate its end. Functions
+which manipulate the string must either deliberately not extend it, or must
+have some cue as to the amount of memory reserved for the string (beyond the
+trailing<codeph>\0</codeph>) so they know how much it can be extended. This
+leads to an awkward programming style, and every C++ library provides a way
+to manipulate strings more elegantly. The Symbian platform solution is <i>descriptors</i>:
+these are introduced in <xref href="GUID-9C51D27D-BEDB-59D1-8F0E-8426B8FF2230.dita">Descriptors</xref></p></section>
+<section id="GUID-9D9ED4A6-5C8A-4369-BCFB-0082A3A97599"><title>Functions</title><p>Functions are a piece of code which can
+be called and executed from anywhere else in a program. The stack is used
+to pass parameters and to contain local variables. The stack is often augmented
+by machine registers, especially in a register-rich processor such as the
+ARM, so that memory is often not used. But, conceptually, there is a stack,
+and for the purposes of this explanation it is convenient to consider the
+stack as if it were implemented entirely in memory. </p><p>Parameters are
+passed by copying or evaluating onto the called functions stack frame. It
+is bad practice to pass large parameters, such as an entire struct, or, in
+fact, anything beyond two machine words in size, because this involves excessive
+copying. Instead, a pointer or a reference should be used to pass the address,
+instead of the data itself. </p><p>In a multi-tasking system such as Symbian,
+each thread has its own stack, which is a pre-allocated area of memory. Each
+function then allocates its own frame from the stack on entry, and de-allocates
+it on exit. The advantage of the stack mechanism is that allocation and de-allocation
+are very rapid indeed— just a couple of instructions. Also, the lifetime of
+any variable on the stack is very well defined: it is the lifetime of its
+owning function, or, in fact, its owning block, since functions may have blocks
+within them. </p><p>When a function returns, its stack memory is still there:
+it is just not allocated. The stack memory will be re-used by the next function
+that is called. A potential source of error is to allocate an object on a
+functions stack frame, and then return a pointer to it: </p><codeblock xml:space="preserve">TEg* foo()
+ {
+ TEg s;
+ TEg* ps=&s
+ return ps; // !! error !!
+ }
+</codeblock><p>This pointer will not be valid for long, because the memory
+will be re-used when the next function is called. You should never allow this
+to happen. This error is so obvious that a compiler will trap it. But it can
+occur in more subtle forms: </p><codeblock xml:space="preserve">foo(CContainer* aContainer)
+ {
+ TEg s;
+ TEg* ps=&s
+ aContainer->iMember=ps;
+ }
+</codeblock><p>These cannot be trapped so easily. </p></section>
+<section id="GUID-19A4F40C-1177-4F71-B547-A00DE447CF55"><title>Heap</title><p>Each thread also has a heap. You can allocate
+and de-allocate objects on the heap at will, and refer to them by pointer.
+The benefit of a heap is that the lifetime of an object is entirely within
+your control. This power comes with responsibility: you must not forget to
+de-allocate objects once you have finished with them, and you must not use
+pointers to objects that have been de-allocated. </p></section>
</conbody></concept>
\ No newline at end of file