|
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-39A8FBC9-5FD6-4F92-B71E-5C5438ECFD46" xml:lang="en"><title>OOM |
|
13 Monitor Overview</title><shortdesc>This section provides an overview of the functionality and the |
|
14 architecture of the OOM Monitor component.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-1"><title>Purpose</title><p>The |
|
16 OOM Monitor Client API monitors the memory situations and handles out of memory |
|
17 situations. OOM monitor is responsible to maintain good memory level in the |
|
18 device. In case of low memory situation, OOM Monitor releases memory by closing |
|
19 applications based on the priority defined. For information on priority, refer |
|
20 to <xref href="GUID-CE308C71-D8B2-43B3-97FD-B868285ED5FB.dita">OOM Monitor Priority</xref>.</p> |
|
21 </section> |
|
22 <section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-2"><title>Key concepts</title><dl> |
|
23 <dlentry> |
|
24 <dt>LOW_RAM_THRESHOLD</dt> |
|
25 <dd><p>It is the minimum amount of free RAM that is specified for the device. |
|
26 This value must be specified in the monitor configuration file. </p> </dd> |
|
27 </dlentry> |
|
28 <dlentry> |
|
29 <dt>GOOD_RAM_THRESHOLD</dt> |
|
30 <dd><p>It is the required amount of free RAM that is specified for the device. |
|
31 This value must be specified in the monitor configuration file.</p> </dd> |
|
32 </dlentry> |
|
33 <dlentry> |
|
34 <dt>Normal RAM rotation</dt> |
|
35 <dd><p>Whenever the amount of free RAM decreases below LOW_RAM_THRESHOLD the |
|
36 OOM Monitor releases RAM by closing applications based on the priorities. |
|
37 This process is called as normal RAM rotation.</p> </dd> |
|
38 </dlentry> |
|
39 </dl><p>For information on OOM Monitor Priority and Optional RAM allocation, |
|
40 refer to <xref href="GUID-F6A33835-D677-41D0-86BB-812E3AFA5192.dita">OOM Monitor |
|
41 Concepts</xref></p> </section> |
|
42 <section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-3"><title>Architecture</title> <p>The |
|
43 basic function of the OOM Monitor is to monitor the amount of free RAM in |
|
44 the mobile device. Whenever the amount of free RAM decreases below a defined <keyword>LOW_RAM_THRESHOLD</keyword> threshold |
|
45 value, the OOM Monitor is triggered. The OOM Monitor then releases RAM by |
|
46 closing applications running on background in order to raise the amount of |
|
47 free RAM above the defined GOOD_RAM_THRESHOLD value.</p><fig id="GUID-1DD9B22F-1060-4AC9-899B-EC2D91E7B948"> |
|
48 <image href="GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e149615_href.png" placement="inline"/> |
|
49 </fig><fig id="GUID-573E838C-50CD-4CE7-B608-6BBD18B29088"> |
|
50 <image href="GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e149619_href.png" scale="100" placement="inline"/> |
|
51 </fig> </section> |
|
52 <section id="GUID-84DFAB24-BC7F-45B2-813D-6CD05EBCF34F-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-4"><title>APIs</title><p>The |
|
53 OOM Monitor Client API consists of <xref href="GUID-02D1911A-D2E5-3D28-9B05-75DA0A75DE73.dita"><apiname>ROomMonitorSession</apiname></xref> class. |
|
54 The main functions of this class are:</p><table id="GUID-CF94290C-7BE9-418F-9CF0-93DE74814097-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-4-3"> |
|
55 <tgroup cols="2"><colspec colname="col1" colwidth="0.70*"/><colspec colname="col2" colwidth="1.30*"/> |
|
56 <tbody> |
|
57 <row> |
|
58 <entry><p><b>Function</b></p></entry> |
|
59 <entry><p><b>Description</b></p></entry> |
|
60 </row> |
|
61 <row> |
|
62 <entry><p><xref href="GUID-1F51447A-B975-3767-8ED9-5E1B98E8A672.dita"><apiname>RequestFreeMemory()</apiname></xref></p></entry> |
|
63 <entry><p>Requests the OOM monitor to allocate RAM.</p></entry> |
|
64 </row> |
|
65 <row> |
|
66 <entry><p><xref href="GUID-C8FA6C1A-AE06-3E4D-9884-FAAA93239D13.dita"><apiname>SetOomPriority()</apiname></xref></p></entry> |
|
67 <entry><p>Sets the priority for an application as high, busy or normal. The |
|
68 application priorities must be defined in <codeph>TOomPriority</codeph> variable.</p></entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p><xref href="GUID-2B246C7F-8A7F-3AA7-8150-657A45CF8F57.dita"><apiname>RequestOptionalRam()</apiname></xref></p></entry> |
|
72 <entry><p>Requests the OOM monitor to allocate optional RAM.</p></entry> |
|
73 </row> |
|
74 </tbody> |
|
75 </tgroup> |
|
76 </table><p>The OOM Monitor Client API also consists of <xref href="GUID-ACE03F26-555A-363E-B220-44FCA7E8EACB.dita"><apiname>COomMonitorPlugin</apiname></xref> class. |
|
77 The main functions of this plug-in class are:</p><table id="GUID-CF94290C-7BE9-418F-9CF0-93DE74814097-GENID-1-8-1-10-1-1-8-1-5-1-4-1-3-4-5"> |
|
78 <tgroup cols="2"><colspec colname="col1" colwidth="0.70*"/><colspec colname="col2" colwidth="1.30*"/> |
|
79 <tbody> |
|
80 <row> |
|
81 <entry><p><b>Function</b></p></entry> |
|
82 <entry><p><b>Description</b></p></entry> |
|
83 </row> |
|
84 <row> |
|
85 <entry><p><xref href="GUID-E51E399F-AB9D-3587-9985-5E5016F49587.dita"><apiname>FreeRam()</apiname></xref></p></entry> |
|
86 <entry><p>Requests to release RAM when the system RAM level becomes low.</p></entry> |
|
87 </row> |
|
88 <row> |
|
89 <entry><p><xref href="GUID-6D853E56-6EE6-398A-B9BF-BB35C4D5729D.dita"><apiname>MemoryGood()</apiname></xref></p></entry> |
|
90 <entry><p>Called when the system RAM level improves to good from low RAM situation. |
|
91 Once the memory level is good, the OOM plug-in can again start allocating |
|
92 optional RAM.</p></entry> |
|
93 </row> |
|
94 </tbody> |
|
95 </tgroup> |
|
96 </table></section> |
|
97 <section id="GUID-1D0FDADB-ACAC-4507-BF63-E78A7F322133"><title>Typical Uses</title><p>Applications |
|
98 can use the following functionality provided by the OOM Monitor component |
|
99 to: </p><ul> |
|
100 <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 |
|
101 Allocation</xref>.</p></li> |
|
102 <li><p>Change its priority in order to protect itself from being closed by |
|
103 the OOM Monitor. For more information, refer to <xref href="GUID-8F8E3814-7ED6-4218-BEEF-741AE0E9366F.dita">Changing |
|
104 the Priority</xref>.</p></li> |
|
105 <li><p>Allocate optional RAM to applications when additional RAM is requested. |
|
106 For more information, refer to <xref href="GUID-217C992B-AC56-42A7-9920-DEC891D233A5.dita">Requesting |
|
107 for Optional RAM Allocation</xref>.</p></li> |
|
108 <li><p>Prevent OOM errors from happening by monitoring the amount of free |
|
109 RAM in the system. When the amount of free RAM drops below the specified threshold |
|
110 value, OOM Monitor automatically closes applications that are staying idle |
|
111 in the background in order to give more RAM to the applications that are active. |
|
112 For more information, refer to <xref href="GUID-0371FD21-D988-4560-891F-2840C36AB2E2.dita">Out |
|
113 of Memory Error</xref>.</p></li> |
|
114 <li><p>Assign priority for each action that can be used to release RAM (i.e. |
|
115 closing an application or calling an OOM plug-in). When releasing RAM, OOM |
|
116 Monitor uses the priorities to determine the order of closing applications |
|
117 and calling plug-ins. As a result RAM is always released by minimizing the |
|
118 negative impact to the user, provided the priorities are correctly configured |
|
119 for the device. For more information, refer to <xref href="GUID-178488C1-5453-490F-B168-9D73DB5BAE47.dita">Priority |
|
120 Configuration</xref>.</p></li> |
|
121 </ul></section> |
|
122 <section id="GUID-23F8161E-5057-4ADD-BD2F-BC87F45B4B2E"><title>Related information</title><ul> |
|
123 <li><p><xref href="GUID-F6A33835-D677-41D0-86BB-812E3AFA5192.dita">OOM Monitor |
|
124 Concepts</xref></p></li> |
|
125 <li><p><xref href="GUID-C7AA92A9-9595-439A-A3E7-769E36D61FEE.dita">Using OOM Monitor</xref></p></li> |
|
126 <li><p><xref href="GUID-88752800-83BD-4845-80A0-6B65D8D81924.dita">OOM Monitor |
|
127 Reference</xref></p></li> |
|
128 </ul></section> |
|
129 </conbody></concept> |