Embedded Wizard Studio: Memory (RAM) usage window

The Memory (RAM) usage window provides a view on stock change of all objects created dynamically during an active prototyping session as well as on the overall memory usage of the tested application. As such it is useful in order to monitor how the number of existing objects raises and declines while you test a GUI component. The Memory (RAM) usage window tracks the creation and the disposal of objects and the resulting changes of the memory usage:

Memory (RAM) usage window while prototyping an application

Dynamically created objects and the Garbage Collector

Usually, new objects are created with the operator new. However, global entities like autoobjects, bitmap and font resources are also considered as dynamically created instances. They are created automatically on demand just at the moment when they are accessed within the GUI application.

Once created the object remains alive until it is not used anymore. Embedded Wizard contains for this purpose a Garbage Collector, which takes care of the automatic detection and disposal of unused dynamically created objects. An object is considered as not used if there is absolutely no reference the application can use to access the object.

Show the Memory (RAM) usage window

The Memory (RAM) usage window appears automatically when the prototyping session is started. However, if you have previously hidden the window, you can show it again by using the shortcut Alt9 or the menu item WindowMemory (RAM) usage.

Unlike other debugging windows, the Memory (RAM) usage window is available even if the GUI application is actually not paused, so you can observe how the number of objects and the memory usage changes while you are interacting with the application.

Chora objects

The upper area of the Memory (RAM) usage window contains an overview of Chora objects existing before and after the recent garbage collection. This list is composed of the following eight columns:

Column

Description

Objects of class

The first column displays the name of the class the respective objects descend from. The objects are instances of this class.

Before GC

The second column displays the number of objects existing just before the last garbage collection begun.

After GC

The third column displays how many objects have survived the last garbage collection. Accordingly the difference between values from the column Before GC and After GC results in the number of objects detected and disposed by the last garbage collection cycle.

Change

The forth column compares the number of objects between the last and its preceding garbage collection cycle. Positive values indicate that the number of objects is grown.

Peak

The fifth column displays the maximal number of objects existing at the same time since the begin of the actual prototyping session.

RAM

The sixth column displays the amount of memory (RAM) occupied by all objects of the respective class which have survived the last garbage collection.

RAM Peak

The seventh column displays the amount of memory (RAM) occupied maximally by objects of the respective class. This corresponds to the value from the column Peak.

Trend

The eighth column displays a trend calculated from the last 32 garbage collection cycles. The trend indicates whether the object stock grows, shrinks or remains unchanged. The more triangles pointing upwards the more the increase of the number of objects. Triangles pointing down imply that the number of objects declines.

The items within the list are sorted alphabetically according to the column with the currently highlighted caption. By clicking on the caption of another column the sorting will change:

The last item within the list (regardless of the list sorting) is always the TOTAL item. It contains the summary by taking in account all Chora objects. For example, the values in the columns Before GC and After GC display the total number of all Chora objects before and after the recent garbage collection. Similarly the value in the column RAM shows how much memory is still occupied by all objects which have survived the recent garbage collection. Consequently the column RAM Peak shows the amount of memory used maximally at the same time by existing Chora objects:

IMPORTANT

The memory (RAM) usage is estimated without taking in account any optimization aspects. As such it may differ from the memory usage in the real target device. Also, the displayed value do not include the memory needed by Graphics Engine nor strings. It expresses just how much memory the particular Chora objects will occupy by themselves.

Track changes

The Memory (RAM) usage window detects when during the prototyping session the number of monitored objects changes and highlights automatically the affected items with green color. This color fades out with every new garbage collection cycle allowing you to simply distinguish what has changed recently.

Inspect existing objects and their class

You can navigate in the window and inspect all existing objects descended from the class in the selected item:

To navigate in the list use the keys Up and Down.

To inspect the objects double click on the corresponding item

... or press the key ENTER while the item is selected.

The inspected objects are listed within the Chora Objects window. Trying to inspect the objects while the prototyping sessions is active will cause the session to pause first before the Chora Objects window is shown.

Furthermore you can inspect the class of the particular objects. The class is opened in Composer window. For this purpose:

Click with right mouse button on the corresponding item to open the context menu.

In the context menu select the command Inspect class.

Track memory (RAM) usage

The bottom half of the window displays the memory usage diagram. The diagram is composed of bars, each bar representing one garbage collection performed in the past. The height of a bar corresponds to the amount of memory occupied by application just before the respective garbage collection was started. It is as such the maximum amount of memory used at this time. The maximum amount of memory needed by the application since it was started is displayed additionally as a kind of water level. This value reflects how much memory the application will need at the runtime in your target device:

Each bar is divided in four categories represented by four colors. The larger the quantity of the respective category in the total memory usage, the larger the area filled with this color. Following are the categories:

Category

Color

Description

Graphics objects

Memory used by Graphics Engine. This includes bitmap and font resources, off-screen buffers needed for e.g. buffered GUI components, storage of Path Data objects, memory required to render text and many other data structures needed to process all drawing operations.

Strings

Memory needed to store string contents.

Signals & observers

Memory needed to store signals and observers.

Chora objects

Memory occupied by Chora objects themselves (see the section above Chora objects).

For every bar you can display additional details information. These are shown in a tooltip window when you rest the mouse pointer over the bar for a short period. Since you can display this information for each bar individually it is useful to get details regarding the amount of memory used by the application in the past:

IMPORTANT

The memory (RAM) usage is estimated by assuming the minimal Graphics Engine and Runtime Environment configuration. It also does not take in account any C compiler specific optimization aspects. As such it may differ from the memory usage in the real target device. Also, the garbage collection in the prototyping environment runs very seldom compared with the target system. From this arises the effect of more resources being considered as occupied at the same time during the prototyping. Finally, please note that depending on your target device there will be additional memory needed for the frame buffer. This value is explicitly not included in this statistic. For more details please see the section Memory Footprint.

Take in account configuration limitations

In the bottom area of the window you see few Graphics Engine configuration parameters deduced during the prototyping session. These are the absolut minimum to allow your application to run in a C compatible target system:

The size of the glyph cache surface is configured by using the C macros EW_MAX_GLYPH_SURFACE_WIDTH and EW_MAX_GLYPH_SURFACE_HEIGHT (or the corresponding global variables EwMaxGlyphSurfaceWidth and EwMaxGlyphSurfaceHeight). In turn, the size of the issue buffer is configured by the macro EW_MAX_ISSUE_TASKS or the corresponding global variable EwMaxIssueTasks. If you are using one of our prepared Build Environments you can configure the macros conveniently in the file ewconfig.h. Otherwise you configure them in the make file or your build process. For details please see the section: Memory Footprint.

TIP

The displayed values are the absolut minimum. In the practice, you should configure these values more generously. How much, it is up to you. It is finally a compromise between the memory usage and the performance. For example, the larger the glyph cache surface, the more glyphs can be stored there without needing to reload them again and again. Thereupon the text rendering speeds up. Similarly, the larger the issue buffer, the more drawing operations can be optimized with the aim to detect and eliminate unnecessary drawing operations.

Memory (RAM) usage and WebGL

The Memory (RAM) usage window provides helpful information to track the memory usage and deduce the minimal configuration for the Graphics Engine to run your application. These values are applicable for a C compatible Platform Package only.

If you are creating an application intended to run in a Web browser (with the WebGL Platform Package), the estimated values are not transferable to the JavaScript engine serving as runtime environment. In other words, we have no possibility to estimate nor control the memory usage in a Web browser.

Force garbage collection

Due to performance aspects, the prototyping environment runs the garbage collection approximately every 0.25 .. 10 seconds. The more Chora objects that have been created in the meantime the more frequently the garbage collection. This differs from the real behavior in the target system, where under normal circumstances the garbage collection is triggered periodically after every screen update. If necessary, however, you can manually force the prototyping environment to run an additional garbage collection cycle:

To request a new garbage collection cycle press the key CtrlShiftF5

... or select the menu item DebugForce garbage collection.

The additional garbage collection cycle will start immediately after the next screen update. Please note, if the actual prototyping session is paused, you can't force the garbage collection because the prototyping environment is inactive during this phase.

For your information, the Memory (RAM) usage window counts the performed garbage collections and displays this value in the bottom right corner. Furthermore, as explained in the sections above, each garbage collection corresponds to a single bar within the diagram lying above:

IMPORTANT

Since the prototyping environment triggers the garbage collection very seldom, the amount of occupied resources will be greater than the corresponding value in the target device. This peculiarity is important when you are tracking the memory (RAM) usage and the number of Chora objects. The memory usage is roughly estimated and it lies usually above the corresponding value in the target device.

Hide the window

The Memory (RAM) usage window disappears automatically as soon as the prototyping session is terminated but unlike other debugging windows, it doesn't disappear when you resume a previously paused debugging session. If desired, however, you can hide this window explicitly:

To hide the window click on its close button in the top-right corner.

While the prototyping session is paused the window can also be hidden using following steps:

To hide all debugging windows while the prototyping session is paused press the key F6

... or select the menu item WindowShow hide debugger windows.

To show the debugging windows again simply repeat the above operation.