OOM Monitor Client API: API description

Overview

This section provides you with an overview of the Out of Memory Monitor Client API features.

General functionality

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 LOW_RAM_THRESHOLD threshold value, the OOM Monitor is triggered and it releases RAM by closing applications running on background in order to raise the amount of free RAM above a defined GOOD_RAM_THRESHOLD treshold value. These two configurable thresholds (LOW_RAM_THRESHOLD and GOOD_RAM_THRESHOLD) exist to provide a hysteresis and thus ensuring sufficient amount of free RAM in the mobile device.

Whenever the amount of free RAM decreases below LOW_RAM_THRESHOLD the OOM Monitor releases RAM by closing applications which are not deemed to be in connection with the active applications. This process is called as normal RAM rotation.

Out of Memory Priority

The OOM priority

When releasing RAM the OOM Monitor uses priorities to determine the order of closing the applications. Each application is assigned with a priority which determines the order (in relation to other applications) of closing the application.

A priority of an application is a measure of impact to the mobile device user in case the OOM Monitor closes that application. Thus a low priority means that the closing of that application will have a low impact on the user, whereas a high priority means that the closing will have a high impact on the user.

The OOM Monitor closes the lowest priority application first (as this will have the smallest impact on the user), then the second lowest, etc. until the amount of the free RAM has risen above the GOOD_RAM_TRESHOLD value.

If two or more applications have the same priority the OOM Monitor closes these applications based on their idle time (i.e. the time the application has stayed idle in the background) in the following order:

1. The longest idle time
2. The second longest idle time
3. etc.

The priority of each internal and 3rd party S60 application is defined in the OOM Monitor configuration file which is set up for each device.

3rd party applications can use he following priorities:

• Normal (the DEFAULT priority)
• High
• Busy (the "infinite" priority)

By default 3rd party applications' priority is Normal but any 3rd party application can change its own priority by using the Out of Memory Monitor Client API.

The OOM Monitor can never close a foreground application. For this reason it can be said that the priority of the foreground application is Busy. The mobile device user can also define the Busy priority for background applications which means that those applications are never closed by the OOM Monitor.

Dynamic rules for changing the priority

The OOM Monitor configuration file can contain rules which determine how the OOM Monitor changes the priority of one or many applications. The changing of the priority is based on two following issues:

• the application's idle time: the OOM Monitor decreases the priority of an application after it has stayed idle in the background for a certain period of time
• grouping applications: when whichever application belonging to a group is in the foreground the OOM Monitor protects the rest of the applications belonging to this group from closing by assigning them a priority higher than the one of the background application not belonging to this group

Changing the priority with OOM Monitor Client API

An application can change its OOM priority by calling the OOM Monitor Client API's void SetOomPriority() method. For more information, see allowing an application to protect itself from closing by the OOM Monitor.

Characteristics of void SetOomPriority(TOomPriority aPriority) method's TOomPriority parameter values

• EOomPriorityNormal:
  • The OOM Monitor can close the application when necessary
  • All 3rd applications should use this priority unless there is a specific reason to change the priority
• EOomPriorityHigh:
  • Allows an application to change its OOM priority so that the OOM Monitor will not close the application in normal RAM rotation
  • When the amount of free RAM is extremely small the OOM Monitor may close the application
  • When the application with the high priority has been a long time idle in the background the OOM Monitor automatically decreases its priority to normal, preventing it from consuming the RAM unnecessarily
• EOomPriorityBusy:
  • Allows an application to increase its OOM priority so that the OOM Monitor doesn't close the application
  • This parameter should be used only in the following cases:
    • an application is processing a task in the background
    • an application provides a network service and it must listen to certain events from the network all the time
  • The application must decrease its priority from busy to high or normal by itself as soon as the background task is complete and the application becomes idle in the background. The priority can be decreased to
    • high with SetOomPriority(EOomPriorityHigh) method call
    • normal with SetOOMPriority(EOomPriorityNormal) method call

When to use the OOM Monitor Client API?

The OOM Monitor Client API is meant to be used in the following two cases:

• an application needs to change its own priority at run time because the OOM Monitor must not close it. It can be
  • an application which is processing a task in the background, for example:
    • Music Player is playing music
    • Download Manager is downloading a file

    By using the OOM Monitor Client API an application can dynamically change its priority for that period of time when an active task is ongoing in the background.

  • a network service providing application which listens certain events from the network all the time, for example:
    • IP Phone application receiving IP calls
    • Instant Messaging application receiving messages

    A network service providing application cannot be closed, otherwise the service will stop.

• A 3rd party application needs to change its priority from the normal priority

  A 3rd party application cannot be included in the OOM configuration file but it can change its OOM priority with the OOM Monitor Client API.

How to avoid out-of-RAM error in applications

To avoid a situation where the free RAM would run out because applications allocated the RAM faster than the OOM Monitor released it, the OOM Monitor has the KOomMaxAllocationWithoutPermission constant. It defines the maximum amount of RAM that an application can safely allocate within two seconds without first asking permission from OOM Monitor.

The KOomMaxAllocationWithoutPermission value defined in the OOM Monitor header file will not be decreased in the future, so allocating not over KOomMaxAllocationWithoutPermission amount of RAM is safe. The RAM can be allocated quickly in small pieces as long as the total amount of allocated RAM within two seconds is less than KOomMaxAllocationWithoutPermission.

Out-of-RAM error in normal RAM rotation

An application should always be prepared for an out-of-RAM error because it can still occur for example in the following situations:

• An application allocates more than KOomMaxAllocationWithoutPermission amount of RAM within two seconds without asking the permission and the OOM Monitor cannot release the RAM fast enough for the application.
• An application allocates less than KOomMaxAllocationWithoutPermission amount of RAM within two seconds but
  • some applications don't release RAM quickly enough when requested OR
  • several applications allocate RAM at the same time

Use cases

The use cases for the Out of Memory Monitor Client API demonstrate how to

• allow an application to protect itself from closing by OOM Monitor
• allow an application to allocate safely a large amount of RAM

API class structure

The Out of Memory Monitor Client API consists of ROomMonitorSession class whose class definition is as follows:

class ROomMonitorSession : public RSessionBase

ROomMonitorSession class has

• one variable:
  • TOomPriority // Defines the application priorities (normal, high, and busy) of the OOM monitor
• among others the following methods:
  • RequestFreeMemory () // Requests the OOM monitor to free RAM
  • SetOomPriority () // Sets the application priority of the OOM monitor

---

Copyright © Nokia Corporation 2001-2008