Nokia N97 SDK
Example Applications Guide

[OomExample]

1. About this Example
1.1 APIs demonstrated
2. Capabilities
3. Design and Implementation
3.1 API Description
3.2 Synchronous request for freeing RAM
3.3 Asynchronous request for freeing RAM
3.4 Set Priority High , Busy or Normal
4. Running the Example.
4.1 Requesting free memory using the Asynchronous method
4.2 Requesting free memory using the Synchronous method:
4.3 Changing application's OOM priority to 'High'
4.4 Changing application's OOM priority 'Busy'
4.5 Changing application's OOM priority 'Normal'


1. About this Example

This example describes how the new OOM Monitor Client API works and how applications can benefit from its functionality.

As an overview, OOM Monitor Client API provides the following functionality.

1.1 APIs demonstrated


2. Capabilities

The application does not require any capabilities. The program capabilities are defined in mmp-files as CAPABILITY NONE.


3. Design and Implementation

This example makes use of the standard Symbian OS application framework, comprising the Application, App UI, Document and Container classes.

3.1 API Description

The basic function of the OOM Monitor Client API is to monitor the amount of free RAM in the system. Whenever the amount of free RAM decreases below a defined LOW_RAM_THRESHOLD threshold value, the OOM Monitor Client API is triggered and it releases RAM by closing applications running on background in order to raise the amount of free RAM of the system above defined GOOD_RAM_THRESHOLD treshold value. These two configurable thresholds (LOW_RAM_THRESHOLD and GOOD_RAM_THRESHOLD ) exist to provide hysteresis and thus ensuring sufficient RAM in the mobile device.

Functionality.jpeg

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

RAM_hysteresis.jpeg

3.2 Synchronous request for freeing RAM

HandleSynchronouslyRequestFreeMemoryMenuItemSelectedL() method is used to synchronously free memory before making an allocation. First the user has to input how much memory needs to be allocated. An application making an allocation greater than KOomMaxAllocationWithoutPermission bytes should first request free memory from the OOM Monitor Client API. The maximum amount of memory that can be allocated without permission is defined in oommonitorclient.h as below.

 const TInt KOomMaxAllocationWithoutPermission = 1048576;

The request can take a number of seconds to complete, so the synchronous version of the API is likely to be inappropriate in most real application situations. Return of KErrNone on executing iOomMonitorSession.RequestFreeMemory(iBytesRequested) suggests that either there was already plenty of memory in the system, or the OOM Monitor Client API has managed to free enough memory for use to safely make the allocation. Return of KErrMemory suggests that the OOM Monitor Client API has not managed to free sufficient memory. It is not safe to make a large allocation.At this point the application could try freeing it's own resources and then make another call to ROomMonitorSession::RequestFreeMemory()

For small allocations, less than KOomMaxAllocationWithoutPermission there is no need to inform the OOM Monitor Client API before allocation. If the memory level falls before a certain threshold, the OOM Monitor Client API will automatically start trying to free memory.

App_req_RAM_sync.jpeg

3.3 Asynchronous request for freeing RAM

HandleAsynchronouslyRequestFreeMemoryMenuItemSelectedL() method is used to asynchronously free memory before making an allocation. First user has to input how much memory need to be allocated. An application making an allocation greater than KOomMaxAllocationWithoutPermission bytes should first request free memory from the OOM Monitor Client API. The request can take a number of seconds to complete, so the asynchronous version of the API used here is likely to be the more appropriate in one in most real application situations. The asynchronous call to the oommonitor is wrapped up in an active object.

For small allocations, less than KOomMaxAllocationWithoutPermission there is no need to inform the OOM Monitor Client API before allocation. If the memory level falls before a certain threshold, the OOM Monitor Client API will automatically start trying to free memory.

App_req_RAM_async.jpeg

3.4 Set Priority High , Busy or Normal

HandleHighMenuItemSelectedL() method is used to set the application's priority to High. This inform the OOM Monitor Client API that the application is doing something of high priority while being in the background. Closing high priority applications will typically be one of the last resorts the OOM Monitor Client API will take in the event of RAM levels going below the device specific low memory threshold. Note that the OOM Monitor Client API will never close the foreground application so it is only necessary to call this API if doing important background processing

HandleBusyMenuItemSelectedL() method is used to set the application's priority to Busy. This inform the OOM Monitor Client API that the application is busy doing some critical task. The OOM Monitor Client API will never close applications that have set themselves as busy even if system RAM goes below the device specific low memory threshold. Note that the OOM Monitor Client API will never close the foreground application so it is only necessary to call this API if doing critical background processing

HandleNormalMenuItemSelectedL() method is used to set the application's priority to Normal. This should be called after ROomMonitorSession::SetOomPriority(ROomMonitorSession::EOomPriorityHigh) or ROomMonitorSession::SetOomPriority(ROomMonitorSession::EOomPriorityBusy) to return the applications's priority back to it's default value

App_changes_priority.jpeg


4. Running the Example.

See the following sections to ensure that the example application works properly.

4.1 Requesting free memory using the Asynchronous method

Open the example application, select Options -> Asynchronously request free memory-> Enter amount e.g. 2048 (kB) -> Wait a while -> "Memory request complete. Bytes freed: ..." is shown . (e.g. if 2048 kB was inputted, then bytes freed shown is 2097152).

4.2 Requesting free memory using the Synchronous method:

Open the example app, select Options -> Synchronously request free memory-> Enter amount e.g. 2048 (kB) -> Wait a while (app does not respond to user input during the wait) -> "Memory request complete. Bytes freed: ... " is shown.

4.3 Changing application's OOM priority to 'High'

Open the example app, select Options -> Set oom priority -> High -> OOM priority is changed to 'High'

4.4 Changing application's OOM priority 'Busy'

Open the example app, select Options -> Set oom priority -> Busy -> OOM priority is changed to 'Busy '

4.5 Changing application's OOM priority 'Normal'

Open the example app, select Options -> Set oom priority -> Normal -> OOM priority is changed to 'Normal'

© Nokia 2009

Back to top