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