In this section:

Starting Inuse on Windows

Run the inuse.exe file located int he <INSURE_INSTALL>/bin directory. See Inuse GUI for usage.

Starting Inuse on Unix

Setting up and running Inuse involves:

1. Running the GUI.
2. Linking your program to Inuse.
3. Adding the inuse on option to your .psrc file and running the application program.

During runtime, you can view and manipulate the displays shown by the GUI. You can even watch the memory allocation as you single step through your program from a standard code-oriented debugger. This section will cover each of these steps in detail.

Additional Details for Unix

You must start the Inuse program before you attempt to display results from any user application. The application will run without displaying any memory activity if you run it before starting Inuse. In normal use, you should enter the inuse command once and leave it running as a background process.

You should compile your code with your regular compiler and then link with Insure++ based on your source, as shown in the following examples:

insure gcc -g -o foo foo.c

insure /path/to/gcc -g -o foo foo.c

insure g++ -g -o foo foo.cpp

To enable runtime display of memory activity, you need to set the following option in your .psrc file:

insure++.inuse on

Inuse can be linked simultaneously with any number of application programs. By turning this option on and off, you can control when your programs connect to Inuse. If you exit Inuse, you must restart it before running any applications for which you wish to display memory activity.

Inuse GUI

Executing the inuse command opens the Inuse GUI on Unix. When you connect a program to Inuse, the connection will appear in the main window. The “plugged in” symbol next to the connection shows that the program is currently sending data to Inuse. If you tell Inuse to stop receiving memory data from the program, this symbol will change to a stop sign. When the program finishes its run or is terminated, the symbol is replaced with a “RIP.”

The “look and feel” of a windowing application will vary quite significantly from system to system. As a result, the version of the window that you see might differ from that shown above.

Menu Bar

The menu bar contains commands that manage Inuse memory functions.  

File

• Load a file for inspection through Inuse.
• Save the currently open file.
• Save a file under a new name and location using Save as.
• Save all files currently open in Inuse using Save all.
• Save all files currently open in Inuse to a certain location and name using Save all as.
• Choose an executable file and Run it.
• Exit the Inuse GUI.

Processes

• Attach a Label to a linked application.
• Use Next or Prev to choose among linked applications.
• Del (delete) a program from the list.
• Stop receiving memory display information from a linked program.
• Step through one allocation or free request from the program at a time.

Reports

The types of reports Inuse generates are described below. For more information on these reports, see Reviewing Inuse Reports.

• Heap History This graph displays the amount of memory allocated to the heap and the user process as a function of real (that is, wall clock) time. This display updates periodically to show the current status of the application, and can be used to keep track of the application over the course of its execution.
• Block Frequency This graph displays a histogram showing the number of blocks of each size that have been allocated. It is useful for selecting potential optimizations in memory allocation strategies.
• Heap Layout This graph shows the layout of memory in the dynamically allocated blocks, including the free spaces between them. You can use this report to “see” fragmentation and memory leaks. You can scan through different areas of the layout by pressing the Fast Left (F.left), Fast Right (F.right) and left and right buttons on the Heap Layout tool bar. You can also zoom in (+) and out (-) of the layout by pressing the zoom buttons. (These options are also available in the Controls menu.) Clicking any block in the heap layout will tell you the block’s address, size, and status (free, allocated, overhead, or leaked). Clicking an allocated or leaked block will also open a window telling you the block ID, block address, stack size, and stack trace for the selected block.
• Time Layout This graph shows the sequence of allocated blocks. As each block is allocated it is added to the end of the display. As blocks are freed, they are marked green. From this display, you can see the relative size of blocks allocated over time. For example, this will allow you to determine if you are allocating a huge block at the beginning of the program or many small blocks throughout the run.
• Usage Summary This bar graph shows how many times each of the memory manipulation calls has been made. It also shows the current size of the heap and the amount of memory actively in use. (The heap fragmentation can be computed simply from these numbers as (total-in_use)/ total).
• Usage Comparison Graphically compares memory from different runs of one executable or among runs of different executables.
• Query The query function enables you to “view” blocks of memory allocated by your program according to their id numbers, their size, and/or their stack traces. You can edit the range of the query according to block id, block size, and stack trace. By “grouping” blocks of memory in this way, you can better understand how memory is being used in your program. The range options let you narrow or broaden your query to your specifications. For example, you can see how much memory is being allocated from a single stack trace or by the entire program combined. For each query you can choose whether you receive a detailed (i.e. containing block id, block size, and stack trace information) or summarized report.

Options (Windows)

Choose Auto Reports to choose the reports shown at each new connection. You will be able to enable the following reports:

• History layout
• Memory usage
• Time layout
• Heap layout
• Frequency
• Memory comparison

Help

Online help feature for Inuse. Options include:

• Overview: Provides a general introduction to the Inuse feature.
• Inuse Reports. Describes the types of reports Inuse generates.
• Inuse Queries. Describes the uses of the query function in Inuse.
• About Inuse. Displays the version of Insra you are running, as well as Parasoft contact information.

Toolbar

The toolbar contains the following buttons/functions:

Block Color

An important visual aid in Inuse is the use of colors to represent the various properties of the heap. 

• Black (♦) indicates the total memory allocated to the heap. This is usually the amount of memory that gets swapped to disk whenever your application is swapped from memory, regardless of whether or not you are actually using it.
• Blue (♦) denotes leaked blocks as reported by Insure++. This is only available when running Inuse and Insure++ together.
• Green (♦) indicates free space is available to be allocated.
• Red (♦) denotes allocated blocks.
• Yellow (♦) represents "overhead" associated with each block. The system normally keeps a small amount of memory with each allocated (and potentially free) block for its bookkeeping information. This memory cannot be used by the application, although its impact can be reduced by allocating fewer large blocks rather than many small ones.