|
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-BEC25BA5-A994-48B6-B781-26900B04C8BE" xml:lang="en"><title>Introduction |
|
13 to GLib Low Memory Handler</title><shortdesc>The default behavior of GLib in Linux is such that in case of a |
|
14 memory allocation failure, the GLib memory allocation API will call abort |
|
15 and hence terminate the application. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>Memory allocation failures are more likely on a mobile device and aborting |
|
17 the application in such cases is undesirable. Therefore, the implementation |
|
18 of GLib for Symbian platform has been modified so that the GLib memory allocation |
|
19 APIs return NULL and do not call <codeph>abort()</codeph>. This requires the |
|
20 application written using GLib to start handling memory allocation failures |
|
21 which they are currently not doing.</p> |
|
22 <p>If the user, for example, wants to change the first character of a string |
|
23 with z and return the string to the caller a GLib code for this can be written |
|
24 as follows: </p> |
|
25 <codeblock xml:space="preserve">gchar * f1(gchar * x) |
|
26 { |
|
27 gchar *temp; |
|
28 temp = g_strdup(x); |
|
29 temp[0] = ‘z’; |
|
30 return temp; |
|
31 }</codeblock> |
|
32 <p>If there is a memory allocation failure in Linux, the call to <codeph>g_strdup</codeph> which |
|
33 internally uses <codeph>g_malloc</codeph> will cause the application to abort. |
|
34 However, in Symbian platform the <codeph>g_malloc()</codeph> function will |
|
35 return NULL, but the implementation of <codeph>g_strdup()</codeph> is such |
|
36 that the return value of <codeph>g_malloc()</codeph> is not checked for NULL. |
|
37 This causes the<codeph> g_strdup()</codeph> API to panic or crash the application. |
|
38 Thus, a mechanism to deal with the failures, panics or crash resulting from |
|
39 low memory situations within Symbian platform is needed.</p> |
|
40 <section id="GUID-003701F2-1AFE-4780-995F-A17FBA777A52"> <title>Illustration |
|
41 of the mechanism to handle a memory allocation failure scenario</title> |
|
42 <p>The user needs to initialize the framework which handles the low memory |
|
43 scenarios using the below-mentioned macros:</p><ol> |
|
44 <li id="GUID-5093158D-046C-4964-B220-E03B8D8DCF9B"><p><b><codeph>SET_LOW_MEMORY_TRAP(failure_value)</codeph>:</b> This |
|
45 macro will set a trap handler for low memory cases. In case there is an allocation |
|
46 failure, the failure value will be returned from the function where the trap |
|
47 handler is set.</p></li> |
|
48 <li id="GUID-E7809DD2-865E-48FE-99DE-863B7BF8C776"><p><b><codeph>SET_LOW_MEMORY_TRAP_VOID()</codeph>:</b> This |
|
49 will do the same as the above except that the function where this is set will |
|
50 just return. This will typically be used by functions which return void. In |
|
51 this case, however, the caller must check the <codeph>errno</codeph> value. |
|
52 If it is <codeph>ENOMEM</codeph>, then the user must handle things appropriately.</p></li> |
|
53 <li id="GUID-46A09236-E182-4780-B7C4-4FF31823CC37"><p><b><codeph>REMOVE_LOW_MEMORY_TRAP()</codeph>:</b> This |
|
54 will remove the trap handler which was set. </p></li> |
|
55 </ol><p>The function <codeph>f1()</codeph> will now be rewritten as:</p><codeblock xml:space="preserve">#include <glowmem> |
|
56 gchar * f1(gchar * x) |
|
57 { |
|
58 gchar *temp; |
|
59 SET_LOW_MEMORY_TRAP(NULL); |
|
60 temp = g_strdup(x); |
|
61 temp[0] = ‘z’; |
|
62 REMOVE_LOW_MEMORY_TRAP(): |
|
63 return temp; |
|
64 } </codeblock><p>If there is a memory allocation failure when the above function <codeph>f1()</codeph> is |
|
65 called, then <codeph>f1()</codeph> will return NULL to its caller. The caller |
|
66 of <codeph>f1()</codeph> is expected to check the failure value of <codeph>f1()</codeph> instead |
|
67 of ignoring the same. </p><p><b>Some words of caution</b>: The |
|
68 macro <codeph>SET_LOW_MEMORY_TRAP()</codeph> defines a variable so it is necessary |
|
69 to make the call after all the local variables declarations in C. <codeph>REMOVE_LOW_MEMORY_TRAP()</codeph> must |
|
70 be called just before the return from the function, which means that if there |
|
71 are four return statements in the function then all of them must be preceded |
|
72 with a call to <codeph>REMOVE_LOW_MEMORY_TRAP()</codeph>.</p></section> |
|
73 </conbody></concept> |