What It Does

BlackBerry Application Resource Monitor monitors applications when they are in the background (with the screen on or off) and when in the foreground when the screen is off. When the app is in one of these two states, it looks for excessive background wakeups (any sort of timers firing including rapid/constant repaints) and high CPU utilization.

When efficient applications are in these two states, they should not be consuming an excessive amount of CPU or exhibiting any sort of timer abuse. When the problematic application is identified, an alert may be presented to the user. If “Automatically shutdown background draining applications” is enabled, the user is alerted and the application is shut down. If it is disabled, the user is alerted and they have the ability to close the app from within the notification. The ability to automatically shut down background-draining applications can be enabled and disabled within the Application Resource Monitor options access on a BlackBerry® smartphone by going to Options -> Device > Application Resource Monitor. The default setting is for it to be enabled.

Applications can also be whitelisted so that they are not shut down by Application Resource Monitor. To whitelist an application, users need to first receive an alert. If the ability to automatically shut down background-draining applications is disabled, they are simply alerted about the problematic application. They can acknowledge the alert (OK), whitelist the app (Ignore Future Alerts) or choose to manually shutdown the app (Kill it Themselves). If it is enabled, the application will be shut down and an alert presented to the user. The user can then open the alert to acknowledge and dismiss it, or whitelist the application to ignore this application going forward. To remove items from the whitelist, users can go to Options > Device > Application Resource Monitor.

How to Avoid Being Shut Down

You can prevent your application from being shut down by Application Resource Monitor by detecting and adapting to the state changes described above. If we use the example of a game, you can put your game into a paused state where it is not making any game play calculations for things like physics or artificial intelligence, and so it is not refreshing the screen when the game has moved to the background or when the screen has turned off.

Detect Moving to the Background

There are two ways to detect that your application is no longer in the foreground. Application.deactivate() is called when an application is moved to the background, and Application.activate() is called when the application moves to the foreground. Override both of these methods to detect the backgrounding and foregrounding events.

An application screen can override the Screen.onObscured() method to be notified when another screen appears on top of it, which may or may not be another application. This method is fired when the menu appears or if a dialog from your application is shown, which could be another point where you would want to pause your game. Screen.onExposed() is the matching method that is fired when screens on top of your application have been removed and your screen moves to the top-most position on the screen stack.

Handling the Shutdown Request Gracefully

Overriding Application.requestClose() can allow your application to respond gracefully to a termination request. Returning true from this method will allow your application 10 seconds to process any required cleanup before it is shut down. Returning false will shut down the application immediately. This can also be used for diagnostic purposes, as it can log information about the state of the application for debugging purposes. Be careful to avoid logging excessive amounts of data in the production version of your application. requestClose is also fired for visible applications (those for which acceptsForeground() returns true) if they have not been used for one hour, regardless of whether or not they are using background timers or significant CPU. (However, applications are not terminated after being idle for one hour. This is simply a suggestion that they could close to conserve resources.)

Application termination from Application Resource Monitor is not limited to visible applications – in fact, it’s arguably more important that non-visible processes are terminated since users are not otherwise able to easily shut them down. You should consider the possibility that their processes may be shut down and ensure that this does not hinder future use of your app.

Verifying Efficiency using the BlackBerry Java Plug-in for Eclipse

Efficient applications that already take into account the states described above should not be impacted. However, it makes sense to do some performance testing of your application to verify that it does act like a good citizen. A new view has been added to version 1.5.2 of the BlackBerry Java® Plug-in for Eclipse™ that allows you to do just that. The new Process View allows you to monitor CPU utilization of your application, where you can monitor the statistics presented to observe the impact of your application while it is in the background and/or when the screen has turned off.

BlackBerry Java Plug-in for Eclipse Profiler View

How to Determine if an Application was Shut Down by Application Resource Monitor

Application Resource Monitor will create an entry in the event log every time it shuts down an application. You can view the event log on a BlackBerry smartphone from the home screen by holding down the Alt key and pressing LGLG. You can also extract it using the javaloader command line tool (javaloader –u eventlog > mylog.txt).
Application Resource Monitor will log detailed information about why the application was shut down and how it handled the shutdown request. Stack traces may be useful if the alert stems from processing too many timer events in the event handling thread (usually from the use of invokeLater with timed runnables and very short timeouts), but it’s more likely that the stack trace won’t capture the specific event processing at the time of the trace dump.

Setting the minimum event log level to “information” will provide more information about background activity that doesn’t meet the criteria to trigger notification or automatic shutdown – i.e. background timer activity below the minimum wakeup rate threshold. Here is a sample event log entry that shows an application being shut down by Application Resource Monitor, with comments added describing the entries shown bolded in red:

The BlackBerry Profiler View in the BlackBerry Java Plug-in for Eclipse should always be the first tool you use to test and enhance the efficiency of your application. However, you may want to test how your application behaves in the event that it gets shut down by Application Resource Monitor. To do so, you can lower the thresholds that it uses to determine if an application should be shut down. This can also be used in conjunction with the BlackBerry Profiler View to ensure that your application stays well under the default threshold. To modify this threshold, go to Options -> Application Resource Monitor on your BlackBerry smartphone, then type FLTR to display the additional options. You should see a screen that has these additional options:

Here are some tips on how to configure these settings while testing your application.

Reduce the wakeup threshold to a low level, perhaps the minimum. It is intentionally set at a very conservative (high) level by default.

Disable automatic shut down – this allows you to immediately profile the application when Application Resource Monitor triggers an alert and before changing the state, to see what’s going on in your application.

Disable transient filtering – this will speed up detection of sustained problems.

If you are performing very frequent restarts of your BlackBerry smartphone while testing, reduce the startup delay to 0.

Shutting Down

The BlackBerry Application Resource Monitor is designed to help consumers get the most battery life out of their BlackBerry smartphone by closing applications that are abusing resources leading to noticeable battery drain. By following the steps outlined in this article, you can ensure that your application behaves like a good citizen on the device and is never noticed by Application Resource Monitor.