<?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-39A8FBC9-5FD6-4F92-B71E-5C5438ECFD46" xml:lang="en"><title>OOM
Monitor Overview</title><shortdesc>This section provides an overview of the functionality and the
architecture of the OOM Monitor component.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-1"><title>Purpose</title><p>The
OOM Monitor Client API monitors the memory situations and handles out of memory
situations. OOM monitor is responsible to maintain good memory level in the
device. In case of low memory situation, OOM Monitor releases memory by closing
applications based on the priority defined. For information on priority, refer
to <xref href="GUID-CE308C71-D8B2-43B3-97FD-B868285ED5FB.dita">OOM Monitor Priority</xref>.</p> 
  </section>
<section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-2"><title>Key concepts</title><dl>
<dlentry>
<dt>LOW_RAM_THRESHOLD</dt>
<dd><p>It is the minimum amount of free RAM that is specified for the device.
This value must be specified in the monitor configuration file. </p> </dd>
</dlentry>
<dlentry>
<dt>GOOD_RAM_THRESHOLD</dt>
<dd><p>It is the required amount of free RAM that is specified for the device.
This value must be specified in the monitor configuration file.</p> </dd>
</dlentry>
<dlentry>
<dt>Normal RAM rotation</dt>
<dd><p>Whenever the amount of free RAM decreases below LOW_RAM_THRESHOLD the
OOM Monitor releases RAM by closing applications based on the priorities.
This process is called as normal RAM rotation.</p> </dd>
</dlentry>
</dl><p>For information on OOM Monitor Priority and Optional RAM allocation,
refer to <xref href="GUID-F6A33835-D677-41D0-86BB-812E3AFA5192.dita">OOM Monitor
Concepts</xref></p>  </section>
<section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-3"><title>Architecture</title>  <p>The
basic function of the OOM Monitor is to monitor the amount of free RAM in
the mobile device. Whenever the amount of free RAM decreases below a defined <keyword>LOW_RAM_THRESHOLD</keyword> threshold
value, the OOM Monitor is triggered. The OOM Monitor then releases RAM by
closing applications running on background in order to raise the amount of
free RAM above the defined GOOD_RAM_THRESHOLD value.</p><fig id="GUID-1DD9B22F-1060-4AC9-899B-EC2D91E7B948">
<image href="GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e143081_href.png" placement="inline"/>
</fig><fig id="GUID-573E838C-50CD-4CE7-B608-6BBD18B29088">
<image href="GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e143085_href.png" scale="100" placement="inline"/>
</fig>  </section>
<section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-4"><title>APIs</title><p>The
OOM Monitor Client API consists of <xref href="GUID-02D1911A-D2E5-3D28-9B05-75DA0A75DE73.dita"><apiname>ROomMonitorSession</apiname></xref> class.
The main functions of this class are:</p><table id="GUID-CF94290C-7BE9-418F-9CF0-93DE74814097-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-4-3">
<tgroup cols="2"><colspec colname="col1" colwidth="0.70*"/><colspec colname="col2" colwidth="1.30*"/>
<tbody>
<row>
<entry><p><b>Function</b></p></entry>
<entry><p><b>Description</b></p></entry>
</row>
<row>
<entry><p><xref href="GUID-1F51447A-B975-3767-8ED9-5E1B98E8A672.dita"><apiname>RequestFreeMemory()</apiname></xref></p></entry>
<entry><p>Requests the OOM monitor to allocate RAM.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-C8FA6C1A-AE06-3E4D-9884-FAAA93239D13.dita"><apiname>SetOomPriority()</apiname></xref></p></entry>
<entry><p>Sets the priority for an application as high, busy or normal. The
application priorities must be defined in <codeph>TOomPriority</codeph> variable.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-2B246C7F-8A7F-3AA7-8150-657A45CF8F57.dita"><apiname>RequestOptionalRam()</apiname></xref></p></entry>
<entry><p>Requests the OOM monitor to allocate optional RAM.</p></entry>
</row>
</tbody>
</tgroup>
</table><p>The OOM Monitor Client API also consists of <xref href="GUID-ACE03F26-555A-363E-B220-44FCA7E8EACB.dita"><apiname>COomMonitorPlugin</apiname></xref> class.
The main functions of this plug-in class are:</p><table id="GUID-CF94290C-7BE9-418F-9CF0-93DE74814097-GENID-1-10-1-10-1-1-8-1-5-1-4-1-3-4-5">
<tgroup cols="2"><colspec colname="col1" colwidth="0.70*"/><colspec colname="col2" colwidth="1.30*"/>
<tbody>
<row>
<entry><p><b>Function</b></p></entry>
<entry><p><b>Description</b></p></entry>
</row>
<row>
<entry><p><xref href="GUID-E51E399F-AB9D-3587-9985-5E5016F49587.dita"><apiname>FreeRam()</apiname></xref></p></entry>
<entry><p>Requests to release RAM when the system RAM level becomes low.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-6D853E56-6EE6-398A-B9BF-BB35C4D5729D.dita"><apiname>MemoryGood()</apiname></xref></p></entry>
<entry><p>Called when the system RAM level improves to good from low RAM situation.
Once the memory level is good, the OOM plug-in can again start allocating
optional RAM.</p></entry>
</row>
</tbody>
</tgroup>
</table></section>
<section id="GUID-1D0FDADB-ACAC-4507-BF63-E78A7F322133"><title>Typical Uses</title><p>Applications
can use the following functionality provided by the OOM Monitor component
to:  </p><ul>
<li><p>Safely allocate large amount of RAM. For more information, refer to <xref href="GUID-50CA5439-29A1-426C-83BA-EC048FE86CDE.dita">Requesting for Large Memory
Allocation</xref>.</p></li>
<li><p>Change its priority in order to protect itself from being closed by
the OOM Monitor. For more information, refer to <xref href="GUID-8F8E3814-7ED6-4218-BEEF-741AE0E9366F.dita">Changing
the Priority</xref>.</p></li>
<li><p>Allocate optional RAM to applications when additional RAM is requested.
For more information, refer to <xref href="GUID-217C992B-AC56-42A7-9920-DEC891D233A5.dita">Requesting
for Optional RAM Allocation</xref>.</p></li>
<li><p>Prevent OOM errors from happening by monitoring the amount of free
RAM in the system. When the amount of free RAM drops below the specified threshold
value, OOM Monitor automatically closes applications that are staying idle
in the background in order to give more RAM to the applications that are active.
For more information, refer to <xref href="GUID-0371FD21-D988-4560-891F-2840C36AB2E2.dita">Out
of Memory Error</xref>.</p></li>
<li><p>Assign priority for each action that can be used to release RAM (i.e.
closing an application or calling an OOM plug-in). When releasing RAM, OOM
Monitor uses the priorities to determine the order of closing applications
and calling plug-ins. As a result RAM is always released by minimizing the
negative impact to the user, provided the priorities are correctly configured
for the device. For more information, refer to <xref href="GUID-178488C1-5453-490F-B168-9D73DB5BAE47.dita">Priority
Configuration</xref>.</p></li>
</ul></section>
<section id="GUID-23F8161E-5057-4ADD-BD2F-BC87F45B4B2E"><title>Related information</title><ul>
<li><p><xref href="GUID-F6A33835-D677-41D0-86BB-812E3AFA5192.dita">OOM Monitor
Concepts</xref></p></li>
<li><p><xref href="GUID-C7AA92A9-9595-439A-A3E7-769E36D61FEE.dita">Using OOM Monitor</xref></p></li>
<li><p><xref href="GUID-88752800-83BD-4845-80A0-6B65D8D81924.dita">OOM Monitor
Reference</xref></p></li>
</ul></section>
</conbody></concept>