16 DLLs. On the Symbian platform, this is possible, but not recommended, because |
16 DLLs. On the Symbian platform, this is possible, but not recommended, because |
17 it is expensive in memory, and has limited support in the Symbian platform |
17 it is expensive in memory, and has limited support in the Symbian platform |
18 Emulator. </p> |
18 Emulator. </p> |
19 <p>This page describes writeable static data (WSD), the alternatives to using |
19 <p>This page describes writeable static data (WSD), the alternatives to using |
20 WSD, and the costs and issues associated with its use. </p> |
20 WSD, and the costs and issues associated with its use. </p> |
21 <section><title>Global writeable static data</title> <p>Global writeable static |
21 <section id="GUID-4ED4247C-0515-4DC0-A6AA-73D0DB4E0CE9"><title>Global writeable static data</title> <p>Global writeable static |
22 data (WSD) is any per-process variable which exists for the lifetime of the |
22 data (WSD) is any per-process variable which exists for the lifetime of the |
23 process. In practice, this means any globally scoped data: data that is declared |
23 process. In practice, this means any globally scoped data: data that is declared |
24 outside of a function, struct, or class, and function scoped static variables. </p> <codeblock id="GUID-C7F90E06-286B-5E64-B94A-7683AA0DA0FB" xml:space="preserve">TBufC<20> fileName; //WSD |
24 outside of a function, struct, or class, and function scoped static variables. </p> <codeblock id="GUID-C7F90E06-286B-5E64-B94A-7683AA0DA0FB" xml:space="preserve">TBufC<20> fileName; //WSD |
25 void SetFileName() |
25 void SetFileName() |
26 { |
26 { |
31 for <codeph>const</codeph> objects with trivial constructors, such as integers. |
31 for <codeph>const</codeph> objects with trivial constructors, such as integers. |
32 However if a <codeph>const</codeph> class has a non-trivial constructor, the <codeph>const</codeph> object |
32 However if a <codeph>const</codeph> class has a non-trivial constructor, the <codeph>const</codeph> object |
33 will require a real variable and must be stored as WSD. For example: </p> <codeblock id="GUID-897D2E68-5AF6-5C69-A5AA-276A9FB89DEC" xml:space="preserve">const TInt myVariable=…; //OK – truly const |
33 will require a real variable and must be stored as WSD. For example: </p> <codeblock id="GUID-897D2E68-5AF6-5C69-A5AA-276A9FB89DEC" xml:space="preserve">const TInt myVariable=…; //OK – truly const |
34 const TPtrC KSomeConstPtr=...; //NOT OK – non trivial constructor |
34 const TPtrC KSomeConstPtr=...; //NOT OK – non trivial constructor |
35 const TRgb KSomeConstCol=...; //NOT OK – non trivial constructor</codeblock> </section> |
35 const TRgb KSomeConstCol=...; //NOT OK – non trivial constructor</codeblock> </section> |
36 <section><title>Support for global writeable static data on Symbian</title> <p>The |
36 <section id="GUID-2FFCE39F-2387-4802-99B5-62B824D93667"><title>Support for global writeable static data on Symbian</title> <p>The |
37 Symbian platform supports global writeable static data in EXEs on all versions |
37 Symbian platform supports global writeable static data in EXEs on all versions |
38 and handsets. </p> <p>Versions of Symbian OS based on the EKA2 kernel (8.1b |
38 and handsets. </p> <p>Versions of Symbian based on the EKA2 kernel (8.1b and |
39 and later) support WSD in DLLs on target hardware. Versions 8.1a and earlier, |
39 later) support WSD in DLLs on target hardware. Versions 8.1a and earlier, |
40 based on the EKA1 kernel, do not support global WSD in DLLs. </p> </section> |
40 based on the EKA1 kernel, do not support global WSD in DLLs. </p> </section> |
41 <section><title>Clean up of global writeable static data</title> <p>Your program |
41 <section id="GUID-D684D28A-5534-4867-BB3F-6341FAC55713"><title>Clean up of global writeable static data</title> <p>Your program |
42 must make sure that global writeable static data that the program allocates |
42 must make sure that global writeable static data that the program allocates |
43 is cleaned up. </p> <p>The clean up rules are as follows: </p> <ul> |
43 is cleaned up. </p> <p>The clean up rules are as follows: </p> <ul> |
44 <li id="GUID-1D25BA8E-1A8E-5502-8FD9-7F74DBB39EF4"><p>Your program must clean |
44 <li id="GUID-1D25BA8E-1A8E-5502-8FD9-7F74DBB39EF4"><p>Your program must clean |
45 up WSD objects that are defined in the process EXE or its statically-loaded |
45 up WSD objects that are defined in the process EXE or its statically-loaded |
46 DLLs. When a process exits, the Symbian platform does not automatically call |
46 DLLs. When a process exits, the Symbian platform does not automatically call |
48 <li id="GUID-7F1EB6D6-2EAD-5318-A066-DC9128A48EAF"><p>Your program does not |
48 <li id="GUID-7F1EB6D6-2EAD-5318-A066-DC9128A48EAF"><p>Your program does not |
49 need to clean up WSD objects defined in DLLs that the process has dynamically |
49 need to clean up WSD objects defined in DLLs that the process has dynamically |
50 loaded using <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref>. The Symbian platform automatically |
50 loaded using <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref>. The Symbian platform automatically |
51 calls destructors of these objects. </p> </li> |
51 calls destructors of these objects. </p> </li> |
52 </ul> </section> |
52 </ul> </section> |
53 <section><title>Alternatives to using global writeable static data</title> <p>Native |
53 <section id="GUID-3458566D-FEC2-4ED2-AFB8-3C61F693FBEF"><title>Alternatives to using global writeable static data</title> <p>Native |
54 Symbian platform C++ code rarely uses WSD. </p> <p>However, code ported from |
54 Symbian platform C++ code rarely uses WSD. </p> <p>However, code ported from |
55 other operating systems may contain large amounts of static data. For example, |
55 other operating systems may contain large amounts of static data. For example, |
56 code written in the C programming language often makes use of WSD as the "glue" |
56 code written in the C programming language often makes use of WSD as the "glue" |
57 between C function calls. </p> <p>In EKA1, WSD is not supported, so there |
57 between C function calls. </p> <p>In EKA1, WSD is not supported, so there |
58 is no choice but to use the alternative mechanisms provided by the Symbian |
58 is no choice but to use the alternative mechanisms provided by the Symbian |
70 global writeable static data. </p> <p><b>Wrap |
70 global writeable static data. </p> <p><b>Wrap |
71 in a server</b> </p> <p>The Symbian platform supports writeable global static |
71 in a server</b> </p> <p>The Symbian platform supports writeable global static |
72 data in EXEs. A common porting strategy is therefore to wrap the code in a |
72 data in EXEs. A common porting strategy is therefore to wrap the code in a |
73 Symbian server (which is an EXE), and expose its API as a client interface. </p> <p><b>Move global variables into your classes</b> </p> <p>With relatively small |
73 Symbian server (which is an EXE), and expose its API as a client interface. </p> <p><b>Move global variables into your classes</b> </p> <p>With relatively small |
74 amounts of code, it may be possible to move most global data inside classes. </p> </section> |
74 amounts of code, it may be possible to move most global data inside classes. </p> </section> |
75 <section><title>Enabling global writeable static data</title> <p>In order |
75 <section id="GUID-03B7CEEC-AF27-430C-8B70-D8E5D2B9703C"><title>Enabling global writeable static data</title> <p>In order |
76 to enable global writeable static data, simply add a statement <codeph>epocallowdlldata</codeph> (case |
76 to enable global writeable static data, simply add a statement <codeph>epocallowdlldata</codeph> (case |
77 insensitive) to the project's MMP file: </p> <codeblock id="GUID-0E673C33-569E-5F7B-9E51-55C2FC233D70" xml:space="preserve">TARGET my.dll |
77 insensitive) to the project's MMP file: </p> <codeblock id="GUID-0E673C33-569E-5F7B-9E51-55C2FC233D70" xml:space="preserve">TARGET my.dll |
78 TARGETTYPE dll |
78 TARGETTYPE dll |
79 EPOCALLOWDLLDATA |
79 EPOCALLOWDLLDATA |
80 … </codeblock> </section> |
80 … </codeblock> </section> |
81 <section><title>Costs and limitations</title> <p><b>Emulator |
81 <section id="GUID-1437C47C-4D74-4332-9138-F2DA552C6715"><title>Costs and limitations</title> <p><b>Emulator |
82 only allows a DLL with WSD to load into a single process</b> </p> <p>The Symbian |
82 only allows a DLL with WSD to load into a single process</b> </p> <p>The Symbian |
83 platform EKA2 Emulator only allows a DLL with WSD to be loaded into a single |
83 platform EKA2 Emulator only allows a DLL with WSD to be loaded into a single |
84 process. </p> <p>This is a very serious restriction. If you have a shared |
84 process. </p> <p>This is a very serious restriction. If you have a shared |
85 DLL with WSD, then the second process that attempts to load it in the emulator |
85 DLL with WSD, then the second process that attempts to load it in the emulator |
86 will fail with <codeph>KErrNotSupported</codeph>. </p> <p><b>Emulator allows WSD by default</b> </p> <p>The Emulator will allow WSD |
86 will fail with <codeph>KErrNotSupported</codeph>. </p> <p><b>Emulator allows WSD by default</b> </p> <p>The Emulator will allow WSD |
128 <li id="GUID-BA2D82B1-A036-5281-95EB-A46A7976605B"><p>The ROM build fails |
128 <li id="GUID-BA2D82B1-A036-5281-95EB-A46A7976605B"><p>The ROM build fails |
129 if a DLL with static data links to a fixed process <i>and</i> any other process. </p> </li> |
129 if a DLL with static data links to a fixed process <i>and</i> any other process. </p> </li> |
130 </ul> <p> <b>A few specific DLLs cannot have WSD</b> </p> <p>DLLs that are |
130 </ul> <p> <b>A few specific DLLs cannot have WSD</b> </p> <p>DLLs that are |
131 required to initialise the file server cannot have WSD, e.g. HAL.DLL, EUSER.DLL, |
131 required to initialise the file server cannot have WSD, e.g. HAL.DLL, EUSER.DLL, |
132 EFSRV.DLL. </p> </section> |
132 EFSRV.DLL. </p> </section> |
133 <section><title>Frequently asked questions</title> <p><b>How |
133 <section id="GUID-4DCE5F11-5066-4C72-9F39-E46737F7BDA8"><title>Frequently asked questions</title> <p><b>How |
134 does Symbian's WSD implementation work ?</b> </p> <p> <b>Case 1. For moving |
134 does Symbian's WSD implementation work ?</b> </p> <p> <b>Case 1. For moving |
135 processes:</b> </p> <p>The Symbian platform supports a moving memory model, |
135 processes:</b> </p> <p>The Symbian platform supports a moving memory model, |
136 in which the data for a process is moved into a fixed virtual address space |
136 in which the data for a process is moved into a fixed virtual address space |
137 (the "run section") when the process is active, and then back into the processes |
137 (the "run section") when the process is active, and then back into the processes |
138 "home" section when another process is active: </p> <ul> |
138 "home" section when another process is active: </p> <ul> |