Figure 3: Application changes its own priority.
When your application is processing a task in the background it should
change its priority to busy with the SetOomPriority(EOomPriorityBusy) method
call so that the OOM Monitor doesn't close it. When the application finishes
its background task and becomes idle it should call the SetOomPriority(EOomPriorityNormal) method.
The following diagram illustrates application's priority change requests.
Figure 3: Application changes its own priority.
To prevent your application from closing by the OOM Monitor while it's
processing a task in the background, the application should change the priority
to busy by calling the SetOomPriority(EOomPriorityBusy) method.
The following code snippet illustrates an applications's critical background
processing with the busy priority:
// Create an OOM Monitor session ROomMonitorSession oomMonitorSession; CleanUpClosePushL(oomMonitorSession); User::LeaveIfError(oomMonitorSession.Connect()); // Set the priority before performing the background task iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityBusy); DoCriticalBackgroundProcessingL(); // Set the priority back to normal as the task is completed iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityNormal); // Tidy up CleanupStack::PopAndDestroy(); //oomMonitorSession, calls Close()
If your application needs to allocate more RAM than KOomMaxAllocationWithoutPermission it
must first ask permission from OOM Monitor with the void RequestFreeMemory(TInt
aBytesRequested, TRequestStatus& aStatus) method.
If the requested amount of RAM is not available the OOM Monitor will release
RAM by closing background applications having lower priority than busy.
If an application allocates RAM while being in the background, it is possible
that the application will cause itself to be closed by the OOM Monitor. The
application can avoid this by setting its OOM priority to busy.
When the RequestFreeMemory() method is used asynchronously
the OOM Monitor sets the aStatus value as follows:
aStatus is set
to KErrNoneaStatus is
set to KErrNoMemory Internally the RequestFreeMemory() method works as follows:
aStatus to KErrNone.aStatus to KErrNoMemory.An application can allocate RAM without asking the permission from the
OOM Monitor only if the amount of RAM is not over KOomMaxAllocationWithoutPermission.
When your application requests free RAM asynchronously with the RequestFreeMemory() method
call, it is not blocked during the method call handling as the figure below
illustrates.
Figure 4: Asynchronous request for free RAM
The following code snippet illustrates an asynchronous request for free RAM
const TInt KLargeValueToAllocate = 2097152; //2MB
// Start an asynchronous request for block of memory
CMemoryAllocatingObject::StartFunctionalityRequiringAllocationL()
{
User::LeaveIfError(iOomMonitorSession.Connect());
iMemoryRequester = CMemoryRequester::NewL(iOomMonitorSession, *this);
iMemoryRequester->Start(KLargeValueToAllocate);
}
// Called when the asynchronous request is completed
CMemoryAllocatingObject::MemoryRequestCompleteL(TInt aResult)
{
if (aResult == KErrNone)
{
DoFunctionRequiring_KLargeValueToAllocate_BytesL();
}
iOomMonitorSession.Close()
}
The active object implementation is the following:
// Start an asynchronous request for block of memory
void CMemoryRequester::Start(TInt aBytesRequested)
{
iOomMonitorSession.RequestFreeMemory(aBytesRequested, iStatus);
SetActive();
}
// Called when the asynchronous request is completed
void CMemoryRequester::RunL()
{
iObserver.MemoryRequestCompleteL(iStatus.Int());
}
Requesting free RAM synchronously is not recommended because the operation may take several seconds and the operating system cannot handle for example user inputs during synchronous wait. In case of a server, synchronous call blocks the server as well because it cannot serve its clients during synchronous wait. However, the synchronous request is possible when there is no need to perform other task while waiting the completion of request. The synchronous request is also easy to use implement because no active object is needed. The following picture illustrates the synchronous request for free RAM.
Figure 5: Synchronous request for free RAM
The following code snippet illustrates a synchronous request of free RAM
TInt KLargeValueToAllocate = 2097152; //2MB // Create an OOM Monitor session ROomMonitorSession oomMonitorSession; CleanUpClosePushL(oomMonitorSession); User::LeaveIfError(oomMonitorSession.Connect()); // Request free memory User::LeaveIfError(iOomMonitorSession.RequestFreeMemory(KLargeValueToAllocate)); DoFunctionRequiring_KLargeValueToAllocate_Bytes(); // Tidy up CleanupStack::PopAndDestroy(); //oomMonitorSession, calls Close()
To avoid an out-of-RAM error, your application must terminate itself without any delay whenever OOM Monitor requests so. Otherwise the time of free RAM amount below LOW_RAM_THRESHOLD gets longer and possibly another application allocates RAM during that time resulting to an out-of-RAM error.
An application doesn’t need to implement any special handling when it is
closed by OOM Monitor; the application just receives OOM Monitor initiated EEikCmdExit event.
When an application terminates the operating system releases immediately all
the RAM the application has allocated.
An out-of-RAM error occurs if an applications consume all RAM of the device . Thus it is important that all applications are prepared for out-of-RAM error and handle it properly.
The Out of Memory Monitor Client API has no extensions.
The Out of Memory Monitor Client API has no limitations.
