Profiling

To profile your code, you need to change the existing configuration options so that you can build your project with profiling enabled. When your launch configuration is set up for profiling, the IDE inserts code before each function to gather call information (Call Count instrumentation), or just after the function enters and just before the function exits (Function instrumentation).

Profiling a C/C++ project

If you're creating a Cascades C++ application and developing the application UI in C++ only, you can use the QNX Application Profiler perspective and the Application Profiler tool in the QNX Momentics IDE.

Profiling a QML project

If you're creating a Cascades project with QML components, you can use the Cascades Profiler. The Cascades Profiler is a tool that allows visual profiling of Cascades QML applications. The Application Profiler traces execution of your code and provides statistics on how much time was spent in each function. The Cascades Profiler is able to show you information about frame rendering, image loading, loading and compiling QML files, time consumed by running QML bindings, and QML signal handlers. 

Configuring the Cascades Profiler

To profile QML and JavaScript code in your Cascades application, you don't need to add or change any code in new projects that use the templates provided by the IDE. The Cascades project build system ensures that the qt_declarative_debug macro is defined in the debug build.

For existing projects, or if you want to profile an application compiled in a Device-Release configuration, you must add the following code as the first lines of your main.cpp file:

// Enable declarative debugging/profiling
#define QT_DECLARATIVE_DEBUG
#include <qt4/QtDeclarative/qdeclarativedebug.h>

You can use the Run Configurations wizard to set up your run configuration for profiling. If you are working on a new project in a new workspace, you might need to create a launch configuration for your project before you can add tools. You can create a new BlackBerry C/C++ Application launch configuration by running your app or by using the new launch configuration button in the wizard. For more information, see Setting the launch configuration.

To configure your app for profiling:

1. In the Project Explorer view, right-click any project and click Run As > Run Configurations.
2. Click the Tools tab and click Add/Delete Tool.
3. Select the Cascades Profiler check box and click OK.
4. Select the Start profiling during application launch check box if you are interested in collecting creating and compiling times. When this option is cleared, you can start profiling manually whenever you want. This feature is useful if you are only interested in profiling certain events in your app.
5. To enable profiling of all apps, click Edit and select the Enable JavaScript Debugging check box.
6. Click Apply and click Close or Run.

You can profile an application from this configuration dialog box by clicking Run. The selected app will launch and you will see the profiler connecting to the profiler port. If you selected the Start profiling during application launch check box, you will see a profile editor window showing you the elapsed time. Otherwise, you can click the Start button to start profiling. To see your profiling data, click the Stop button in the top left corner of your profile editor window.

Understanding Cascades Profiler views and data

You can view the data that's gathered by the Cascades Profiler by using the profile editor window. The profiler editor has two views:

• Timeline view: Provides details of the three main QML threads: frame rendering, image loading, and QML engine.
• Events view: Shows you the events within each thread.

Timeline view

The Timeline view shows you the time that your app is spending in the frame rendering, image loading, and QML engine threads. You can expand the Frame Rendering Thread, the Image Loading Thread, and the QML Engine Thread to see the details. You want to see a very small number of frames per second for each item in these threads. For example, a typical frame rendering span duration should be less than 16 ms so that the app can render 60 frames per second.

When you hover over a span in the Timeline view, you can see the duration and timestamp information and the thread that the span belongs to. You can adjust the view of the spans by expanding or collapsing the viewable window in the lower-left corner of the profiler editor window.

In the example below, the time window has been reduced in the navigation area (in order to enlarge the timespans shown). By default, the navigation area extends the entire width of the window.

The Image Loading thread view displays the time spent loading images as a percentage of how much time it took to load all the images. You can double-click the image in the Image Loading Thread to view the image.

The QML Engine Thread view shows you how long it takes to create and compile your app (if you started profiling during application launch). Creating and compiling your app involves binding and initializing all the properties used by your app in the QML engine thread. This process is sequential. By default, the rendering spans are ordered by timestamp in the order that they occurred.

Events view

The Events view lets you look at frame rendering information and walk through the call stack by selected events and callee or caller. You can look in the Details column to see the first lines of code that were executed for each event, or you can double-click events to open your QML file at the code that was executed. You can use the arrows to move forward or backward in the call stack.

In the example below, the main.qml thread was selected in the QML Engine Thread view. The lower window shows the events that were called by main.qml.

What to look for in the data

When you look at your profiling data, you should first look at long spans. You can order the spans by length and you can double-click the spans to see the code that they're executing. You should pay attention to the following patterns in your profiling data:

• Look at idle spans if you want to see if there's anything else going on (for example, background processes). The idle spans are hidden by default. To see the idle spans, click the Show/Hide Rendering Idle Spans button on the toolbar.

• Check out long spans of frame rendering (for example, greater than 100 ms). When your app is busy rendering frames, the UI will won't appear smooth and responsive.

• Look at the creating block. If the creating block is too long, it might be waiting for each binding to finish. Look at your code to see if you can use smaller bindings.

• Look for unnecessary bindings that are run frequently.

• Check your compile times. If your compile times are larger than you expected, you can use dynamically loaded QML assets to postpone some of the compiling in your app.

• Check the handling signal. If it's too long, you should investigate. Hover over the signal and expand the categories to find the source code.

Troubleshooting your configuration

If data doesn't appear in the profiling editor window, open the Debug or Device Log view and select the buffer set for your app and then filter for the message "QDeclarative". You should see two messages that tell you that you're using the Qt library with profiling support and a port on which Qt is awaiting connection.

You can also filter for messages containing the word "profile". You should see three messages that tell you that you have deployed the Cascades Profiler. You should also be able to see the server side connections, the trace engine instance created, and the trace engine instance registered.

If you don't see these messages, it might be because you are trying to profile with a target that is running a load that does doesn't support the Cascades Profiler. The Cascades Profiler works only on a BlackBerry device or simulator that is running version 10.1 of the device OS (or higher).