<?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-12-1-13-1-1-9-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-12-1-13-1-1-9-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-12-1-13-1-1-9-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_d0e188587_href.png" placement="inline"/>

</fig><fig id="GUID-573E838C-50CD-4CE7-B608-6BBD18B29088">

<image href="GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e188591_href.png" scale="100" placement="inline"/>

</fig>  </section>

<section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-12-1-13-1-1-9-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-12-1-13-1-1-9-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-12-1-13-1-1-9-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>