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'
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.
- Prevent OOM errors from happening by monitoring the amount of free RAM in the system. When the amount of free RAM drops below
a configurable threshold value, OOM Monitor Client API automatically closes applications that are staying idle in the background
in order to give more RAM to the applications that the user is currently using.
- OOM Monitor Client API assigns priority for each action that can be used to release RAM. When releasing RAM, OOM Monitor Client
API uses the priorities to determine the order of closing applications. As a result RAM is always released by minimizing the
negative impact to the user, provided the priorities are correctly configured for the device.
- Provide an API, which allows an application to change its priority in order to protect itself from being closed by OOM Monitor
Client API.
- Provide an API, which allows an application to safely allocate a large amount of RAM.
The application does not require any capabilities. The program capabilities are defined in mmp-files as CAPABILITY NONE.
This example makes use of the standard Symbian OS application framework, comprising the Application, App UI, Document and
Container classes.
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.
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.
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.
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.
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
See the following sections to ensure that the example application works properly.
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).
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.
Open the example app, select Options -> Set oom priority -> High -> OOM priority is changed to 'High'
Open the example app, select Options -> Set oom priority -> Busy -> OOM priority is changed to 'Busy '
Open the example app, select Options -> Set oom priority -> Normal -> OOM priority is changed to 'Normal'
|
© Nokia 2009
|

|